Category: Guides

  • ๐Ÿ“‚ ,

    Connecting to a VPN in Arch Linux with nmcli

    nmcli is the command line tool for interacting with NetworkManager.

    For work I sometimes need to connect to a vpn using an .ovpn (openvpn) file.

    This method should work for other vpn types (I’ve only used openvpn)

    Installing the tools

    All three of the required programs are available via the official Arch repositories.

    Importing the ovpn file into your Network Manager

    Once you’ve got the openvpn file on your computer, you can import it into your Network Manager configuration with the following command:

    # Replace the file path with your own correct one.
    nmcli connection import type openvpn file /path/to/your-file.ovpn

    You should see a message saying that the connection was succesfully added.

    Activate the connection

    Activating the connection will connect you to the VPN specified with that .ovpn file.

    nmcli connection up your-file

    If you need to provide a password to your vpn connection, you can add the --ask flag, which will make the connection up command ask you for a password:

    nmcli connection up your-file --ask


    To disconnect from the VPN, just run the down command as follows:

    nmcli connection down you-file

    Other Links:

    Network Manager on the Arch Wiki.

  • ๐Ÿ“‚ ,

    Installing and setting up github cli

    What is the github cli

    The Github CLI tool is the official Github terminal tool for interacting with your github account, as well as any open source projects hosted on Github.

    I’ve only just begun looking into it but am already trying to make it part of my personal development flow.


    You can see the installation instructions here, or if you’re running on Arch Linux, just run this:

    sudo pacman -S github-cli

    Once installed, you should be able to run the following command and see the version you have installed:

    gh --version


    Before interacting with your github account, you will need to login via the cli tool.

    Generate a Github Personal Access Token

    Firstly, I generate a personal access token on the Github website. In my settings page I head to “Developer Settings” > “Personal Access Tokens” > “Tokens (classic)”.

    I then create a new “classic” token (just my preference) and I select all permissions and give it an appropriate name.

    Then I create it and keep the page open where it displays the access token. This is for pasting it into the terminal during the authentication flow next.

    Go through the Github CLI authentication flow

    Start the authentication flow by running the command:

    gh auth login

    The following highlights are the options I select when going through the login flow. Your needs may vary.

    What account do you want to log into?
    > Github Enterprise Server
    What is your preferred protocol for Git operations?
    > HTTPS
    > SSH
    Upload your SSH public key to your Github account?
    > /path/to/.ssh/
    > Skip
    How would you like to authenticate Github CLI?
    > Login with a web browser
    > Paste an authentication token

    I then paste in the access token from the still-open tokens page, and hit enter.

    You should see it correctly authenticates you and displays who you are logged in as.

    Check out the official documentation to see all of the available actions you can perform on your account.

  • ๐Ÿ“‚ ,

    Adding Laravel Jetstream to a fresh Laravel project

    I only have this post here as there was a couple of extra steps I made after regular installation, which I wanted to keep a note of.

    Here are the changes made to my Inventory Manager.

    Follow the Jetstream Installation guide

    Firstly I just follow the official installation guide.

    When it came to running the Jetstream install command in the docs, this was the specific flavour I ran:

    php artisan jetstream:install livewire --pest

    This sets it up to use Livewire, as I wanted to learn that along the way, as well as setting up the Jetstream tests as Pest ones.

    Again, I’m not too familiar with Pest (still loving phpunit) but thought it was worth learning.

    Enable API functionality

    I want to build my Inventory Manager as a separate API and front end, so I enabled the API functionality after install.

    Enabling the built-in API functionality, which is Laravel Sanctum by the way, is as easy as uncommenting a line in your ./config/jetstream.php file:

    'features' => [
        // Features::termsAndPrivacyPolicy(),
        // Features::profilePhotos(),
        // Features::teams(['invitations' => true]),

    The Features::api(), line should be commented out by default; just uncomment it and you’re good to go.

    Setup Pest testing

    The only thing that tripped me up was that I hadn’t previously setup pest, which was causing the Jetstream tests to fail.

    So I ran the following command, which is modified for my using Laravel Sail, from the Pest Documentation:

    ./vendor/bin/sail artisan pest:install

    I then also added the RefreshDatabase trait to my ./tests/TestCase.php file.

    Then all of my tests pass.

    That is Jetstream setup and ready to continue for me.

  • ๐Ÿ“‚ ,

    How I organize my Neovim configuration

    The entry point for my Neovim Configuration is the init.lua file.


    My entrypoint file simply requires three other files:

    require 'user.plugins'
    require 'user.options'
    require 'user.keymaps'

    The user.plugins file is where I’m using Packer to require plugins for my configuration. I will be writing other posts around some of the plugins I use soon.

    The user.options file is where I set all of the Neovim settings. Things such as mapping my leader key and setting number of spaces per tab:

    vim.g.mapleader = " "
    vim.g.maplocalleader = " "
    vim.opt.expandtab = true
    vim.opt.shiftwidth = 4
    vim.opt.tabstop = 4
    vim.opt.softtabstop = 4

    Finally, the user.keymaps file is where I set any general keymaps that aren’t associated with any specific plugins. For example, here I am remapping the arrow keys to specific buffer-related actions:

    -- Easier buffer navigation.
    vim.keymap.set("n", "<Left>", ":bp<cr>", { noremap = true, silent = true })
    vim.keymap.set("n", "<Right>", ":bn<cr>", { noremap = true, silent = true })
    vim.keymap.set("n", "<Down>", ":bd<cr>", { noremap = true, silent = true })
    vim.keymap.set("n", "<Up>", ":%bd<cr>", { noremap = true, silent = true })

    In that example, the left and right keys navigate to previous and next buffers. The down key closes the current buffer and the up key is the nuclear button that closes all open buffers.

    Plugin-specific setup and mappings

    For any plugin-specific setup and mappings, I am using Neovim’s “after” directory.

    Basically, for every plugin you install, you can add a lua file within a directory at ./after/plugin/ from the root of your Neovim configuration.

    So for example, to add settings / mappings for the “vim-test” plugin, I have added a file at: ./after/plugin/vim-test.lua with the following contents:

      let test#php#phpunit#executable = 'docker-compose exec -T laravel.test php artisan test'
      let test#php#phpunit#options = '--colors=always'
      let g:test#strategy = 'neovim'
      let test#neovim#term_position = "vert botright 85"
      let g:test#neovim#start_normal = 1
    vim.keymap.set('n', '<Leader>tn', ':TestNearest<CR>', { silent = false })
    vim.keymap.set('n', '<Leader>tf', ':TestFile<CR>', { silent = false })
    vim.keymap.set('n', '<Leader>ts', ':TestSuite<CR>', { silent = false })
    vim.keymap.set('n', '<Leader>tl', ':TestLast<CR>', { silent = false })
    vim.keymap.set('n', '<Leader>tv', ':TestVisit<CR>', { silent = false })

    This means that these settings and bindings will only be registered after the vim-test plugin has been loaded.

    I used to just have extra required files in my main init.lua file, but this feels so much more cleaner in my opinion.

    Update: 9th February 2023 — when setting up Neovim on a fresh system, I notice that I get a bunch of errors from the after files as they are executing on boot, before I’ve actually installed the plugins. I will add protected calls to the plugins soon to mitigate these errors.

  • ๐Ÿ“‚ ,

    Starting a new Laravel 9 project

    Whenever I start a new Laravel project, whether that’s a little side-project idea or just having a play, I try to follow the same process.

    I recently read Steve’s post here on starting your first Laravel 9 Application, so thought I would write down my own setup.

    Whereas Steve’s guide walks you through the beginnings of building a new app, I’m only going to show what I do to get a new project in a ready state I’m happy with before beginning a build.

    This includes initial setup, static analysis, xdebug setup and CI pipeline setup (with Github Actions).


    Before starting, I already have docker and docker-compose installed for my system (Arch Linux BTW).

    Oh and curl is installed, which is used for pulling the project down in the initial setup.

    Other than that, everything that is needed is contained within the Docker containers.

    I then use Laravel’s quick setup from their documentation.

    Initial setup

    Using Laravel’s magic endpoint here, we can get a new Laravel project setup with docker-compose support right out of the box. This could take a little time — especially the first time your run it, as it downloads all of the docker images needed for the local setup.

    curl -s | bash

    At the end of the installation, it will ask you your password in order to finalise the last steps.

    Once finished, you should be able to start up your new local project with the following command:

    cd my-new-site
    ./vendor/bin/sail up -d

    If you now direct your browser to http://localhost , you should see the default Laravel landing page.

    Code style fixing with Laravel Pint

    Keeping a consistant coding style across a project is one of the most important aspects of development — especially within teams.

    Pint is Laravel’s in-house development library to enable the fixing of any deviations from a given style guide, and is actually included as a dev dependancy in new Laravel projects.

    Whether you accept it’s opinionated defaults or define your own rules in a “pint.json” file in the root of your project, is up to you.

    In order to run it, you simply run the following command:

    ./vendor/bin/sail bin pint

    A fresh installation of Laravel should give you no issues whatsoever.

    I advise you to make running this command often — especially before making new commits to your version control.

    Static Analysis with Larastan

    Static analysis is a great method for testing your code for things that would perhaps end up as run time errors in your code later down the line.

    It analyses your code without executing it, and warns of any bugs and breakages it finds. It’s clever stuff.

    Install Larastan with the following command:

    ./vendor/bin/sail composer require nunomaduro/larastan:^2.0 --dev

    Create a file called “phpstan.neon” in the root of your project with the following contents:

        - ./vendor/nunomaduro/larastan/extension.neon
            - app/
        # Level 9 is the highest level
        level: 5

    Then run the analyser with the following command:

    ./vendor/bin/sail bin phpstan analyse

    You can actually set the level in your phpstan.neon file to 9 and it will pass in a fresh Laravel application.

    The challenge is to keep it passing at level 9.

    Line by Line debugging with Xdebug

    At the time of writing, xdebug does come installed with the Laravel sail dockerfiles. However, the setup does need an extra step to make it work fully (at least in my experience)


    There are two parts to xdebug to think about and set up.

    Firstly is the server configuration — this is the installation of xdebug on the php server and setting the correct configuration in the xdebug.ini file.

    The second part is setting up your IDE / PDE to accept the messages that xdebug is sending from the server in order to display the debugging information in a meaningful way.

    I will show here what is needed to get the server correctly set up. However, you will need to look into how your chosen editor works to receive xdebug messages. VS Code has a plugin that is apparently easy to setup for this.

    I use Neovim, and will be sharing a guide soon for how to get debugging with xdebug working in Neovim soon.

    Enable Xdebug in Laravel Sail

    In order to “turn on” xdebug in Laravel Sail, we just need to enable it by way of an environment variable in the .env file.

    Inside your project’s .env file, put the following:


    Unfortunately, in my own experience this hasn’t been enough to have xdebug working in my editor (Neovim). And looking around Stack Overflow et. al, I’m not the only one.

    However, what follows is how I get the xdebug server correctly configured for me to debug in Neovim. You will need to take an extra step or two for your editor of choice in order to receive those xdebug messages and have them displayed for you.

    Publish the Sail runtime files

    One thing Laravel does really well, is creating sensible defaults with the ease of overriding those defaults — and Sail is no different.

    Firstly, publish the Laravel sail files to your project root with the following command:

    ./vendor/bin/sail artisan sail:publish

    Create an xdebug ini file

    After publishing the sail stuff above, you will have a folder in the root of your project called “docker”. Within that folder you will have different folders for each of the supported PHP versions.

    I like to use the latest version, so I would create my xdebug ini file in the ./docker/8.2/ directory, at the time of writing.

    I name my file ext-xdebug.ini, and add the following contents to it. You may need extra lines added depending on your IDE’s setup requirements too.


    Add a Dockerfile step to use the new xdebug ini file

    Within the Dockerfile located at ./docker/8.2/Dockerfile, find the lines near the bottom of the file that are copying files from the project into the container, and add another copy line below them as follows:

    COPY start-container /usr/local/bin/start-container
    COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
    COPY php.ini /etc/php/8.2/cli/conf.d/99-sail.ini
    COPY ext-xdebug.ini /etc/php/8.2/cli/conf.d/ext-xdebug.ini

    Optionally rename the docker image

    It is recommended that you rename the image name within your project’s ./docker-compose.yml file, towards the top:

            context: ./docker/8.2
            dockerfile: Dockerfile
                WWWGROUP: '${WWWGROUP}'
        image: sail-8.2/app
        image: renamed-sail-8.2/app

    This is only if you have multiple Laravel projects using sail, as the default name will clash between projects.

    Rebuild the Image.

    Now we need to rebuild the image in order to get our new xdebug configuration file into our container.

    From the root of your project, run the following command to rebuild the container without using the existing cache.

    ./vendor/bin/sail build --no-cache

    Then bring the containers up again:

    ./vendor/bin/sail up -d

    Continuous Integration with Github Actions

    I use Github for storing a backup of my projects.

    I have recently started using Github’s actions to run a workflow for testing my code when I push it to the repository.

    In that workflow it first installs the code and it’s dependancies. It then creates an artifact tar file of that working codebase and uses it for the three subsequent workflows I run after, in parallel: Pint code fixing; Larastan Static Analysis and Feature & Unit Tests.

    The full ci workflow file I use is stored as a Github Gist. Copy the contents of that file into a file located in a ./.github/workflows/ directory. You can name the file itself whatever you’d like. A convention is to name it “ci.yml”.

    The Github Action yaml explained

    When to run the action

    Firstly I only want the workflow to run when pushing to any branch and when creating pull requests into the “main” branch.

        branches: [ "*" ]
        branches: [ "main" ]

    Setting up the code to be used in multiple CI checks.

    I like to get the codebase into a testable state and reuse that state for all of my tests / checks.

    This enables me to not only keep each CI step separated from the others, but also means I can run them in parallel.

        name: Setting up CI environment
        runs-on: ubuntu-latest
        - uses: shivammathur/setup-php@15c43e89cdef867065b0213be354c2841860869e
            php-version: '8.1'
        - uses: actions/checkout@v3
        - name: Copy .env
          run: php -r "file_exists('.env') || copy('.env.example', '.env');"
        - name: Install Dependencies
          run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
        - name: Generate key
          run: php artisan key:generate
        - name: Directory Permissions
          run: chmod -R 777 storage bootstrap/cache
        - name: Tar it up 
          run: tar -cvf setup.tar ./
        - name: Upload setup artifact
          uses: actions/upload-artifact@v3
            name: setup-artifact
            path: setup.tar

    This step creates an artifact tar file from the project that has been setup and had its dependancies installed.

    That tar file will then be called upon in the three following CI steps, extracted and used for each test / check.

    Running the CI steps in parallel

    Each of the CI steps I have defined — “pint”, “larastan” and “test-suite” — all require the “setup” step to have completed before running.

        name: Pint Check
        runs-on: ubuntu-latest
        needs: setup
        - name: Download Setup Artifact
          uses: actions/download-artifact@v3
            name: setup-artifact
        - name: Extraction
          run: tar -xvf setup.tar
        - name: Running Pint
          run: ./vendor/bin/pint

    This is because they all use the artifact that is created in that setup step. The artifact being the codebase with all dependancies in a testable state, ready to be extracted in each of the CI steps.

        name: Pint Check
        runs-on: ubuntu-latest
        needs: setup
        - name: Download Setup Artifact
          uses: actions/download-artifact@v3
            name: setup-artifact
        - name: Extraction
          run: tar -xvf setup.tar
        - name: Running Pint
          run: ./vendor/bin/pint

    Those three steps will be run in parallel as a default; there’s nothing we need to do there.

    Using the example gist file as is, should result in a full passing suite.

    Further Steps

    That is the end of my starting a new Laravel project from fresh, but there are other steps that will inevitably come later on — not least the Continuous Delivery (deployment) of the application when the time arrises.

    You could leverage the excellent Laravel Forge for your deployments — and I would actually recommend this approach.

    However, I do have a weird interest in Kubernetes at the moment and so will be putting together a tutorial for deploying your Laravel Application to Kubernetes in Digital Ocean. Keep an eye out for that guide — I will advertise that post on my Twitter page when it goes live.

  • ๐Ÿ“‚ ,

    Given, When, Then — how I approach Test-driven development in Laravel

    Laravel is an incredible PHP framework and the best starting point for pretty much any web-based application (if writing it in PHP, that is).

    Along with it’s many amazing features, comes a beautiful framework from which to test what you are building.

    For the longest time I cowered at the idea of writing automated tests for what I built. It was a way of working that was brought in by a previous workplace of mine and my brain fought against it for ages.

    Since that time a few years ago I slowly came to like the idea of testing. Then over the past year or so I have grown to love it.

    I have met some people that are incredibly talented developers, but for me made the prospect of automated testing both confusing and intimidating.

    That was until I came across Adam Wathan’s excellent Test Driven Laravel course. He made testing immediately approachable and broke it down into three distinct phases (per test): “Given”, “When” and “Then”. Also known as “Arrange”, “Act” and “Assert”. I forget which phrase he used, but either way the idea is like this.

    “Given” this environment

    The first step is to set up the “world” in which the test should happen.

    One example would be if you were building an API that would return PlayStation game data to you. In order to return games, there must be games there to return.

    In Laravel we have factories that we can create for quickly creating test entries for our models. Here is an example of a Game model that uses its factory to create a game for us:

    $game = Game::factory()->create([
        'title' => 'The Last of Us part 2',
        'developer' => 'Naughty Dog',

    “When” this thing I want to test happens

    Here you would do the thing that you are testing.

    Maybe that is sending some data to an API endpoint in your application. Or perhaps you are testing a single utility class can do a specific action, so you call the method on that class.

    Here, let’s continue the idea of return games from an api call. We’ll use the $game variable from the previous example and access its ID to build our GET endpoint:

    $response = $this->json('get', '/api/games/' . $game->id,);

    Here the $response variable gets the response from the json get call, allowing you to later make assertions against it.

    “Then” I should see this particular outcome

    In this last step you would make assertions against what has happened. This could be checking if a record exists in a database with specific values, or asserting that an email got sent.

    Basically anything you need to make sure happened, or didn’t happen, for you to be sure you are getting your desired functionality.

    Let’s finish our game example by asserting that we got json back with the expected data. We do this by calling the appropriate method off of the $response variable from the previous example.

        'title' => 'The Last of Us part 2',
        'developer' => 'Naughty Dog',

    The full example test code

    $game = Game::factory()->create([
        'title' => 'The Last of Us part 2',
        'developer' => 'Naughty Dog',
    $response = $this->json('get', '/api/games/' . $game->id,);
        'title' => 'The Last of Us part 2',
        'developer' => 'Naughty Dog',

    Much more to explore

    There is so much to automated testing and I’m still relatively new to it all myself.

    You can “fake” other things in your application in order to not run live things in tests. For example when testing emails are sent you don’t really want to be actually sending emails when you run your tests. Therefore you would “fake” the functionality of sending the mail.

    I hope that this post has been an easy-to-follow intro to how I myself approach testing.

    I have found that even as my tests have gotten more complex in certain situations, I still always stick to the same structural idea:

    1. Given this is the world my code lives in.
    2. When I perform this particular action.
    3. Then I should see this specific outcome.

  • ๐Ÿ“‚ ,

    Preview Laravel’s migrations with the pretend flag

    Here is the command to preview your Laravel migrations without running them:

    cd /your/project/root
    php artisan migrate --pretend

    Laravel’s migrations give us the power to easily version control our database schema creations and updates.

    In a recent task at work, I needed to find out why a particular migration was failing.

    This is when I discovered the simple but super-useful flag --pretend, which will show you the queries that Laravel will run against your database without actually running those migrations.

  • ๐Ÿ“‚

    Giving a flatpak program access to home directory on Linux

    List out all of your installed Flatpaks and copy the “Application ID” for the Flatpak you want to give home directory access to.

    $ flatpak list

    Let’s assume we want to give the program “Insomnia” access to our home directory when it is used.

    The second column is the Application ID.

    The application ID for Insomnia is rest.insomnia.Insomnia.

    To give Insomnia access to your home directory, run the following:

    flatpak override --user --filesystem=home rest.insomnia.Insomnia


    My knowledge of Flatpaks is limited so apologies if I end up being incorrect here.

    Flatpak’ed programs are self-contained installations that are sheltered from the system they are installed on. (Linux / security geeks may need to correct me here).

    By default, they don’t have access to the filesystem of your computer.

    I needed to give my own installation of Insomnia access to my system (just the home directory in my case) so that I could upload a file to it. The command above gives me that result.

    Other online tutorials

    There are some tutorials I’ve seen online that mention similar solutions, except using sudo and not including the --user flag. This didn’t give me the result I was needing.

    You see, without the --user flag, the command will try to update the Flatpak’s global configuration — which is why it needs sudo privileges.

    But by using the --user flag, we are only affecting the configuration for the current user, and so the sudo is not needed.

  • ๐Ÿ“‚

    Setting up Elasticsearch and Kibana using Docker for local development


    Elasticsearch is a super-fast search query program. Kibana is a separate program that can be used for interacting with elasticsearch.

    Here I am setting up both Elasticsearch and Kibana in their own single Docker Containers. I do this as a way to help keep my computer relatively free from being cluttered with programs. Not only that, but since the containers are their own separate self-contained boxes, it also makes it easy to upgrade the Elasticsearch version I am using at a later date.

    Or even remove them entirely with minimal fuss.

    Please note: I am using version 7.10.1 of both programs in the examples below. You can look at each program’s respective docker hub pages to target the exact version you require:

    Just replace any uses of “7.10.1” below with your own version.

    Creating and running containers for the services needed

    Run the two following commands to download and run Elasticsearch locally:

    # Download the Elasticsearch docker image to your computer
    docker pull elasticsearch:7.10.1
    # Create a local container with Elasticsearch running
    docker run -d --name my_elasticsearch --net elasticnetwork -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" -e "" elasticsearch:7.10.1
    # Start the container
    docker container start my_elasticsearch

    And then run the two following commands to download and run Kibana locally:

    # Download the Kibana docker image to your computer
    docker pull kibana:7.10.1
    # Create a local container with Kibana running
    docker run -d --name my_kibana --net elasticnetwork -e ELASTICSEARCH_URL=http://elasticsearch:9200 -p 5601:5601 kibana:7.10.1
    # Start the container
    docker container start my_kibana

    Accessing Kibana

    Since kibana will be connecting to our Elasticsearch container, which it was told to use with the ELASTICSEARCH_URL=http://elasticsearch:9200 section of the Kibana create command, we really only need to use Kibana.

    Kibana has it’s own Devtools for querying Elasticsearch, which so far has been enough for my own usecases.

    head to http://localhost:5601 to access your own Kibana installation.

    Note: You can send curl requests directly to your Elasticsearch from the terminal by targeting the endpoint.

    Deleting the containers

    If you wish to remove Elasticsearch and/or Kibana from your computer, then enter the following commands into your terminal.

    Using Docker for local development makes this a cinch.

    # Stop the Elasticsearch container if it is running
    # (Use it's name you gave it in the "--name" argument as its handle)
    docker container stop my_elasticsearch
    # Delete the Elasticsearch container
    docker container rm my_elasticsearch
    # Stop the Kibana container if it is running
    # (Use it's name you gave it in the "--name" argument as its handle)
    docker container stop my_kibana
    # Delete the Kibana container
    docker container rm my_kibana

    If you need to set up the two programs again, you can just use the create commands shown above to create them as you did originally.

  • ๐Ÿ“‚

    Install MongoDB with Docker for local development

    Pull the docker image for mongo down to your computer.

    docker pull mongo

    Run the mongo container in the background, isolated from the rest of your computer.

    # Command explained below
    docker run -d -p 27017:27017 --name mongodb mongo -v /data/db:/data/db

    What I love about this approach is that I don’t start muddying up my computer installing new programs — especially if it’s just for the purposes of experimenting with new technologies.

    The main run command explained:

    • “docker run -d” tells docker to run in detached mode, which means it will run in the background. Otherwise if we close that terminal it will stop execution of the program docker is running (mongo in this case).
    • “-p 27017:27017” maps your computer’s port number 27017 so it forwards its requests into the container using the same port. (I always forget which port represents the computer and which is the container)
    • “–name mongodb” just gives the container that will be created a nice name. Otherwise Docker will generate and random name.
    • “mongo” is just telling Docker which image to create.
    • “-v /data/db:/data/db” tells Docker to map the /data/db directory on your computer to the /data/db directory in the container. This will ensure that if you restart the container, you will retain the mongo db data.