Connecting to the Database

First, I created a simple Laravel application and selected to use a SQLite database. In PhpStorm, pull up the database tools:

When the tool window appears, we can add our SQLite database:

We are using SQLite in this post, but PhpStorm has support for many different data sources.

Set up the connection to the database, for SQLite, just need to point to the appropriate file in the project.

After hitting OK, we are connected to our database!

Viewing Table Data

I used the UserFactory to create users. By double-clicking the users table in the database tools, we can see all the users.

Looks like there are a lot of professors using our site! 😂

Transposing the Data

The first feature I really like is being able to transpose the data.

This lets you view the table with the columns as rows. It makes it really nice to see the data for individual records.

Query Console

One of the nice features of having databases right in PhpStorm, is you get the advantage of your editor, autocomplete, syntax highlighting, and even AI completion if you use something like Copilot:

The console also persists across sessions per database, so it's easy to just leave previous queries there if you need to re-run them later.

The console also allows defining variables that can be modified each time the query is run:

You can refer to the PhpStorm docs for more information about using parameters: User Parameters | PhpStorm Documentation.

Data Extractors

Data extractors change how copied data is handled. It allows copying rows and columns as a CSV, JSON, Markdown, or even custom extractors.

For example, if we select Markdown, then select data, copy and paste it, we get a nicely formatted Markdown table in the clipboard.

| id | name | email |
| :--- | :--- | :--- |
| 1 | Ana Lesch IV | lrogahn@example.net |
| 2 | Mateo Trantow | ullrich.deborah@example.com |
| 3 | Jeanie Altenwerth | marcelle00@example.com |
| 4 | Prof. Brad Koch | elise.paucek@example.net |
| 5 | Prof. Reva Jast IV | jmayert@example.com |
| 6 | Buford Stracke | ora07@example.net |
| 7 | Agnes O'Conner | lillian95@example.org |
| 8 | Korey Spencer PhD | schmeler.fleta@example.com |
| 9 | Dr. Celestino Fisher | grimes.ada@example.com |
| 10 | Orin Keeling | bgrant@example.org |

If you've used Laravel's job queue and ever needed to retry a lot of jobs, you have to use something like the following command:

php artisan queue:retry 825d691e-8a75-403a-98d4-afc0da6474c0 565faa3f-dad4-40c2-b0d5-cf9c783f6643 7aec1085-11a8-441d-8218-d65f5f60382a

This retries three jobs using their UUID from the failed_jobs table. With a custom data extractor, we can easily copy the UUID's from the table in the proper format (no quotes, no commas, one space between UUIDs).

If we use the “One-row” data extractor, this gets us close, but notice it includes quotes and commas, which don't work in the retry command.

'825d691e-8a75-403a-98d4-afc0da6474c0', '565faa3f-dad4-40c2-b0d5-cf9c783f6643', '7aec1085-11a8-441d-8218-d65f5f60382a'

So, let's create a new version of the extractor.

Copy the One-row.sql.groovy script, and then we can easily modify for our needs.

Make sure to move the new file into the extractors folder so PhpStorm can find it.

It might look complicated, but all we really need to do is change the separator and quote to a space and empty, respectively.

Now, if we select our new extractor and copy the UUIDs, we get the format we require for the command.

825d691e-8a75-403a-98d4-afc0da6474c0 565faa3f-dad4-40c2-b0d5-cf9c783f6643 7aec1085-11a8-441d-8218-d65f5f60382a

Diagrams

The last feature I will discuss in this article is auto-generated database diagrams. For example, to create a diagram for our entire database, select the database and choose diagrams.

Final Thoughts

PhpStorm is extremely powerful and offers a ton of different features and tools. I keep learning new things all the time, especially with the database tools. I highly recommend further exploring the database tools on your own to help refine your workflows.

Let me know if you have any other helpful tips about the database features in PhpStorm or any questions I can help answer. Thanks for reading!

class ProjectFactory extends Factory
{
    protected $model = Project::class;

    public function definition(): array
    {
        return [
            'title' => $this->faker->sentence(),
            'description' => $this->faker->paragraph(),
            'team_id' => Team::factory(),
            'user_id' => User::factory(),
        ];
    }
}

The problem with this is the Team factory is creating its own User and now the User factory created a user, and they are not related.

The next iteration could look like this:

class ProjectFactory extends Factory
{
    protected $model = Project::class;

    public function definition(): array
    {
        $team = Team::factory()->create();

        return [
            'title' => $this->faker->sentence(),
            'description' => $this->faker->paragraph(),
            'team_id' => $team->id,
            'user_id' => $team->user_id,
        ];
    }
}

This works and gives us what we want, or does it?

It will give us a Project with a User and Team that are related. However, what happens if we were using the factory and we already knew the team? Something like the following:

$project = Project::factory()
    ->for($previouslyCreatedTeam, 'team')
    ->for($previouslyCreatedTeam->owner, 'user')
    ->create();

If we look in the database, we should see a single user, team, and project record. However, looking at the users table, I have two users:

In the teams table, I have two teams!

What happened?

The issue is, any time the factory runs, it calls the definition method, and then it looks at the fields that were passed to the factory to see which fields of the definition it needs to use. When the definition method is called, though, nothing is preventing it from calling the Team factory and creating a Team and User.

class ProjectFactory extends Factory
{
    protected $model = Project::class;

    public function definition(): array
    {
        // This runs regardless of the fields provided
        // to the factory, creating extra teams and users
        // when not necessary.
        $team = Team::factory()->create();

        return [
            'title' => $this->faker->sentence(),
            'description' => $this->faker->paragraph(),
            'team_id' => $team->id,
            'user_id' => $team->user_id,
        ];
    }
}

How do we fix this?

It’s actually right in the Laravel docs.

If the relationship's columns depend on the factory that defines it you may assign a closure to an attribute.

So to fix it, we can use a closure to get the User from the Team factory used in the definition:

class ProjectFactory extends Factory
{
    protected $model = Project::class;

    public function definition(): array
    {
        return [
            'title' => $this->faker->sentence(),
            'description' => $this->faker->paragraph(),
            'team_id' => Team::factory(),
            // Fetch the user_id from the team that was 
            // generated in the factory above.
            'user_id' => fn (array $attributes) => Team::find($attributes['team_id'])->user_id,
        ];
    }
}

This is a bit of an edge case and doesn’t frequently happen, so it’s easy to miss in the docs. I hope this helps, and now you can go and improve your factories. Thanks for reading!

In my project, I have a checkout_events table where I track various options and properties of a user's checkout. It’s primarily for debugging purposes, but maybe one day, it could grow into an event sourcing flow.

In the table, I have a metadata column and I want to track things like processor, checkoutSource, checkoutType, errorMessage, and exceptionClass. As things change or grow, I knew the different properties could change, which is why I opted for a JSON column versus a dedicated column for each property.

To make sure I have the correct data going in and out of the table, I created the DTO below:

<?php

readonly class CheckoutMetadata
{
    public function __construct(
        public Processor $processor,
        public CheckoutSource $checkoutSource,
        public CheckoutType $checkoutType,
        public ?string $errorMessage = null,
        public ?string $exceptionClass = null,

    ) {}
}

Notice, the $errorMessage and $exception properties are nullable since the event won’t always have that metadata.

Now, for the model, we need to add a cast for this:

<?php

class CheckoutEvents extends Model
{
    protected function casts(): array
    {
        return [
            'metadata' => CheckoutMetadata::class,
        ];
    }
}

Now, to actually make this work, we could create a Cast in Laravel as shown in the docs. However, I am going to opt for making the DTO itself be Castable (docs) and use anonymous cast classes (docs). To achieve this, CheckoutMetadata needs to implement Illuminate\Contracts\Database\Eloquent\Castable. The contract requires a castUsing method that returns a new class instance that implements Illuminate\Contracts\Database\Eloquent\CastsAttributes:

<?php

class CheckoutMetadata implements Castable
{
    public function __construct(
        public Processor $processor,
        public CheckoutSource $checkoutSource,
        public CheckoutType $checkoutType,
        public ?string $errorMessage = null,
        public ?string $exceptionClass = null,
    ) {}

    public static function castUsing(array $arguments): CastsAttributes
    {
        return new class implements CastsAttributes
        {
            // Get method is called when getting metadata from the model.
            public function get(Model $model, string $key, mixed $value, array $attributes)
            {
                // Convert the JSON data from the database into an object.
                $data = json_decode($attributes[$key]);

                return new CheckoutMetadata(
                    processor: Processor::from($data->processor),
                    checkoutSource: CheckoutSource::from($data->checkout_source),
                    checkoutType: CheckoutType::from($data->checkout_type),
                    errorMessage: data_get($data, 'error_message'),
                    exceptionClass: data_get($data, 'error_message'),
                );
            }

            // Set method is called when updating the metadata field on the model.
            public function set(Model $model, string $key, mixed $value, array $attributes): array
            {
                // Throw an exception if trying to set a value that is not an instance of CheckoutMetadata.
                if (! $value instanceof CheckoutMetadata) {
                    throw new InvalidArgumentException('A CheckoutMetadata instance is required.');
                }

                $data = [
                    'processor' => $value->processor->value,
                    'checkout_source' => $value->checkoutSource->value,
                    'checkout_type' => $value->checkoutType->value,
                    'error_message' => $value->errorMessage,
                    'exception_class' => $value->exceptionClass,
                ];

                // JSON encode the data to store in the database.
                return [$key => json_encode($data)];
            }
        };
    }
}

Quite a lot of new stuff here. The get method of the anonymous class gets called when we try to get the metadata property from the model, like $checkoutModel->metadata. We need to decode the JSON from the database and then instantiate a new CheckoutMetadata class instead. Now, anytime we call $checkoutModel->metadata, we get the CheckoutMetadata class and know what properties we have available.

The set method is used when we try to update the metadata property, so: $checkoutModel->metadata = $checkoutMetadata. Since we always want to require data to be in the form of CheckoutMetadata, we throw an InvalidArgumentException if the value passed in is not an instance of CheckoutMetadata.

Now, our model can be used like the following:

<?php

$metadata = new CheckoutMetadata(
  checkoutSource: CheckoutSource::Brick,
  checkoutType: CheckoutType::OneTime,
  processor: Processor::Braintree
);

$model = new CheckoutEvent();
$model->name = 'New Event';
$model->user_id = 1;
$model->metadata = $metadata;
$model->save();

$model->metadata;

// App\CheckoutMetadata {#2744
//    +processor: App\Processor {#2746
//      +name: "Braintree",
//      +value: 2,
//    },
//    +checkoutSource: App\CheckoutSource {#2750
//      +name: "Brick",
//      +value: 2,
//    },
//    +checkoutType: App\CheckoutType {#2748
//      +name: "OneTime",
//      +value: 2,
//    },
//    +errorMessage: null,
//    +exceptionClass: null,
//  }

In the future, if we wish to add properties that we will track, we can add new optional properties to the DTO and update the anonymous CastAttributes class. If we want to remove properties, we can just delete them from the DTO and update the anonymous CastsAttributes class.

For further learning, look into the Arrayable and JsonSerializable interfaces in Laravel so you can return the DTO to an expected structure when converting a model to an array or JSON. You can also read about Array / JSON Serialization in Laravel.

I hope you enjoyed this post and learned something new about Eloquent attribute casting and JSON fields. They can be powerful, but it’s important to make sure the data being passed in and out of the field is what you expect. You don’t want it to blow up with countless unknown properties and different structures in each row.

Thanks for reading!

Furthermore, if you’d like to learn more about data transfer objects, read my post Streamlining API Responses in Laravel with DTOs.

In this post, I will be using Neovim with LazyVim. LazyVim is a fantastic Neovim setup with many features and tools out of the box. I’ve spent more time than I’d like to admit configuring Vim and Neovim. LazyVim cuts almost all that time out. As you start to become comfortable configuring LazyVim, you can consider creating your own configuration from scratch.

Installation

This post assumes you are using the latest version of Neovim (v0.10.0 at the time of publishing). If you need to install it, you can grab it for your OS here.

Once you have Neovim installed, we are going to use LazyVim. You are welcome to use your configuration if you would rather not use LazyVim, but that setup is a lot more complex for this post.

To install LazyVim, you’ll want to clone the repo and move it to your Neovim configuration folder, (~/.config/nvim on MacOS/Linux).

git clone https://github.com/LazyVim/starter ~/.config/nvim

Once cloned, you can remove the .git folder since you won’t need it now and may want to version control your configuration changes.

rm -rf ~/.config/nvim/.git

If you are using Windows, you can follow the installation instructions here.

Once that is done, you can run Neovim, and it will pull down all the plugins and dependencies for LazyVim

Out of the box, LazyVim gives a nice menu to navigate around as needed.

LazyVim PHP Extras

LazyVim recently added an update to quickly add PHP support. You just need to click x from the home screen to get to the extras menu or type :LazyExtras.

From the menu, you can search for PHP by first typing a slash, then php, so /php. The / begins searches in Neovim.

With your cursor on the lang.php line, hit x to toggle the extra. Then restart Neovim. Now, Neovim will support PHP syntax and install the Phpactor LSP.

To test the LSP, I created a new Laravel project with Laravel Breeze. From the project directory, open Neovim and open the ProfileController by using <leader>ff. In Neovim, many keyboard commands are prefixed with the <leader> key, which is set to space by default. So to find a file, type space + f + f. Then, you can just search using the fuzzy finder.

When loading the controller for the first time, Phpactor will start to index your codebase, typically from the Git root of the project.

You’ll also see many errors and other diagnostics. These are being provided by the LSP along with code completion, go to definition, refactoring, and many other features.

If you want to modify the base controller, you can navigate to Controller and click gd for Goto Definition.

After Goto Definition, you can go back down to the class definition and click gr to Goto References for the Controller class. Next, you can use ctrl+o to jump back to your previous locations.

Please don't hesitate to keep using Phpactor if it works for you. It struggles with some of the magic and missing types in Laravel but it is completely free and open source. You can improve this by using something like Laravel IDE Helper which generates stubs for models, facades, and other framework features to give better auto-completion.

Personally, I’ve had a better experience using the Intelephense LSP, which you're probably familiar with if you’re coming from VSCode. Unfortunately, you do miss some features of Phpactor without the premium version of Intelephense, so I do recommend the purchase if you use Intelephense. A single license works VSCode, Neovim, and any other editors that support LSPs.

To set up Intelephense, you’ll need to modify the LazyVim configuration. In the ~/.config/nvim folder, open options.lua and add the following line:

vim.g.lazyvim_php_lsp = "intelephense"

This tells LazyVim to set up Intelephense. You may need to remove Phpactor, though. To accomplish that, you can type <leader>cm which opens Mason. Mason is a tool for installing various formatters, linters, and LSPs. From the Mason menu, find Phpactor and uninstall it by using X.

Setup Laravel Pint Formatting

Since we installed the Lazy Extras for PHP, Laravel Pint and PHP-CS-Fixer have been installed. However, PHP-CS-Fixer is set as the default. To change this, we can create a new file in the Neovim config: ~/.config/nvim/lua/plugins/php.lua. You can name this file whatever you want, but for this post, we’ll use it for all of our PHP/Laravel related configuration.

In the file, you can include the following:

return {
  {
    "stevearc/conform.nvim",
    optional = true,
    opts = {
      formatters_by_ft = {
        php = { { "pint", "php_cs_fixer" } },
      },
    },
  },
}

This makes Pint the default formatter, and it will fall back to PHP-CS-Fixer if not found. With this change, I can go back to the ProfileController and add an unused import and mess up indentation, and saving will trigger a format.

Another optional change you can make is to remove phpcs if you don’t use it. In the php.lua file, just add another block like the following:

return {
  {
    -- Set Laravel Pint as the default PHP formatter with PHP CS Fixer as a fall back.
    "stevearc/conform.nvim",
    optional = true,
    opts = {
      formatters_by_ft = {
        php = { { "pint", "php_cs_fixer" } },
      },
    },
  },
  {
    -- Remove phpcs linter.
    "mfussenegger/nvim-lint",
    optional = true,
    opts = {
      linters_by_ft = {
        php = {},
      },
    },
  },
}

I am grabbing these configurations right from the LazyVim docs.

Testing

Next, we’ll set up Neatest so we can run tests from right in Neovim. This is another LazyVim extra that can be added by typing :LazyExtras and then searching for “test.core” and toggling with X.

Then, we need to install the Neotest Pest plugin. Add the following block to the php.lua configuration.

return {
  {
    ...
  },
  {
    -- Add neotest-pest plugin for running PHP tests.
    -- A package is also available for PHPUnit if needed.
    "nvim-neotest/neotest",
    dependencies = { "V13Axel/neotest-pest" },
    opts = { adapters = { "neotest-pest" } },
  }
}

With the testing config in place, load up a test file, and you can run individual tests with <leader>tr or the whole file with <leader>tt.

Use <leader>to to toggle a summary of the test results.

Blade Syntax

Adding support for Laravel Blade is a little more involved. LazyVim has Treesitter setup to support syntax highlighting for most languages. However, Blade is not installed by default, so we need to add it.

return {
  {
    ...
  },  
  {
    -- Add a Treesitter parser for Laravel Blade to provide Blade syntax highlighting.
    "nvim-treesitter/nvim-treesitter",
    opts = function(_, opts)
      vim.list_extend(opts.ensure_installed, {
        "blade",
        "php_only",
      })
    end,
    config = function(_, opts)
      vim.filetype.add({
        pattern = {
          [".*%.blade%.php"] = "blade",
        },
      })

      require("nvim-treesitter.configs").setup(opts)
      local parser_config = require("nvim-treesitter.parsers").get_parser_configs()
      parser_config.blade = {
        install_info = {
          url = "https://github.com/EmranMR/tree-sitter-blade",
          files = { "src/parser.c" },
          branch = "main",
        },
        filetype = "blade",
      }
    end,
  },
}

We extend the default Treesitter config to set a new filetype and pull down the Blade parser.

Once we restart Neovim, you can run :TSInstall blade to download the parser.

Next, we need to add some Treesitter queries for better code support. To achieve this, we have to create some new files from within Neovim.

Blade Injections

Type :TSEditQuery injections blade and add the following contents:

((text) @injection.content
    (#not-has-ancestor? @injection.content "envoy")
    (#set! injection.combined)
    (#set! injection.language php))

; tree-sitter-comment injection
; if available
((comment) @injection.content
 (#set! injection.language "comment"))

; could be bash or zsh
; or whatever tree-sitter grammar you have.
((text) @injection.content
    (#has-ancestor? @injection.content "envoy")
    (#set! injection.combined)
    (#set! injection.language bash))

((php_only) @injection.content
    (#set! injection.language php_only))

((parameter) @injection.content                                                                                                 
    (#set! injection.include-children) ; You may need this, depending on your editor e.g Helix                                                                                          
    (#set! injection.language "php-only"))

Blade Highlights

Type :TSEditQuery highlights blade and add:

(directive) @tag
(directive_start) @tag
(directive_end) @tag
(comment) @comment

Blade Folds

Type :TSEditQuery folds blade and add:

((directive_start) @start
    (directive_end) @end.after
    (#set! role block))


((bracket_start) @start
    (bracket_end) @end
    (#set! role block))

HTML Injections

Finally, we’ll add some injection queries for Alpine support. Type :TSEditQuery and add:

;; extends

; AlpineJS attributes
(attribute
  (attribute_name) @_attr
    (#lua-match? @_attr "^x%-%l")
  (quoted_attribute_value
    (attribute_value) @injection.content)
  (#set! injection.language "javascript"))

; Blade escaped JS attributes
; <x-foo ::bar="baz" />
(element
  (_
    (tag_name) @_tag
      (#lua-match? @_tag "^x%-%l")
  (attribute
    (attribute_name) @_attr
      (#lua-match? @_attr "^::%l")
    (quoted_attribute_value
      (attribute_value) @injection.content)
    (#set! injection.language "javascript"))))

; Blade PHP attributes
; <x-foo :bar="$baz" />
(element
  (_
    (tag_name) @_tag
      (#lua-match? @_tag "^x%-%l")
    (attribute
      (attribute_name) @_attr
        (#lua-match? @_attr "^:%l")
      (quoted_attribute_value
        (attribute_value) @injection.content)
      (#set! injection.language "php_only"))))

Now, after adding everything, saving and restarting, you should now have syntax highlighting for Blade files!

For more information and installation instructions, visit the repo for the Blade Treesitter parser.

Snippets

LazyVim comes with a plugin to easily create snippets. To create PHP snippets, you can create a new file: ~/.config/nvim/snippets/php.json similar to the example below:

{
  "strict types": {
    "prefix": "strict",
    "description": "Add strict types declaration",
    "body": [
      "declare(strict_types=1);"
    ]
  },
  "inv": {
    "prefix": "inv",
    "description": "Create PHP __invoke method",
    "body": [
      "public function __invoke(${1}): ${2:void}",
      "{",
      "    ${3}",
      "}",
      ""
    ]
  },
  "public method": {
    "prefix": "pubf",
    "description": "Create a public method",
    "body": [
      "public function ${1}(${2}): ${3:void}",
      "{",
      "    ${0}",
      "}",
      ""
    ]
  },
  "protected method": {
    "prefix": "prof",
    "description": "Create a protected method",
    "body": [
      "protected function ${1}(${2}): ${3:void}",
      "{",
      "    ${0}",
      "}",
      ""
    ]
  },
  "private method": {
    "prefix": "prif",
    "description": "Create a private method",
    "body": [
      "private function ${1}(${2}): ${3:void}",
      "{",
      "    ${0}",
      "}",
      ""
    ]
  },
  "public static method": {
    "prefix": "pubsf",
    "description": "Create a public static method",
    "body": [
      "public static function ${1}(${2}): ${3:void}",
      "{",
      "    ${0}",
      "}",
      ""
    ]
  },
  "pest test (it) method": {
    "prefix": "it",
    "description": "Create a pest test",
    "body": [
      "it('${1}', function () {",
      "    // Arrange",
      "    ${0}",
      "",
      "    // Act",
      "",
      "    // Assert",
      "",
      "});"
    ]
  }
}

You can add any other snippets you might want to this file, or create files for other languages to add snippets.

Additional Plugins

Laravel.nvim

This plugin can be used to quickly run Artisan commands with a great search feature using <leader>la. Or you can list all the routes in your application using <leader>lr.

return { 
  {
    ...
  },
  {
    -- Add the Laravel.nvim plugin which gives the ability to run Artisan commands
    -- from Neovim.
    "adalessa/laravel.nvim",
    dependencies = {
      "nvim-telescope/telescope.nvim",
      "tpope/vim-dotenv",
      "MunifTanjim/nui.nvim",
      "nvimtools/none-ls.nvim",
    },
    cmd = { "Sail", "Artisan", "Composer", "Npm", "Yarn", "Laravel" },
    keys = {
      { "<leader>la", ":Laravel artisan<cr>" },
      { "<leader>lr", ":Laravel routes<cr>" },
      { "<leader>lm", ":Laravel related<cr>" },
    },
    event = { "VeryLazy" },
    config = true,
    opts = {
      lsp_server = "intelephense",
      features = { null_ls = { enable = false } },
    },
  },
}

Blade-Nav.nvim

Adds the ability to use Goto File on Blade views to jump to components and other views using gf.

return { 
  {
    ...
  },
  {
    -- Add the blade-nav.nvim plugin which provides Goto File capabilities
    -- for Blade files.
    "ricardoramirezr/blade-nav.nvim",
    dependencies = {
      "hrsh7th/nvim-cmp",
    },
    ft = { "blade", "php" },
  },
}

Additional Tips

One giant benefit of LazyVim is the documentation. If there’s something you’re used to doing in VSCode and you want it in Neovim, there’s a chance LazyVim may already have that built-in. I recommend just going through each section in LazyVim to learn more about it.

Probably one of the most important sections is the keymaps. LazyVim uses which-key.nvim to help you remember the configured keycaps while you’re in the editor, but for a complete list, click here.

Do you want Git support? LazyVim has that covered with LazyGit which is a really nice terminal UI for Git. Use <leader>gg to open it. You can even install LazyGit directly using something like Homebrew to just run right on the command line using lazygit.

Need additional tooling like PHPStan or Psalm? Use <leader>cm or :Mason to bring up the Mason menu and search for what you need. It has may popular linters and formatters available to install.

Additional Resources

LazyVim Docs

Like I mentioned above, LazyVim provides amazing documentation and it’s definitely worth a read.

Neovim as a PHP and JavaScript IDE

Jess Archer has a fantastic course for setting up Neovim on Laracasts. If you are not subscribed to Laracasts, I cannot recommend it enough. I’ve been a lifetime user since 2017. If it’s something you’re interested in, please use my referral link.

Omakub

DHH (the creator of Ruby on Rails) created the Omakub package as a quick way to set up a development environment on Ubuntu Linux. Even if you’re not using Ubuntu, the repo for Omakub is worth checking out as it has a lot of nice configurations and tools, one of which being Neovim with LazyVim.

Kickstart.nvim

If you want something a bit more minimal than LazyVim, then Kickstart.nvim is a good start. You can watch this video by TJ DeVries about how to get started. Even if you want to keep using LazyVim, this is still a great resource to learn more about configuring Neovim.

Summary

I hope this helps get you started on your Neovim journey. It’s a powerful editor that is infinitely configurable. Though not as powerful as something like PhpStorm, it can get you pretty close for free and requires less CPU resources.

Even if you don’t plan to use Neovim as your primary editor, I think it can still be beneficial to learn the keybindings. I typically split my time between Neovim and PhpStorm and try to keep my keybindings as similar as possible. Luckily, the IdeaVim plugin for JetBrains IDEs makes this simple.

For your reference, I created a repo with all the files we created in this post.

Please let me know if you have any other questions about the setup or any additional features I might have missed.

Thanks for reading!

Typically, when using query scopes in Laravel, the simple way is to use the scope prefix on a method in the model, like the following:

class Posts 
{        
    public function scopePublished(Builder $query): void
    {
        $query->where('published_at', '<=', now());
    }
}

$publishedPosts = Posts::published()->get();

This works well, but it does make it harder for the IDE to handle unless you’re using something like the Laravel IDE Helper package.

To convert this into a tappable scope, we can do something like the following:

// app/Scopes/Published.php

class Published
{
    public function __invoke(Builder $query): void
    {
        $query->where('published_at', '<=', now());
    }
}

$publishedPosts = Posts::tap(new Published)->get();

Using the tappable scope changes the following:

// With regular query scope
$publishedPosts = Posts::published()->get();

// With tappable scope
$publishedPosts = Posts::tap(new Published)->get();

The top one looks nicer, however, the IDE will not be able to easily see what the published method does since it using the magic scope prefix, whereas with the tappable scope version, you can easily click into Published and see exactly what’s happening.

Also, using the tappable scope allows it to be easily reused. For example, if you had a Comment model, that also included a published_at column, then to get just published comments, you can use the same scope from before:

$comments = Comment::tap(new Published)->get();

Now, let’s take these scopes to the next level by adding custom parameters.

Using are same Post and Comment models, let’s assume both include a user_id field. To handle that with a tappable scope, create the following:

// app/Scopes/ByUser.php

class ByUser
{
    public function __construct(private readonly int $userId)
    {
    }

    public function __invoke(Builder $query): void
    {
        $query->where('user_id', $this->userId);
    }
}

With the new tappable scope, we can fetch posts and comments for a user shown below:

$userId = 1;

$posts = Post::tap(new ByUser($userId))->get();

$comments = Comment::tap(new ByUser($userId))->get();

The above examples are relatively simple, and maybe it’s easier to just use normal where methods for those, so maybe they are not the best cases for tappable scopes, but I wanted to use the simple examples as an introduction. Now let’s create a tappable scope for something a little more complex.

On our home page, we want to show the latest published posts with the author and comment count. This query could look like the following:

$posts = Post::query()
    ->with(['user', 'comments'])
    ->where('published_at', '<=', now())
    ->latest('published_at')
    ->limit(10)
    ->get();

This works, but the query is starting to get kind of large. We also fetch the entire user model for each post and all the comments, when really all we want is a name and count. Also, we are counting unpublished comments which we don’t want. So let’s adjust:

$posts = Post::query()
    ->select('posts.*')
    ->join('users', 'users.id', '=', 'posts.user_id')
    ->withAggregate('user', 'name')
    ->withCount(['comments' => fn (Builder $query) => $query->where('published_at', '>=', now())])
    ->where('published_at', '<=', now())
    ->latest('published_at')
    ->limit(10)
    ->get();

This gives us exactly what we want, an array of posts with the following structure:

[
    0 => [    
        'id' => 69,
        'user_id' => 360,
        'name' => '...',
        'body' => '...',
        'published_at' => '2024-04-20 03:18:37',
        'created_at' => '2024-04-21T18:44:24.000000Z',
        'updated_at' => '2024-04-21T18:44:24.000000Z',
        'user_name' => 'Janae Luettgen',
        'comments_count' => 2,
    ],
    1 => [...]
    ...
]

This is great, but now our query is pretty complex. Imagine different parts of our application need to show a limit of 5 posts instead of 10. Or maybe we want to only find a count of unpublished comments. Let’s create a tappable scope:

// app/Scopes/LatestPosts.php

class LatestPosts
{
    public function __construct(private readonly int $limit = 10, private readonly bool $publishedComments = true)
    {
    }

    public function __invoke(Builder $query): void
    {
        $query->select('posts.*')
            ->join('users', 'users.id', '=', 'posts.user_id')
            ->withAggregate('user', 'name')
            ->withCount([
                    'comments' => fn (Builder $query) => $query
                        ->when(
                            $this->publishedComments,
                            fn(Builder $query) => $query->where('published_at', '>=', now())
                        )
                ]
            )
            ->where('published_at', '<=', now())
            ->latest('published_at')
            ->limit($this->limit);
    }
}

Now, instead of having to copy and paste this large query wherever we need it, it is encapsulated in a single place and we can fetch our latest posts like below:

$latestPosts = Post::tap(new LatestPosts(limit: 10, publishedComments: true))->get();

I hope this helps you in your Laravel career. It’s a clean way to remove some of the magic of the built-in Laravel query scopes and allows for easy reuse and abstracting complex queries.

Thanks for reading!

Related Links

• Unorthodox Eloquent - Muhammed Sari

• Laravel IDE Helper

• Laravel - Local Scopes

To start with, I was just using Laravel’s Cache facade, like below:

Cache::remember(
    'unique-key', 
    60, // cache lives for 60 seconds
    fn () => $this->operationToBeCached()
);

Cache::remember is really nice because it will pull from the cache if it exists or regenerate the value using the closure, put it in the cache, and return it.

Let’s say this cache is for a user and when the data involved changes, I need to forget the cache. It’s not too hard, just use the forget method.

Cache::forget('unique-key');

The problem I started running into though is trying to remember that unique key. I don’t like having magic strings used throughout the app to set or remove items from the cache. It gets even more difficult when the unique key needs to include additional data like model IDs.

To solve this, I created a CacheHelper class.

<?php

namespace App\Cache;

use Illuminate\Support\Facades\Cache;

abstract class CacheHelper
{
    protected string $key; // Cache key
    protected int $ttl = 60; // Time to live

    public function getKey(): string
    {
        return $this->key;
    }

    public function value(): mixed // Store and fetch value from cache
    {
        return Cache::remember(
            $this->getKey(),
            $this->ttl,
            fn () => $this->generate()
        );
    }

    public function forget(): bool // Forget value from the cache
    {
        return Cache::forget($this->getKey());
    }

    abstract protected function generate(): mixed; // Abstract method for generating cache value
}

The CacheHelper class is abstract, so it must be extended and include a generate method. I also created a trait that allows easily setting unique keys using an ID.

<?php

namespace App\Cache;

trait CacheIdentifier
{
    protected int|string|null $identifier = null;

    public function getKey(): string
    {
        return sprintf($this->key, $this->identifier); // Attach an identifier to the cache key.
    }
}

Here’s an example below on how this can be extended.

<?php

namespace App\Cache;

use App\Models\User;
use Illuminate\Support\Collection;

class UserExpensiveComputationCache extends CacheHelper
{
    use CacheIdentifier;

    protected string $key = 'expensive_computation_:%s';
    protected int $ttl = 60;

    public function __construct(protected readonly User $user)
    {
        $this->identifier = $user->id; // The identifier is the user ID and is attached to the key.
    }

    public static function make(User $user): static
    {
        return new static($user); // Simple helper to create a new instance
    }

    protected function generate(): Collection
    {
        return $this->user->expensiveComputation();
    }
}

With this set, whenever I need to access the expensive computation, I can use my cache class:

<?php

$user = User::find(1);
$value = UserExpensiveComputationCache::make($user);

The UserExpensiveComputationCacheclass will remember the value for the user I passed to it.

When it comes time to clear the cache because a related record was modified, I can just do the following:

<?php

UserExpensiveComputationCache::make($user)->forget();

I no longer need to remember a magic string throughout my application. I just have a simple class that I can instantiate and use it to handle my unique keys, setting, and forgetting the cache. If I have to change the key for whatever reason, it only happens in this one place in the application and I don’t have to search around for other instances of the key.

I was able to throw this CacheHelper class together pretty quickly, and it solved my problem of avoiding magic strings across my application and being able to easily manage forgetting the cache when needed. Using dedicated classes to cache items isn’t something I have seen used before. Please let me know if you’ve seen something similar or have other ideas and strategies for managing cache. Thanks for reading!

Starting off, here's something I read at the end of the month from Aaron Francis: Do literally anything - Aaron Francis. This one resonates with me. I am always thinking of new projects I want to work on and hobbies I want to start. I've been thinking about getting into woodworking, I've been thinking about landscape improvements, and this is on top of my job, my side work, and my family. What ends up happening is I overwhelm myself and then sit in frustration thinking I can't get anything done. Instead, if I just do something, even if it isn't a lot, it is still a step in the right direction and builds momentum to keep doing more. So this will be something I keep in the back of my mind when I get overwhelmed.

Here's an article by Rob Owen: It's OK to abandon your side-project - Robb Owen. In the article, Rob describes working on a project and once he had it launched, he abandoned it. He was building an application to help him practice with a foreign language and by doing all the work to build the application, he ended up learning what he was hoping to use the application to teach. So it was more about the experience of building the application itself versus having a completed application.

On to a different topic, here's one by Nikita Prokopov: JavaScript Bloat in 2024 @ tonsky.me. It's shocking to see how much JavaScript is being loaded on different sites. What is Slack doing downloading 55 MB worth of JavaScript?! It seems like over the last few years, we are starting to see a shift in frontend development with tools like Laravel Livewire and React server components, we are starting to move back to servers doing more of the work versus the client. I spend more time working on backend code, so this is exciting for me. Hopefully, we'll start to see this JavaScript bloat start to go down. However, I'd be more excited for just the complexity of the front end to go down. Over the last year and a half, I've been primarily doing backend work and I feel like I am so behind on the latest frontend tools, but when I start to look into it, I just think, why has this become so difficult and I have years of experience in Vue, React, Angular, jQuery, etc. Is it time to get back on jQuery now that 4.0 is coming: jQuery 4.0.0 BETA! | Official jQuery Blog 😂?

This article from Cory Doctorow: ‘Enshittification’ is coming for absolutely everything is a bit of a depressing read. It discusses how platforms, that start great and provide a lot of value to their users, start to degrade. It does end on a positive by discussing the "anti-enshittification" movement.

The last article I have for this month is from Paul Redmond at Laravel News: Five Tools That Will Make You More Productive on the Command Line - Laravel News. I learned about some new CLI tools I haven't used before. Zoxide has been an amazing find to make moving around paths more efficient. Also, Paul mentions fzf-tab. I have been using fzf for a long time with Vim/Neovim, but fzf-tab is great for completing items in the CLI.

Article List

Here's a quick list of the articles I described above:

• Do literally anything - Aaron Francis

• It's OK to abandon your side-project - Robb Owen

• JavaScript Bloat in 2024 @ tonsky.me

• ‘Enshittification’ is coming for absolutely everything

• Five Tools That Will Make You More Productive on the Command Line - Laravel News

RSS Feeds

If you found any of the above articles interesting, here's a list of RSS feeds to subscribe to:

• aaronfrancis.com/feed

• robbowen.digital/feed.xml

• tonsky.me/atom.xml

• Laravel News

Other Articles

Here are some other interesting articles I read over February.

• Where I’m at on the whole CSS-Tricks thing – Chris Coyier

• PeakD

• A dozen thoughts about AI - daverupert.com

• How I take notes: Structure with Now Next Notes | Sebastian De Deyne

• Watch out for this when testing Artisan commands | Mastering Laravel

• Please, don’t force me to log in : Juha-Matti Santala

• For each loops with LATERAL Joins - Database Tip

Thanks for reading!

When I was finally fed up enough with the waiting, I would decide to run the test locally, and when I would see it pass, I’d be confused about what was going on in CI.

That’s when I started using the repeat method with Pest to debug what was going on.

I will use a simple Post model as an example of what I was running into.

public function up(): void
{
    Schema::create('posts', function (Blueprint $table) {
        $table->id();
        $table->string('title');
        $table->string('content')->nullable();
        $table->unsignedBigInteger('user_id');
        $table->string('status');
        $table->dateTime('published_at')->nullable();
        $table->timestamps();
    });
}

class Post extends Model
{
    use HasFactory;

    protected $casts = [
        'status' => PostStatus::class,
        'published_at' => 'datetime',
    ];

    protected $attributes = [
        'status' => PostStatus::Idea,
    ];

    protected function isPublished(): Attribute
    {
        return Attribute::make(
            get: function () {
                return $this->status === PostStatus::Published && $this->published_at?->lt(now());
            }
        );
    }
}

PostStatus is an enum with the following cases:

enum PostStatus: string
{
    case Idea = 'idea';
    case Draft = 'draft';
    case Published = 'published';
    case Hidden = 'hidden';
}

So far, everything is pretty straightforward. A post is considered published if it has a status of PostStatus::Published and a published_at date before the current date/time. I have two simple tests set up for this.

uses(RefreshDatabase::class);

it('is published', function () {
    $post = Post::factory()->create([
        'status' => PostStatus::Published
    ]);

    expect($post->is_published)->toBeTrue();
});

it('is not published', function () {
    $post = Post::factory()->create();

    expect($post->is_published)->toBeFalse();
});

I run the tests locally and everything passes.

Everything’s looking good, however, when merging my PR, CI runs and one of these tests fails. Or even worse, it passes, and another teammate comes along with a new PR and one of these tests now fails even though nothing related to these tests was changed. What just happened?

I decide I need to fix this flaky test, so I start looking into it using the repeat method.

it('is published', function () {
    $post = Post::factory()->create([
        'status' => PostStatus::Published
    ]);

    expect($post->is_published)->toBeTrue();
})->repeat(100);

it('is not published', function () {
    $post = Post::factory()->create();

    expect($post->is_published)->toBeFalse();
})->repeat(100);

Now, when I run the tests, I see something like the following:

So, our tests pass most of the time, but not all the time. So we know something is going on here. Since these tests are fairly simple, the first thing I will check is the factory.

class PostFactory extends Factory
{
    protected $model = Post::class;

    public function definition(): array
    {
        return [
            'title' => $this->faker->word(),
            'content' => $this->faker->paragraph(),
            'status' => $this->faker->randomElement(PostStatus::cases()),
            'published_at' => $this->faker->dateTimeBetween(now()->subYear(), now()->addWeek()),
            'user_id' => User::factory(),
        ];
    }
}

Look at that, we are randomly picking a status in the factory as well as a date, that could be in the past or the future. So, depending on the randomly picked selections, the test can fail. For this example, the best thing to do would probably be to modify the factory to take out the randomness, and then various adjustments into states, like the following.

class PostFactory extends Factory
{
    protected $model = Post::class;

    public function definition(): array
    {
        return [
            'title' => $this->faker->word(),
            'status' => PostStatus::Idea,
            'user_id' => User::factory(),
        ];
    }

    public function published(): static
    {
        return $this->state(function () {
            return [
                'status' => PostStatus::Published,
                'published_at' => now()->subWeek(),
            ];
        });
    }

    public function scheduled(): static
    {
        return $this->state(function () {
            return [
                'status' => PostStatus::Published,
                'published_at' => now()->addWeek(),
            ];
        });
    }

    public function idea(): static
    {
        return $this->state(function () {
            return [
                'content' => null,
                'status' => PostStatus::Idea,
                'published_at' => null,
            ];
        });
    }

    public function draft(): static
    {
        return $this->state(function () {
            return [
                'status' => PostStatus::Draft,
                'published_at' => null,
            ];
        });
    }

    public function hidden(): static
    {
        return $this->state(function () {
            return [
                'status' => PostStatus::Hidden,
                'published_at' => now()->addWeek(),
            ];
        });
    }
}

Notice that I changed the base definition to be much simpler with no randomness and then added the various states I would expect. For large projects where a factory may already be used in many places, you may need to be careful changing the base definition because it could break other tests.

With the factory updates in place, I updated the tests to the following:

uses(RefreshDatabase::class);

it('is published', function () {
    $post = Post::factory()->published()->create();

    expect($post->is_published)->toBeTrue();
})->repeat(100);

it('is not published', function ($post) {
    expect($post->is_published)->toBeFalse();
})->with([
    'idea post' => fn () => Post::factory()->idea()->create(),
    'draft post' => fn () => Post::factory()->draft()->create(),
    'scheduled post' => fn () => Post::factory()->scheduled()->create(),
    'hidden post' => fn () => Post::factory()->hidden()->create(),
])->repeat(100);

Now when I run them, I get the output below.

Since the second test is now using a dataset, it repeats 100 times for each item in the dataset, which is why there are 500 assertions versus the original 200.

Now that I am confident with the tests, I can remove the repeat method.

Flaky tests can be extremely frustrating, so having some more tools in place to fix them is always useful. An issue with a factory is what caused my initial look into using repeat, but there can be a variety of other causes, too. One of the biggest culprits I’ve seen is data not being cleaned up properly between tests, so something created in one test is affecting the next test. Another is timestamps. I’ve seen a lot of tests start failing at the start/end of a month, issues with daylight savings, or even where a test set a date that was not far enough into the future and now that date has happened, the test starts failing. You can use something like Carbon::setTestNow(today()); or other time methods in Laravel to try to avoid those issues.

Before Pest 2.0 or PHPUnit 10, you could use the --repeat=100 argument in the CLI to get similar results. However, this option was removed in PHPUnit 10, so Pest is needed. This Github issue has some workarounds if you can’t use Pest: Repeating tests · Issue #5174 · sebastianbergmann/phpunit.

Now, go and fix those flaky tests! Let me know if you have any other strategies for flaky tests. Thanks for reading!

This is the first of my “What I’m Reading” posts that I hope to do monthly. This was inspired by some articles I read by Chris Coyier and Cassidy Williams about RSS feeds, personal blogs, and reading what you think is interesting or what other humans think is interesting versus what the social media algorithms want you to read. So with that, let’s get started!

RSS and Blogging

I’ve been an avid RSS user since the time of Google Reader. After that was shut down, I moved to Feedly, and then on and on and on. I now use Readwise Reader which I have been enjoying quite a bit for both RSS feeds, read later, and combining it with Readwise itself to track highlights. RSS feeds are still my preferred way of discovering new articles directly from the sources I follow. This is why I found the following articles interesting and hope they help lead to an RSS resurgence.

• Where have all the websites gone?

• I miss human curation

Please comment if you have any interesting RSS feeds you’d like to share.

Modular Laravel

This one was more of a watch than a read, but I found it extremely informative. It was a course on Laracasts about Modular Laravel by Mateus Guimarães.

• Modular Laravel

Mateus does an excellent job talking about modularizing a Laravel application. After finishing the course, I want to build a simple Laravel package to create modules, but I know there are already a few of those and do I have the time to take something like that on?

Productivity and Maintainability

Speaking of not having time, I read an interesting article from Dave Rupert where he discusses having only one big project and one little project at a time and pushing everything else off to the side. It is an interesting idea for someone like me who has a lot of unfinished side projects lying around. I’ll be interested to see a follow-up and whether or not it worked.

• One big, one little

Another Dave Rupert article I read was about how quickly a project can go south and end up with a lot of tech debt when trying to move too fast. He says:

a key factor of sustainability is making sure maintainability stays on par with growth

A fun read and it discusses the current trend of AI for everything.

• The time to unmaintainable is very low

If you’d like to hear more from Dave Rupert, he co-hosts the Shop Talk Show with Chris Coyier. I’ve been listening on and off for a few years now and always enjoy it.

React Complexity

Here’s another Cassidy Williams post. This time about React and how confusing it has become.

• Kind of annoyed at React

In the last year or so, I’ve been primarily focused on the backend in Laravel, but before that, I was doing quite a bit of React, and I enjoyed it but I always felt like it made it way too easy to get into a bad state with poor performance, too many re-renders, etc.

Recently, I’ve been working on a project using Vue 2 and it has been so refreshing. I’m not sure if I am enjoying it because I really like Vue or because I’ve been so focused on backend work. I have yet to work on a Vue 3 project. If you have worked with Vue 3, how do you compare it to React? Are you using the Options API or Composition API?

Dev Tooling

It’s hard to resist trying out shiny new tools as a developer and two I came across recently are the Helix editor and Aspen HTTP client.

• Helix

• Meet Aspen: Speedier & Smarter API Testing, Powered by AI

Helix is a cool little terminal editor similar to Vim/Neovim but with a lot of helpful features built-in like LSP support. It’s nearly ready to go out of the box, you just need to install some LSP’s using npm. The keybindings are different from Vim, so that takes some time to get used to but they seem mostly straightforward. I am a PhpStorm user primarily but I like to work with other editors from time to time and getting Helix working was so much easier than my Neovim configuration using LazyVim, though some things are missing and Neovim is still a lot more flexible. As much as I want to like Helix, since I use Vim keybindings in all my editors, I likely won’t make the switch until I see Helix extensions in JetBrains, VSCode, etc.

With the recent changes from Insomnia, a lot of people have been looking at other HTTP clients. Insomnia is still my primary but I’ve been trying out Hoppscotch and using PhpStorm which you can read about in my post: Simplify API Testing with PhpStorm HTTP Requests. Aspen is fast and has a nice interface, but I can’t find anywhere to save variables and requests outside of the history it stores. It’s a good first start, but it will need some more before it can become my go-to HTTP client. However, I did recently see it can take the response to your request and turn it into a DTO for a variety of languages. This will save me a lot of time.

Event Sourcing

I have recently started diving into event sourcing. I haven’t actually done anything with it yet, but I am very intrigued. I started to look into it with the announcement of Verbs for Laravel by Chris Morrell and Daniel Coulbourne. Verbs isn’t quite ready for production usage yet and though it looks great, I decided to dive into a few other packages to start to learn more about it.

• Quickstart - Verbs

• Introduction | laravel-event-sourcing

• EventSauce - Event sourcing for PHP

I can’t wait to try out event sourcing, even at a small scale. Have you used any of these packages or event sourcing in general? What do you think about it?

That’s a good chunk of my reading from January, I hope you found this informative and entertaining. Comment with any interesting links or RSS feeds you’ve come across lately. Thanks for reading!

In the previous posts of the series, we learned how to build the following:

• Simple API client class using Laravel’s built-in Http facade

• Custom request class to generate API requests with a URL, method type, data, query strings, etc.

• API resources to use CRUD-like methods to fetch resources from the APIs

• Custom DTOs with simple classes

• DTOs using the Spatie Laravel-data package

Throughout all of these posts, we also learned how to test these various integrations using the Http facade and fake responses. However, we only tested best-case scenarios and didn’t go into error handling. So that’s what I hope to accomplish in this post.

Creating a Custom Exception

To get started, I recommend creating a custom exception. For now, we can call it ApiException. Either create this manually or use the Artisan command:

php artisan make:exception ApiException

Our new exception class can extend the Exception class and take three parameters.

<?php

namespace App\Exceptions;

use App\Support\ApiRequest;
use Exception;
use Illuminate\Http\Client\Response;
use Throwable;

class ApiException extends Exception
{
    public function __construct(
        public readonly ?ApiRequest $request = null,
        public readonly ?Response $response = null,
        Throwable $previous = null,
    ) {
        // Typically, we will just pass in the message from the previous exception, but provide a default if for some reason we threw this exception without a previous one.
        $message = $previous?->getMessage() ?: 'An error occurred making an API request';

        parent::__construct(
            message: $message,
            code: $previous?->getCode(),
            previous: $previous,
        );
    }

    public function context(): array
    {
        return [
            'uri' => $this->request?->getUri(),
            'method' => $this->request?->getMethod(),
        ];
    }
}

The constructor takes a $request property, $response property, and a $previous property.

The $request property is an instance of the ApiRequest class we created in a previous post to store information like URL, method, body data, query strings, etc.

The $response is an instance of Laravel’s default Illuminate\Http\Client\Response class which is returned when using the Http facade to make a request. By adding the response to the exception, we can gather a lot more information if needed when handing the exception, like an error object from the third-party API.

Finally, using the previous exception, if it exists, we throw the ApiException using data from the previous exception or simple defaults.

I also added a context class to provide a little more information which is pulled from the $request property. Depending on your application, data and query parameters could include sensitive information, so be sure you understand what is being added. For some applications, the URL itself could be sensitive, so adjust as needed or make a context parameter and pass in whatever data works for you.

Throwing the ApiException

Now that we have our new exception class, let’s look at actually throwing it when there is an error. We can update the ApiClient class from the previous posts to now catch exceptions, use the ApiException as a wrapper, and include information about the request.

<?php

namespace App\Support;

use App\Exceptions\ApiException;
use Exception;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Http;

abstract class ApiClient
{
    /**
     * Send an ApiRequest to the API and return the response.
     * @throws ApiException
     */
    public function send(ApiRequest $request): Response
    {
        try {
            return $this->getBaseRequest()
                ->withHeaders($request->getHeaders())
                ->{$request->getMethod()->value}(
                    $request->getUri(),
                    $request->getMethod() === HttpMethod::GET
                        ? $request->getQuery()
                        : $request->getBody()
                );
        } catch (Exception $exception) {
            // Create our new exception and throw it.
            throw new ApiException(
                request: $request,
                response: $exception?->response,
                previous: $exception,
            );
        }
    }

    protected function getBaseRequest(): PendingRequest
    {
        $request = Http::acceptJson()
            ->contentType('application/json')
            ->throw()
            ->baseUrl($this->baseUrl());

        return $this->authorize($request);
    }

    protected function authorize(PendingRequest $request): PendingRequest
    {
        return $request;
    }

    abstract protected function baseUrl(): string;
}

To throw the exception, all we need to do is wrap the return in our send method with a try…catch and then throw our new exception. When setting the $response in our exception, we attempt to pull it from the caught exception’s response property. If our request was made but failed during the process, the Http facade will throw an Illuminate\Http\Client\RequestException which has a response property that is an instance of Illuminate\Http\Client\Response. If a different exception is caught, we will just set the response to null.

Testing

Testing the Client

To test our new exception, we’ll create an ApiClientTest.php file and add the following test.

it('throws an api exception', function () {
    // Arrange
    Http::fakeSequence()->pushStatus(500);
    $request = ApiRequest::get('foo');

    // Act
    $this->client->send($request);
})->throws(ApiException::class, exceptionCode: 500);

This test uses the Http::fakeSequence() call and pushes a response with a 500 status code. Then, we expect the client to throw an ApiException with a 500 exception code.

You might notice that this test fails. This occurs because we used Http::fake() in the beforeEach method of the test.

beforeEach(function () {
    Http::fake();

    $this->client = new class extends ApiClient {
        protected function baseUrl(): string
        {
            return 'https://example.com';
        }
    };
});

When calling Http::fake() essentially, we tell it to fake any request made with the facade. It does this by pushing an entry into an internal collection. Even when we add additional items to Http::fake() or our Http::fakeSequence(), the fake response will still pull from the first item in the collection since we didn’t specify a specific URL. It works kind of like the router where it finds the first viable route that can be used to fake the response.

To solve this, we can either move Http::fake() into the various tests themselves. However, I like another approach, which is adding a macro to the Http facade to be able to reset the internal collection, which is named stubCallbacks. To do that, open your AppServiceProvider and add the macro in the boot method.

// AppServiceProvider

public function boot(): void
{
    Http::macro('resetStubs', fn () => $this->stubCallbacks = collect());
}

Now, instead of having to add Http::fake() to all of our previous tests, we can update our new test to call Http::resetStubs.

it('throws an api exception', function () {
    // Arrange
    Http::resetStubs();
    Http::fakeSequence()->pushStatus(500);
    $request = ApiRequest::get('foo');

    // Act
    $this->client->send($request);
})->throws(ApiException::class, exceptionCode: 500);

Testing the Exception

Now that we tested that our client throws the API exception, let’s add some tests for the exception itself.

<?php

use App\Exceptions\ApiException;
use App\Support\ApiRequest;
use Illuminate\Http\Client\RequestException;
use Illuminate\Http\Client\Response;

it('sets default message and code', function () {
    // Act
    $apiException = new ApiException();

    // Assert
    expect($apiException)
        ->getMessage()->toBe('An error occurred making an API request.')
        ->getCode()->toBe(0);
});

it('sets context based on request', function () {
    // Arrange
    $request = ApiRequest::get(fake()->url);

    // Act
    $apiException = new ApiException($request);

    // Assert
    expect($apiException)->context()->toBe([
        'uri' => $request->getUri(),
        'method' => $request->getMethod(),
    ]);
});

it('gets response from RequestException', function () {
    // Arrange
    $requestException = new RequestException(
        new Response(
            new GuzzleHttp\Psr7\Response(
                422,
                [],
                json_encode(['message' => 'Something went wrong.']),
            ),
        )
    );

    // Act
    $apiException = new ApiException(response: $requestException->response, previous: $requestException);

    // Assert
    expect($apiException->getCode())->toBe(422)
        ->and($apiException->response)->toBeInstanceOf(Response::class)
        ->and($apiException->response->json('message'))->toBe('Something went wrong.');
});

Using the Response in the Exception

Having the response from the request be part of the ApiException is extremely helpful for a variety of purposes. For example, our application could have a UI to allow a user to add a product to the store. When submitting the request, we would likely validate as much as we could in our application, but maybe the third-party API has some additional validation that we can’t handle locally. We would likely want to return that information to our UI so the user knows what needs to be fixed.

If we make a call to create a product with our ProductResource that we created in a previous post, and we receive an ApiClientException, in our controller, we could catch that exception and return any errors received to the user in the frontend.

For simplicity, I created a very simple controller example. In a production application, you would likely have more validation for the request data using a FormRequest class or $request->validate(). For this example, we are assuming the third-party API returns validation error messages using a 422 and a response similar to how Laravel returns errors.

<?php

namespace App\Http\Controllers;

use App\ApiResources\ProductResource;
use App\Data\SaveProductData;
use App\Exceptions\ApiException;
use Illuminate\Http\Request;

class ProductController extends Controller
{
    public function __construct(public readonly ProductResource $productResource)
    {

    }

    public function create(Request $request)
    {
        try {
            return $this->productResource->create(SaveProductData::from($request->all());
        } catch (ApiException $exception) {
            if ($exception->getCode() === 422) {
                // 422 is typically the HTTP status code used for validation errors.
                // Let's assume that the API returns an 'errors' property similar to Laravel.
                $errors = $exception->response?->json('errors');
            }

            return response()->json([
                'message' => $exception->getMessage(),
                'errors' => $errors ?? null,
            ], $exception->getCode());
        }
    }
}

Additional Techniques

In your application, let’s say you have integrations with multiple third-party APIs. This means you likely have multiple client classes extending the base ApiClient class. Instead of having a single ApiException, it could be nice to have specific exceptions for each client. To do that, we can introduce a new $exceptionClass property to the ApiClient class.

abstract class ApiClient
{
    protected string $exceptionClass = ApiException::class;

    ...
}

Now, when throwing the exception, we can throw an instance of whatever is set by the $exceptionClass.

throw new $this->exceptionClass(
    request: $request,
    response: $exception?->response,
    previous: $exception,
);

If we go back to the StoreApiClient we created in a previous post, we can create a new exception for it and set it on the client. The exception can just simply extend the ApiException class.

// StoreApiException
<?php

namespace App\Exceptions;

class StoreApiException extends ApiException
{
}

Then, we can update the client.

// StoreApiClient
<?php

namespace App\Support;

use App\Exceptions\StoreApiException;

class StoreApiClient extends ApiClient
{
    protected string $exceptionClass = StoreApiException::class;

    protected function baseUrl(): string
    {
        return config('services.store_api.url');
    }
}

Let’s add a test to make sure the StoreApiClient is throwing our new StoreApiException.

it('throws a StoreApiException', function () {
    // Arrange
    Http::resetStubs();
    Http::fakeSequence()->pushStatus(404);
    $request = ApiRequest::get('products');

    // Act
    app(StoreApiClient::class)->send($request);
})->throws(StoreApiException::class, exceptionCode: 404);

What happens if someone decides to use an exception that doesn’t extend our ApiException class? When our client tries to throw, it will fail if the $exceptionClass is not expecting the same parameters. To handle that, let’s create an interface and use that to check the $exceptionClass.

<?php

namespace App\Exceptions\Contracts;

use App\Support\ApiRequest;
use Illuminate\Http\Client\Response;
use Throwable;

interface ApiExceptionInterface
{
    public function __construct(
        ?ApiRequest $request = null,
        ?Response $response = null,
        Throwable $previous = null,
    );
}

Now, update the ApiException class to implement the interface.

class ApiException extends Exception implements ApiExceptionInterface
{
    ...
}

Finally, let’s update the ApiClient to throw the $exceptionClass only if it implements the ApiExceptionInterface. Otherwise, let’s just throw the exception that was caught since we may not know how to instantiate a different type of exception.

abstract class ApiClient
{
    ...

    public function send(ApiRequest $request): Response
    {
        try {
            return $this->getBaseRequest()
                ->withHeaders($request->getHeaders())
                ->{$request->getMethod()->value}(
                    $request->getUri(),
                    $request->getMethod() === HttpMethod::GET
                        ? $request->getQuery()
                        : $request->getBody()
                );
        } catch (Exception $exception) {
            if (! is_subclass_of($this->exceptionClass, ApiExceptionInterface::class)) {
                // If the exceptionClass does not implement the ApiExceptionInterface,
                // let's just throw the caught exception since we don't know how to instantiate
                // the exceptionClass.
                throw $exception;
            }

            // Create our new exception and throw it.
            throw new $this->exceptionClass(
                request: $request,
                response: $exception?->response,
                previous: $exception,
            );
        }
    }

    ...
}

We use the is_subclass_of method which checks if the $exceptionClass is a child of or implements the provided class. Since our $exceptionClass for the StoreApiClient extends the ApiException class and does not overwrite the constructor, it implements the ApiExceptionInterface.

Summary

In this post, we learned how to create a custom exception to make it easier to track and debug issues with third-party APIs. We created a custom ApiException that was integrated with our ApiClient. The exception included information about the request and response to make it easier to track down the cause of the issue.

As always, let me know if you have any questions or comments, and thanks for reading!

• Simplifying API Integration with Laravel's Http Facade

• Streamlining API Responses in Laravel with DTOs

In the first two parts of the series, I used the Google Books API for my examples. For simplification and to have more routes readily available without needing to setup OAuth 2.0, I will be using Fake Store API and querying products. I will also be using the Spatie Laravel-data package for my data-transfer objects (DTOs) instead of creating custom DTOs from simple PHP classes like I did in the previous posts. This helps to remove some of the boilerplate of defining fromArray and toArray methods.

Getting Started

In the previous posts in the series, we had an ApiRequest class and ApiClient class. To create the API client for the Fake Store API; we can extend the ApiClient class.

<?php

namespace App\Support;

class StoreApiClient extends ApiClient
{
    protected function baseUrl(): string
    {
        return config('services.store_api.url');
    }
}

Since the Fake Store API does not have any authentication required, this class can be pretty simple. For the test, we can just make sure the base URL is getting set as expected.

<?php

use App\Support\ApiRequest;
use App\Support\StoreApiClient;
use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;

beforeEach(function () {
    Http::fake();
    config([
        'services.store_api.url' => 'https://example.com',
    ]);
});

it('sets the base url', function () {
    $request = ApiRequest::get('products');

    app(StoreApiClient::class)->send($request);

    Http::assertSent(static function (Request $request) {
        expect($request)->url()->toStartWith('https://example.com/products');

        return true;
    });
});

For this test, I manually set a test URL in my configuration. It is also possible to just use an .env.test file to define the value if you prefer. For simple tests, I like the approach of defining the config in the test so I can easily see what was expected in the tests versus having to compare it to another file.

Now, let’s create our API resource. What I am calling an API resource is a simple class to treat the product resource similar to a REST controller in Laravel. The API resource will allow me to list products, show a product, create a product, update a product, and delete a product. In the previous post, we had an action for fetching books from the Google Books API, but by using a resource, I combined the various calls for a resource into a single class.

<?php

namespace App\ApiResources;

use App\Data\ProductData;
use App\Support\StoreApiClient;
use Spatie\LaravelData\DataCollection;

/**
 * ApiResource for products.
 */
class ProductResource
{
    /**
     * Use dependency injection to get the StoreApiClient.
     */
    public function __construct(private readonly StoreApiClient $client)
    {
    }

    /**
     * List all products.
     */
    public function list()
    {
        ...
    }

    /**
     * Show a single product.
     */
    public function show(int $id)
    {
        ...
    }

    /**
     * Create a new product.
     */
    public function create($data)
    {
        ...
    }

    /**
     * Update a product.
     */
    public function update(int $id, $data)
    {
        ...
    }

    /**
     * Delete a product.
     */
    public function delete(int $id)
    {
        ...
    }
}

Filling out the API Resource

List Method

We’ll start with the list method. The first thing I like to do is model the data that we will be receiving from the API. I will use Laravel-data for this and create a ProductData class. If you haven’t installed Laravel-data, install it with composer:

composer require spatie/laravel-data

The ProductData class can be created manually by extending the Spatie\LaravelData\Data class or by using Artisan:

php artisan make:data ProductData

Looking at the documentation for the Fake Store API, we can map that to a DTO like the following:

<?php

namespace App\Data;

use Spatie\LaravelData\Data;

class ProductData extends Data
{
    public function __construct(
        public int $id,
        public string $title,
        public float $price,
        public string $description,
        public string $category,
        public string $image,
        public ?RatingData $rating = null,
    ) {}
}

Notice the $rating property has a type of RatingData. This is another DTO:

<?php

namespace App\Data;

use Spatie\LaravelData\Data;

class RatingData extends Data
{
    public function __construct(
        public float $rate,
        public int $count,
    ) {}
}

Now, in the resource list method, we can add the following to fetch the products and map them to a collection of ProductData instances.

public function list(): DataCollection
{
    // Create the request to the products endpoint.
    $request = ApiRequest::get('/products');

    // Send the request using the client.
    $response = $this->client->send($request);

    // Map the response to the ProductData DTO.
    return ProductData::collection($response->json());
}

Looking at the API documentation for the Fake Store API, it is possible to limit the number of results and sort the results that are returned. We can map this using a DTO as well.

<?php

namespace App\Data;

use App\Enums\SortDirection;
use Spatie\LaravelData\Data;

class ListProductsData extends Data
{
    public function __construct(
        public readonly ?int $limit = null,
        public readonly ?SortDirection $sort = null,
    ) {}

    public function toArray(): array
    {
        return collect(parent::toArray())
            ->filter()
            ->toArray();
    }
}

The SortDirection type is just a simple enum with asc and desc cases. I added a custom toArray method which uses Laravel collections and the filter method to remove any null properties from the array. This prevents sending things like ?sort=null to the API.

Let’s add this to our list method.

public function list(?ListProductsData $data = null): DataCollection
{
    $request = ApiRequest::get('/products');

    if ($data) {
        // Add the ListProductsData to the query string of the request.
        $request->setQuery($data->toArray());
    }

    $response = $this->client->send($request);

    return ProductData::collection($response->json());
}

Now, if we want to request a list of five products in descending order, we can do something like the following:

$resource = resolve(ProductResource::class);
$requestData = new ListProductsData(
  limit: 5,
  sort: SortDirection::DESC,
);

$response = $resource->list($requestData);

Let’s add a few tests for this method.

<?php

use App\ApiResources\ProductResource;
use App\Data\ListProductsData;
use App\Data\ProductData;
use App\Enums\SortDirection;
use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Request;
use Spatie\LaravelData\DataCollection;
use Tests\Helpers\StoreApiTestHelper;

uses(StoreApiTestHelper::class);

it('shows a list of products', function () {
    // Fake the response from the API.
    Http::fake([
        '*/products' => Http::response([
            $this->getFakeProduct(['id' => 1]),
            $this->getFakeProduct(['id' => 2]),
            $this->getFakeProduct(['id' => 3]),
            $this->getFakeProduct(['id' => 4]),
            $this->getFakeProduct(['id' => 5]),
        ]),
    ]);

    $resource = resolve(ProductResource::class);

    $response = $resource->list();

    // Assert that the response is a collection of product data objects.
    expect($response)
        ->toBeInstanceOf(DataCollection::class)
        ->count()->toBe(5)
        ->getIterator()->each->toBeInstanceOf(ProductData::class);

    // Assert that a GET request was sent to the correct endpoint.
    Http::assertSent(function (Request $request) {
        expect($request)
            ->url()->toEndWith('/products')
            ->method()->toBe('GET');

        return true;
    });
});

it('limits and sorts products', function () {
    // Fake the response from the API.
    Http::fake([
        '*/products?*' => Http::response([
            $this->getFakeProduct(['id' => 3]),
            $this->getFakeProduct(['id' => 2]),
            $this->getFakeProduct(['id' => 1]),
        ]),
    ]);

    $resource = resolve(ProductResource::class);

    // Create a request data object with a three-item limit and descending direction.
    $requestData = new ListProductsData(3, SortDirection::DESC);

    $response = $resource->list($requestData);

    // Assert that the response is a collection of product data objects.
    expect($response)
        ->toBeInstanceOf(DataCollection::class)
        ->count()->toBe(3)
        ->getIterator()->each->toBeInstanceOf(ProductData::class);

    // Assert that a GET request was sent to the correct endpoint with the correct query data.
    Http::assertSent(function (Request $request) {
        parse_str(parse_url($request->url(), PHP_URL_QUERY), $queryParams);
        $path =  (parse_url($request->url(), PHP_URL_PATH));

        expect($queryParams)->toMatchArray(['limit' => 3, 'sort' => 'desc'])
            ->and($path)->toEndWith('/products')
            ->and($request)->method()->toBe('GET');

        return true;
    });
});

You’ll notice the uses(StoreApiTestHelper::class); call in the test. That loads a simple trait to provide the getFakeProduct() method which is used to generate fake product responses.

<?php

namespace Tests\Helpers;

trait StoreApiTestHelper
{
    private function getFakeProduct(array $data = []): array {
        return [
            'id' => data_get($data, 'id', fake()->numberBetween(1, 1000)),
            'title' => data_get($data, 'title', fake()->text()),
            'price' => data_get($data, 'price', fake()->randomFloat(2, 0, 100)),
            'description' => data_get($data, 'description', fake()->paragraph()),
            'category' => data_get($data, 'category', fake()->text()),
            'image' => data_get($data, 'image', fake()->url()),
            'rating' => data_get($data, 'rating', [
                'rate' => fake()->randomFloat(2, 0, 5),
                'count' => fake()->numberBetween(1, 1000),
            ]),
        ];
    }
}

I like using traits like this in tests to try and make it easier to fake API responses. This can easily be expanded on, too, like I did in my previous post.

In the tests, we ensure the proper endpoints are being called and the expected responses are being returned.

Show and Delete Methods

I am combining the show and delete methods here since they will be very similar. According to the API documentation, they both return the product for the ID provided, so they have the same return value. They also accept an id URL parameter to fetch the specific product.

/**
 * Show a single product.
 */
public function show(int $id): ProductData
{
    $request = ApiRequest::get("/products/{$id}");
    $response = $this->client->send($request);

    return ProductData::from($response->json());
}

/**
 * Delete a product.
 */
public function delete(int $id): ProductData
{
    $request = ApiRequest::delete("/products/$id");
    $response = $this->client->send($request);

    return ProductData::from($response->json());
}

Now, let’s add the following tests:

it('fetches a product', function () {
    // Create a fake product
    $fakeProduct = $this->getFakeProduct();

    // Fake the response from the API.
    Http::fake(["*/products/{$fakeProduct['id']}" => Http::response($fakeProduct)]);

    $resource = resolve(ProductResource::class);

    // Request a product
    $response = $resource->show($fakeProduct['id']);
    expect($response)
        ->toBeInstanceOf(ProductData::class)
        ->id->toBe($fakeProduct['id']);

    // Assert that a GET request was sent to the correct endpoint with the correct method.
    Http::assertSent(function (Request $request) use ($fakeProduct) {
        expect($request)
            ->url()->toEndWith("/products/{$fakeProduct['id']}")
            ->method()->toBe('GET');

        return true;
    });
});

it('deletes a product', function () {
    // Create a fake product
    $fakeProduct = $this->getFakeProduct();

    // Fake the response from the API.
    Http::fake(["*/products/{$fakeProduct['id']}" => Http::response($fakeProduct)]);

    $resource = resolve(ProductResource::class);

    // Request a product
    $response = $resource->delete($fakeProduct['id']);
    expect($response)
        ->toBeInstanceOf(ProductData::class)
        ->id->toBe($fakeProduct['id']);

    // Assert that a DELETE request was sent to the correct endpoint.
    Http::assertSent(function (Request $request) use ($fakeProduct) {
        expect($request)
            ->url()->toEndWith("/products/{$fakeProduct['id']}")
            ->method()->toBe('DELETE');

        return true;
    });
});

Create and Update Methods

For the create and update methods, we know we need to send data to the API. Sometimes it is possible to reuse the same DTO that the API returns, but oftentimes, I like to create dedicated DTOs for the request. So I will create the SaveProductData DTO:

<?php

namespace App\Data;

use Spatie\LaravelData\Data;

class SaveProductData extends Data
{
    public function __construct(
        public string $title,
        public float $price,
        public string $description,
        public string $category,
        public string $image,
    ) {}
}

For this API, this single DTO is sufficient for both the create and update methods, however, sometimes it is necessary to have a dedicated DTO for each method. For example, using this specific DTO for the update method requires all the fields to be specified. However, you may want a DTO that allows optional properties and filters out the ones not set so you can easily update specific properties instead of everything.

With that in place, let’s update the create method:

/**
 * Create a new product.
 */
public function create(SaveProductData $data): ProductData
{
    $request = ApiRequest::post('/products')->setBody($data->toArray());
    $response = $this->client->send($request);

    return ProductData::from($response->json());
}

The update method is similar but with an additional id parameter and a PUT request instead of a POST request.

/**
 * Update a product.
 */
public function update(int $id, SaveProductData $data): ProductData
{
    $request = ApiRequest::put("/products/$id")->setBody($data->toArray());
    $response = $this->client->send($request);

    return ProductData::from($response->json());
}

Just like the show and delete methods, we are returning a ProductData instance for create and update.

Add the following tests for the methods.

it('creates a product', function () {
    // Create a fake product
    $fakeProduct = $this->getFakeProduct();

    // Fake the response from the API.
    Http::fake(["*/products" => Http::response($fakeProduct)]);

    $resource = resolve(ProductResource::class);

    // Data for creating a product.
    $data = new SaveProductData(
        title: $fakeProduct['title'],
        price: $fakeProduct['price'],
        description: $fakeProduct['description'],
        category: $fakeProduct['category'],
        image: $fakeProduct['image'],
    );

    // Request a product
    $response = $resource->create($data);
    expect($response)
        ->toBeInstanceOf(ProductData::class)
        ->id->toBe($fakeProduct['id']);

    // Assert that a POST request was sent to the correct endpoint.
    Http::assertSent(function (Request $request) {
        expect($request)
            ->url()->toEndWith('/products')
            ->method()->toBe('POST');

        return true;
    });
});

it('updates a product', function () {
    // Create a fake product
    $fakeProduct = $this->getFakeProduct();

    // Fake the response from the API.
    Http::fake(["*/products/{$fakeProduct['id']}" => Http::response($fakeProduct)]);

    $resource = resolve(ProductResource::class);

    $data = new SaveProductData(
        title: $fakeProduct['title'],
        price: $fakeProduct['price'],
        description: $fakeProduct['description'],
        category: $fakeProduct['category'],
        image: $fakeProduct['image'],
    );

    // Request a product
    $response = $resource->update($fakeProduct['id'], $data);
    expect($response)
        ->toBeInstanceOf(ProductData::class)
        ->id->toBe($fakeProduct['id']);

    // Assert that a PUT request was sent to the correct endpoint.
    Http::assertSent(function (Request $request) use ($fakeProduct) {
        expect($request)
            ->url()->toEndWith("/products/{$fakeProduct['id']}")
            ->method()->toBe('PUT');

        return true;
    });
});

Summary

In this post, we discussed a method of combining requests related to a resource into a single class. When using the combination of Laravel’s Http facade and data transfer objects, the methods of these classes can be made similar to a Laravel controller and be kept small and concise. I hope you enjoyed this series on integrating third-party APIs in Laravel. You can view the repository with all the code we went through in this post, here.

Thanks for reading and as always, feel free to comment or ask questions!

Handling API responses effectively is crucial for integrating third-party APIs. In my previous post, I discussed setting up simple client and request classes using the Http facade. If that's not something that you've already read, I recommend you take a look at it.

Amplifying these concepts, this post brings you an in-depth guide on how to create custom data transfer objects (DTOs) that can map the data from the API responses. I’ll be using an ongoing Google Books API integration scenario as a practical example to make things more relatable.

Map the Response Data to a DTO

To start, let’s look at a sample response from the Google Books API when we perform a search. To do this, I call the QueryBooksByTitle action I created previously and search for the book “The Ferryman”:

$response = app(QueryBooksByTitle::class)("The Ferryman");

dump($response->json());

This dumps out the following JSON which I have narrowed down to fields I’d like to track:

[
    'kind' => 'books#volumes',
    'totalItems' => 367,
    'items' => [
        0 => [
            ...
        ],
        1 => [
            ...
        ],
        2 => [
            'kind' => 'books#volume',
            'id' => 'dO5-EAAAQBAJ',
            'volumeInfo' => [
                'title' => 'The Ferryman',
                'subtitle' => 'A Novel',
                'authors' => [
                    0 => 'Justin Cronin',
                ],
                'publisher' => 'Doubleday Canada',
                'publishedDate' => '2023-05-02',
                'description' => 'From the #1 New York Times bestselling author of The Passage comes a riveting standalone novel about a group of survivors on a hidden island utopia--where the truth isn\'t what it seems. Founded by a mysterious genius, the archipelago of Prospera lies hidden from the horrors of a deteriorating outside world. In this island paradise, Prospera\'s lucky citizens enjoy long, fulfilling lives until the monitors embedded in their forearms, meant to measure their physical health and psychological well-being, fall below 10 percent. Then they retire themselves, embarking on a ferry ride to the island known as the Nursery, where their failing bodies are renewed, their memories are wiped clean, and they are readied to restart life afresh. Proctor Bennett, of the Department of Social Contracts, has a satisfying career as a ferryman, gently shepherding people through the retirement process--and, when necessary, enforcing it. But all is not well with Proctor. For one thing, he\'s been dreaming--which is supposed to be impossible in Prospera. For another, his monitor percentage has begun to drop alarmingly fast. And then comes the day he is summoned to retire his own father, who gives him a disturbing and cryptic message before being wrestled onto the ferry. Meanwhile, something is stirring. The support staff, ordinary men and women who provide the labor to keep Prospera running, have begun to question their place in the social order. Unrest is building, and there are rumors spreading of a resistance group--known as Arrivalists--who may be fomenting revolution. Soon Proctor finds himself questioning everything he once believed, entangled with a much bigger cause than he realized--and on a desperate mission to uncover the truth.',
                'pageCount' => 507,
                'categories' => [
                    0 => 'Fiction',
                ],
                'imageLinks' => [
                    'smallThumbnail' => 'http://books.google.com/books/content?id=dO5-EAAAQBAJ&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api',
                    'thumbnail' => 'http://books.google.com/books/content?id=dO5-EAAAQBAJ&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api',
                ],
                ...
            ],
            ...
        ],
        ...
    ]

Now that we know the format of the response, let’s create the necessary DTOs to map the data. Let’s start with BookListData which can be a simple PHP class.

<?php

namespace App\DataTransferObjects;

use Illuminate\Contracts\Support\Arrayable;

/**
 * Stores the top-level data from the Google Books volumes API.
 */
readonly class BooksListData implements Arrayable
{
    public function __construct(
        public string $kind,
        public string $id,
        public int $totalItems,
    ) {
    }

    /**
     * Creates a new instance of the class from an array of data.
     */
    public static function fromArray(array $data): BooksListData
    {
        return new self(
            data_get($data, 'kind'),
            data_get($data, 'id'),
            data_get($data, 'totalItems'),
        );
    }

    /**
     * Implements Laravel's Arrayable interface to allow the object to be
     * serialized to an array.
     */
    public function toArray(): array
    {
        return [
            'kind' => $this->kind,
            'items' => $this->items,
            'totalItems' => $this->totalItems,
        ];
    }
}

With the DTO created, we can update the QueryBooksByTitle action that we created in the previous post.

<?php

namespace App\Actions;

use App\DataTransferObjects\BooksListData;
use App\Support\ApiRequest;
use App\Support\GoogleBooksApiClient;
use Illuminate\Http\Client\Response;

/**
 * The QueryBooksByTitle class is an action for querying books by title from the
 * Google Books API.
 * It provides an __invoke method that takes a title and returns the response
 * from the API.
 */
class QueryBooksByTitle
{
    /**
     * Query books by title from the Google Books API and return the BookListData.
     * This method creates a GoogleBooksApiClient and an ApiRequest for the
     * 'volumes' endpoint
     * with the given title as the 'q' query parameter and 'books' as the
     * 'printType' query parameter.
     * It then sends the request using the client and returns the book list data.
     */
    public function __invoke(string $title): BooksListData
    {
        $client = app(GoogleBooksApiClient::class);

        $request = ApiRequest::get('volumes')
            ->setQuery('q', 'intitle:'.$title)
            ->setQuery('printType', 'books');

        $response = $client->send($request);

        return BooksListData::fromArray($response->json());
    }
}

Test the Response Data

We can create a test to make sure we return a BooksListData object when calling the action:

<?php

use App\Actions\QueryBooksByTitle;
use App\DataTransferObjects\BooksListData;

it('fetches books by title', function () {
    $title = 'The Lord of the Rings';

    $response = resolve(QueryBooksByTitle::class)($title);

    expect($response)->toBeInstanceOf(BooksListData::class);
});

You might not have noticed, but there is an issue with the test above. We are reaching out to the Google Books API. This might be okay for an integration test that is not run often, but in our Laravel tests, this should be fixed. We can use the power of the Http facade for this since our Client class is built using the facade.

Prevent HTTP Requests in Tests

The first step I like to do is make sure none of my tests are making external HTTP requests that I am not expecting. We can add Http::preventStrayRequests(); to the Pest.php file. Then, in any test using the Http facade to make a request, an exception will be thrown unless we mock the request.

<?php

use Illuminate\Foundation\Testing\TestCase;
use Illuminate\Support\Facades\Http;
use Tests\CreatesApplication;

uses(
    TestCase::class,
    CreatesApplication::class,
)
    ->beforeEach(function () {
        Http::preventStrayRequests();
    })
    ->in('Feature');

If I run my QueryBooksByTitle test again, I now get a failed test that says:

RuntimeException: Attempted request to [https://www.googleapis.com/books/v1/volumes?key=XXXXXXXXXXXXX&q=intitle%3AThe%20Lord%20of%20the%20Rings&printType=books] without a matching fake.

Now, let’s use the Http facade to fake the response.

<?php

use App\Actions\QueryBooksByTitle;
use App\DataTransferObjects\BooksListData;
use Illuminate\Support\Facades\Http;

it('fetches books by title', function () {
    $title = fake()->sentence();

    // Generate a fake response from the Google Books API.
    $responseData = [
        'kind' => 'books#volumes',
        'totalItems' => 1,
        'items' => [
            [
                'id' => fake()->uuid,
                'volumeInfo' => [
                    'title' => $title,
                    'subtitle' => fake()->sentence(),
                    'authors' => [fake()->name],
                    'publisher' => fake()->company(),
                    'publishedDate' => fake()->date(),
                    'description' => fake()->paragraphs(asText: true),
                    'pageCount' => fake()->numberBetween(100, 500),
                    'categories' => [fake()->word],
                    'imageLinks' => [
                        'thumbnail' => fake()->url(),
                    ],
                ],
            ],
        ],
    ];

    // Return the fake response when the client sends a request to the Google Books API.
    Http::fake(['https://www.googleapis.com/books/v1/*' => Http::response(
        body: $responseData,
        status: 200
    )]);

    $response = resolve(QueryBooksByTitle::class)($title);

    expect($response)->toBeInstanceOf(BooksListData::class);
    expect($response->items[0]['volumeInfo']['title'])->toBe($title);
});

When running the test now, we no longer have the RuntimeException because we are faking the request using the Http::fake() method. The Http::fake() method is very flexible and can accept an array of items and different URLs. Depending on your application, you can just use '*' instead of the full URL or even make it more specific and include query parameters or other dynamic URL data. You can even fake sequences of requests if needed. Refer to the Laravel docs for more information.

This test works great but there are still some improvements to be made.

Expand the DTOs

First, let’s look at the response data again. It’s nice that we map the top level of the response in the BooksListData object, but having items[0]['volumeInfo']['title']) is not very developer-friendly friendly and the IDE cannot provide any type of autocompletion. To fix this, we need to create more DTOs. It’s usually easiest to start with the lowest-level items that need to be mapped. In this case, that would be the imageLinks data from the response. Looking at the response from Google Books, it looks like that could contain a thumbnail and smallThumbnail properties. We’ll create an ImageLinksData object to map this.

<?php

namespace App\DataTransferObjects;

use Illuminate\Contracts\Support\Arrayable;

readonly class ImageLinksData implements Arrayable
{
    public function __construct(
        public ?string $thumbnail = null,
        public ?string $smallThumbnail = null,
    ) {
    }

    public static function fromArray(array $data): self
    {
        return new self(
            thumbnail: data_get($data, 'thumbnail'),
            smallThumbnail: data_get($data, 'smallThumbnail'),
        );
    }

    public function toArray(): array
    {
        return [
            'thumbnail' => $this->thumbnail,
            'smallThumbnail' => $this->smallThumbnail,
        ];
    }
}

From there, go up a level and we have the VolumeInfoData.

<?php

namespace App\DataTransferObjects;

use Illuminate\Contracts\Support\Arrayable;
use Illuminate\Support\Collection;

readonly class VolumeInfoData implements Arrayable
{
    public function __construct(
        public string $title,
        public string $subtitle,
        // Using collections instead of arrays is a personal preference.
        // It makes dealing with the data a little easier.
        /** @var Collection<int, string> */
        public Collection $authors,
        public string $publisher,
        public string $publishedDate,
        public string $description,
        public int $pageCount,
        /** @var Collection<int, string> */
        public Collection $categories,
        // The image links are mapped by the ImageLinksData object.
        public ImageLinksData $imageLinks,
    ) {
    }

    public static function fromArray(array $data): self
    {
        return new self(
            title: data_get($data, 'title'),
            subtitle: data_get($data, 'subtitle'),
            // Create collections from the arrays of data.
            authors: collect(data_get($data, 'authors')),
            publisher: data_get($data, 'publisher'),
            publishedDate: data_get($data, 'publishedDate'),
            description: data_get($data, 'description'),
            pageCount: data_get($data, 'pageCount'),
            // Create collections from the arrays of data.
            categories: collect(data_get($data, 'categories')),
            // Map the image links to the ImageLinksData object.
            imageLinks: ImageLinksData::fromArray(data_get($data, 'imageLinks')),
        );
    }

    public function toArray(): array
    {
        return [
            'title' => $this->title,
            'subtitle' => $this->subtitle,
            // Convert the collections to arrays since they implement the
            // arrayable interface.
            'authors' => $this->authors->toArray(),
            'publisher' => $this->publisher,
            'publishedDate' => $this->publishedDate,
            'description' => $this->description,
            'pageCount' => $this->pageCount,
            'categories' => $this->categories->toArray(),
            // Since we are using the arrayable interface, we can just call the
            // toArray method on the imageLinks object.
            'imageLinks' => $this->imageLinks->toArray(),
        ];
    }
}

Notice instead of using arrays, I used Laravel’s collections instead. I prefer working with Collections so I make sure anytime I have arrays in my responses, I map to Collections instead. Also, since the VolumeInfoData contains the imageLinks property, we can map it using the ImageLinksData object.

Going up another level, we have the list of items, so we can create the ItemData object.

<?php

namespace App\DataTransferObjects;

use Illuminate\Contracts\Support\Arrayable;

readonly class ItemData implements Arrayable
{
    public function __construct(
        public string $id,
        public VolumeInfoData $volumeInfo,
    ) {
    }

    public static function fromArray(array $data): self
    {
        return new self(
            id: data_get($data, 'id'),
            volumeInfo: VolumeInfoData::fromArray(data_get($data, 'volumeInfo')),
        );
    }

    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'volumeInfo' => $this->volumeInfo->toArray(),
        ];
    }
}

Finally, we need to go back to the original BooksListData object and instead of mapping an array of data, we want to map a Collection of ItemData objects.

<?php

namespace App\DataTransferObjects;

use Illuminate\Contracts\Support\Arrayable;
use Illuminate\Support\Collection;

/**
 * Stores the top-level data from the Google Books volumes API.
 */
readonly class BooksListData implements Arrayable
{
    public function __construct(
        public string $kind,
        /** @var Collection<int, ItemData> */
        public Collection $items,
        public int $totalItems,
    ) {
    }

    /**
     * Creates a new instance of the class from an array of data.
     */
    public static function fromArray(array $data): BooksListData
    {
        return new self(
            data_get($data, 'kind'),
            // Map the items to a collection of ItemData objects.
            collect(data_get($data, 'items', []))->map(fn (array $item) => ItemData::fromArray($item)),
            data_get($data, 'totalItems'),
        );
    }

    /**
     * Implements Laravel's Arrayable interface to allow the object to be
     * serialized to an array.
     */
    public function toArray(): array
    {
        return [
            'kind' => $this->kind,
            'items' => $this->items->toArray(),
            'totalItems' => $this->totalItems,
        ];
    }
}

With all the new DTOs created, let’s go back to the test and update.

Test the Full DTO

<?php

use App\Actions\QueryBooksByTitle;
use App\DataTransferObjects\BooksListData;
use App\DataTransferObjects\ImageLinksData;
use App\DataTransferObjects\ItemData;
use App\DataTransferObjects\VolumeInfoData;
use Illuminate\Support\Facades\Http;

it('fetches books by title', function () {
    $title = fake()->sentence();

    // Generate a fake response from the Google Books API.
    $responseData = [
        'kind' => 'books#volumes',
        'totalItems' => 1,
        'items' => [
            [
                'id' => fake()->uuid,
                'volumeInfo' => [
                    'title' => $title,
                    'subtitle' => fake()->sentence(),
                    'authors' => [fake()->name],
                    'publisher' => fake()->company(),
                    'publishedDate' => fake()->date(),
                    'description' => fake()->paragraphs(asText: true),
                    'pageCount' => fake()->numberBetween(100, 500),
                    'categories' => [fake()->word],
                    'imageLinks' => [
                        'thumbnail' => fake()->url(),
                    ],
                ],
            ],
        ],
    ];

    // Return the fake response when the client sends a request to the Google Books API.
    Http::fake(['https://www.googleapis.com/books/v1/*' => Http::response(
        body: $responseData,
        status: 200
    )]);

    $response = resolve(QueryBooksByTitle::class)($title);

    expect($response)->toBeInstanceOf(BooksListData::class)
        ->and($response->items->first())->toBeInstanceOf(ItemData::class)
        ->and($response->items->first()->volumeInfo)->toBeInstanceOf(VolumeInfoData::class)
        ->imageLinks->toBeInstanceOf(ImageLinksData::class)
        ->title->toBe($title);
});

Now in our expectations, we can see that the response is mapping all the various DTOs and correctly setting the title.

By having the action return the DTO versus the default Illuminate/Http/Client/Response, we now have type safety for the API response and get better autocompletion in the editor which greatly improves the developer experience.

Create Test Response Helpers

One other bonus tip for this test that I like to do is create something like a response factory. It is time-consuming to mock out the responses on every single test that you might need for querying books, so I prefer to create a simple trait that helps me mock the responses much quicker.

<?php

namespace Tests\Helpers;

use Illuminate\Support\Facades\Http;

trait GoogleBooksApiResponseHelpers
{
    /**
     * Generate a fake response for querying books by title.
     */
    private function fakeQueryBooksByTitleResponse(array $items = [], int $status = 200, bool $raw = false): void
    {
        // If raw is true, return the items array as-is. Otherwise, return a
        // fake response from the Google Books API.
        $data = $raw ? $items : [
            'kind' => 'books#volumes',
            'totalItems' => count($items),
            'items' => array_map(fn (array $item) => $this->createItem($item), $items),
        ];

        Http::fake(['https://www.googleapis.com/books/v1/*' => Http::response(
            body: $data,
            status: $status
        )]);
    }

    // Create a fake item array.
    private function createItem(array $data = []): array
    {
        return [
            'id' => data_get($data, 'id', '123'),
            'volumeInfo' => $this->createVolumeInfo(data_get($data, 'volumeInfo', [])),
        ];
    }

    // Create a fake volume info array.
    private function createVolumeInfo(array $data = []): array
    {
        return [
            'title' => data_get($data, 'title', fake()->sentence),
            'subtitle' => data_get($data, 'subtitle', 'Book Subtitle'),
            'authors' => data_get($data, 'authors', ['Author 1', 'Author 2']),
            'publisher' => data_get($data, 'publisher', 'Publisher'),
            'publishedDate' => data_get($data, 'publishedDate', '2021-01-01'),
            'description' => data_get($data, 'description', 'Book description'),
            'pageCount' => data_get($data, 'pageCount', 123),
            'categories' => data_get($data, 'categories', ['Category 1', 'Category 2']),
            'imageLinks' => data_get($data, 'imageLinks', ['thumbnail' => 'https://example.com/image.jpg']),
        ];
    }
}

To use the trait in a Pest test, we just need to use the uses method.

uses(GoogleBooksApiResponseHelpers::class);

With that, we can now easily add additional tests without needing to have all the mock data written in each test.

<?php

use App\Actions\QueryBooksByTitle;
use App\DataTransferObjects\BooksListData;
use App\DataTransferObjects\ImageLinksData;
use App\DataTransferObjects\ItemData;
use App\DataTransferObjects\VolumeInfoData;
use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Facades\Http;
use Tests\Helpers\GoogleBooksApiResponseHelpers;

uses(GoogleBooksApiResponseHelpers::class);

it('fetches books by title', function () {
    $title = fake()->sentence();

    // Generate a fake response from the Google Books API.
    $this->fakeQueryBooksByTitleResponse([['volumeInfo' => ['title' => $title]]]);

    $response = resolve(QueryBooksByTitle::class)($title);

    expect($response)->toBeInstanceOf(BooksListData::class)
        ->and($response->items->first())->toBeInstanceOf(ItemData::class)
        ->and($response->items->first()->volumeInfo)->toBeInstanceOf(VolumeInfoData::class)
        ->imageLinks->toBeInstanceOf(ImageLinksData::class)
        ->title->toBe($title);
});

it('passes the title as a query parameter', function () {
    $title = fake()->sentence();

    // Generate a fake response from the Google Books API.
    $this->fakeQueryBooksByTitleResponse([['volumeInfo' => ['title' => $title]]]);

    resolve(QueryBooksByTitle::class)($title);

    Http::assertSent(function (Illuminate\Http\Client\Request $request) use ($title) {
        expect($request)
            ->method()->toBe('GET')
            ->data()->toHaveKey('q', 'intitle:'.$title);

        return true;
    });
});

it('fetches a list of multiple books', function () {
    // Generate a fake response from the Google Books API.
    $this->fakeQueryBooksByTitleResponse([
        $this->createItem(),
        $this->createItem(),
        $this->createItem(),
    ]);

    $response = resolve(QueryBooksByTitle::class)('Fake Title');

    expect($response->items)->toHaveCount(3);
});

it('throws an exception', function () {
    // Generate a fake response from the Google Books API.
    $this->fakeQueryBooksByTitleResponse([
        $this->createItem(),
    ], 400);

    resolve(QueryBooksByTitle::class)('Fake Title');
})->throws(RequestException::class);

With that, we now have cleaner tests, and our API responses are mapped to a DTO. For even more optimizations, you may consider using the Laravel Data package by Spatie to create the DTOs, it can help reduce some of the boilerplate code for having to create the fromArray and toArray methods.

Summary

In this post, you've learned how to streamline your process for developing and testing API integrations in Laravel by leveraging DTOs.

We explored the process of creating DTOs, mapping API responses to these DTOs, and developing test response helpers. This not only improved the readability of our code, but also facilitated a more type-safe, efficient, and testable development process.

The techniques discussed here and in my previous post are useful for all types of API integrations, however, for more advanced solutions, I recommend looking at the Saloon PHP library.

I hope this post proves beneficial in your future Laravel projects. Nevertheless, the discussion doesn't have to end here. Do you have extra tips or alternative methods you'd like to share? Or perhaps there are points you'd like to discuss or need clarification on? I'd love to hear your perspective! Feel free to leave a comment.

In this post, we will explore integrating the Google Books API. I will create a reusable client and request class to make using the API very simple. In future posts, I will go into more detail about testing, mocking, as well as creating API resources.

Let’s get started!

Add Google Books Configuration to Laravel

Now that we have an API key, we can add it to the .env along with the API URL.

GOOGLE_BOOKS_API_URL=https://www.googleapis.com/books/v1
GOOGLE_BOOKS_API_KEY=[API KEY FROM GOOGLE]

For this example, I am storing an API key that I obtained from the Google Cloud console, though it is not needed for the parts of the API we will be accessing. For more advanced API usage, you would need to integrate with Google’s OAuth 2.0 server and create a client ID and secret that could also be stored in the .env file. This is beyond the scope of this post.

With the environment variables in place, open the config/services.php file and add a section for Google Books.

'google_books' => [
    // Base URL for the Google Books API, retrieved from the .env
    'base_url' => env('GOOGLE_BOOKS_API_URL'),
    // API key for the Google Books API, retrieved from the .env
    'api_key' => env('GOOGLE_BOOKS_API_KEY'),
],

Create an ApiRequest Class

When making requests to the API, I find it easiest to use a simple class to be able to set any request properties I need.

Below is an example of an ApiRequest class that I use to pass in URL information along with the body, headers, and any query parameters. This class can easily be modified or extended to add additional functionality.

<?php

namespace App\Support;

/**
 * The ApiRequest class is a utility for building HTTP requests to an API.
 * It provides methods for setting the HTTP method, URI, headers, query
 * parameters, and body of the request.
 * It also provides methods for getting these properties, as well as for
 * clearing the headers, query parameters, and body.
 * Additionally, it provides static methods for creating ApiRequest instances
 * for specific HTTP methods.
 */
class ApiRequest
{
    // Store the headers that will be sent with the API request.
    protected array $headers = [];

    // Store any query string parameters.
    protected array $query = [];

    // Store the body of the request.
    protected array $body = [];

    /**
     * Create an API request for a given HTTP method and URI.
     */
    public function __construct(protected HttpMethod $method = HttpMethod::GET, protected string $uri = '')
    {
    }

    /**
     * Set headers for the request.
     * This accepts either a key and value, or an array of key/value pairs.
     */
    public function setHeaders(array|string $key, string $value = null): static
    {
        if (is_array($key)) {
            $this->headers = $key;
        } else {
            $this->headers[$key] = $value;
        }

        return $this;
    }

    /**
     * Clear headers for the request.
     * This method can clear a specific header or all headers in the request if
     * a key is not provided.
     */
    public function clearHeaders(string $key = null): static
    {
        if ($key) {
            unset($this->headers[$key]);
        } else {
            $this->headers = [];
        }

        return $this;
    }

    /**
     * Set query parameters for the request.
     * This accepts either a key and value, or an array of key/value pairs.
     */
    public function setQuery(array|string $key, string $value = null): static
    {
        if (is_array($key)) {
            $this->query = $key;
        } else {
            $this->query[$key] = $value;
        }

        return $this;
    }

    /**
     * Clear query parameters for the request.
     * This method can clear a specific parameter or all parameters if a key is
     * not provided.
     */
    public function clearQuery(string $key = null): static
    {
        if ($key) {
            unset($this->query[$key]);
        } else {
            $this->query = [];
        }

        return $this;
    }

    /**
     * Set body data for the request.
     * This accepts either a key and value, or an array of key/value pairs.
     */
    public function setBody(array|string $key, string $value = null): static
    {
        if (is_array($key)) {
            $this->body = $key;
        } else {
            $this->body[$key] = $value;
        }

        return $this;
    }

    /**
     * Clear body data for the request.
     * This method can clear a specific key of data or all data.
     */
    public function clearBody(string $key = null): static
    {
        if ($key) {
            unset($this->body[$key]);
        } else {
            $this->body = [];
        }

        return $this;
    }

    /**
     * This method returns the headers for the API request.
     */
    public function getHeaders(): array
    {
        return $this->headers;
    }

    /**
     * This method returns the query for the API request.
     */
    public function getQuery(): array
    {
        return $this->query;
    }

    /**
     * This method returns the body for the API request.
     */
    public function getBody(): array
    {
        return $this->body;
    }

    /**
     * This method returns the URI for the API request.
     * If the query is empty, or we have a GET request, the URI can be returned
     * as is.
     * Otherwise, we need to append the query string to the URI.
     */
    public function getUri(): string
    {
        if (empty($this->query) || $this->method === HttpMethod::GET) {
            return $this->uri;
        }

        return $this->uri.'?'.http_build_query($this->query);
    }

    /**
     * This method returns the HTTP method for the API request.
     */
    public function getMethod(): HttpMethod
    {
        return $this->method;
    }

    // The following methods are used to create API requests for specific HTTP
    // methods.

    public static function get(string $uri = ''): static
    {
        return new static(HttpMethod::GET, $uri);
    }

    public static function post(string $uri = ''): static
    {
        return new static(HttpMethod::POST, $uri);
    }

    public static function put(string $uri = ''): static
    {
        return new static(HttpMethod::PUT, $uri);
    }

    public static function delete(string $uri = ''): static
    {
        return new static(HttpMethod::DELETE, $uri);
    }
}

The class constructor takes an HttpMethod, which is just a simple enum with the various HTTP methods, and a URI.

enum HttpMethod: string
{
    case GET = 'get';
    case POST = 'post';
    case PUT = 'put';
    case DELETE = 'delete';
}

There are helper methods to create the request using the HTTP method name and passing a URI. Finally, there are methods to add and clear headers, query parameters, and body data.

Create an API Client

Now that we have the request, we need an API client to send it. This is where we can use the Http facade.

Abstract ApiClient

First, we’ll create an abstract ApiClient class that will be extended by our various APIs.

<?php

namespace App\Support;

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Http;

/**
 * The ApiClient class is an abstract base class for making HTTP requests to an
 * API.
 * It provides a method for sending an ApiRequest and methods for getting and
 * authorizing a base request.
 * Subclasses must implement the baseUrl method to specify the base URL for the
 * API.
 */
abstract class ApiClient
{
    /**
     * Send an ApiRequest to the API and return the response.
     */
    public function send(ApiRequest $request): Response
    {
        return $this->getBaseRequest()
            ->withHeaders($request->getHeaders())
            ->{$request->getMethod()->value}(
                $request->getUri(),
                $request->getMethod() === HttpMethod::GET
                    ? $request->getQuery()
                    : $request->getBody()
            );
    }

    /**
     * Get a base request for the API.
     * This method has some helpful defaults for API requests.
     * The base request is a PendingRequest with JSON acceptance, a content type
     * of 'application/json', and the base URL for the API.
     * It also throws exceptions for non-successful responses.
     */
    protected function getBaseRequest(): PendingRequest
    {
        $request = Http::acceptJson()
            ->contentType('application/json')
            ->throw()
            ->baseUrl($this->baseUrl());

        return $this->authorize($request);
    }

    /**
     * Authorize a request for the API.
     * This method is intended to be overridden by subclasses to provide
     * API-specific authorization.
     * By default, it simply returns the given request.
     */
    protected function authorize(PendingRequest $request): PendingRequest
    {
        return $request;
    }

    /**
     * Get the base URL for the API.
     * This method must be implemented by subclasses to provide the base URL for
     * the API.
     */
    abstract protected function baseUrl(): string;
}

This class has a getBaseRequest method that sets up some sane defaults using the Http facade to create a PendingRequest. It calls the authorize method which we can override in our Google Books implementation to set our API key.

The baseUrl method is just a simple abstract method that our Google Books class will set to use the Google Books API URL we set earlier.

Finally, the send method is what sends the request to the API. It takes an ApiRequest parameter to build up the request, then returns the response.

GoogleBooksApiClient

With the abstract client created, we can now create a GoogleBooksApiClient to extend it.

<?php

namespace App\Support;

use Illuminate\Http\Client\PendingRequest;

/**
 * The GoogleBooksApiClient class is a concrete implementation of the ApiClient
 * base class for the Google Books API.
 * It provides methods for getting the base URL and authorizing a request for
 * the Google Books API.
 */
class GoogleBooksApiClient extends ApiClient
{
    /**
     * Get the base URL for the Google Books API.
     * The base URL is retrieved from the 'services.google_books.base_url'
     * configuration value.
     */
    protected function baseUrl(): string
    {
        return config('services.google_books.base_url');
    }

    /**
     * Authorize a request for the Google Books API.
     * The Google Books API accepts the API key as a query parameter named
     * 'key'.
     * The API key is retrieved from the 'services.google_books.api_key'
     * configuration value.
     */
    protected function authorize(PendingRequest $request): PendingRequest
    {
        return $request->withQueryParameters([
            'key' => config('services.google_books.api_key'),
        ]);
    }
}

In this class, we just need to set the base URL and configure the authorization. For the Google Books API, that means passing the API key as a URL parameter and setting an empty Authorization header.

If we had an API that used a bearer authorization, we could have an authorize method like the following:

protected function authorize(PendingRequest $request): PendingRequest
{
    return $request->withToken(config(services.someApi.token));
}

The nice part about having this authorize method is the flexibility it offers to support a variety of API authorization methods.

Query Books By Title

Now that we have our ApiRequest class and GoogleBooksApiClient, we can create an action to query books by title. It would look something like this:

<?php

namespace App\Actions;

use App\Support\ApiRequest;
use App\Support\GoogleBooksApiClient;
use Illuminate\Http\Client\Response;

/**
 * The QueryBooksByTitle class is an action for querying books by title from the
 * Google Books API.
 * It provides an __invoke method that takes a title and returns the response
 * from the API.
 */
class QueryBooksByTitle
{
    /**
     * Query books by title from the Google Books API and return the response.
     * This method creates a GoogleBooksApiClient and an ApiRequest for the
     * 'volumes' endpoint
     * with the given title as the 'q' query parameter and 'books' as the
     * 'printType' query parameter.
     * It then sends the request using the client and returns the response.
     */
    public function __invoke(string $title): Response
    {
        $client = app(GoogleBooksApiClient::class);

        $request = ApiRequest::get('volumes')
            ->setQuery('q', 'intitle:'.$title)
            ->setQuery('printType', 'books');

        return $client->send($request);
    }
}

Then, to call the action, if I wanted to find information about the book The Ferryman, which I just read and highly recommend, use the following snippet:

use App\Actions\QueryBooksByTitle;

$response = app(QueryBooksByTitle::class)("The Ferryman");

$response->json();

Bonus: Tests

Below, I added some examples for testing the request and client classes. For the tests, I am using Pest PHP which provides a clean syntax and additional features on top of PHPUnit.

ApiRequest

<?php

use App\Support\ApiRequest;
use App\Support\HttpMethod;

it('sets request data properly', function () {
    $request = (new ApiRequest(HttpMethod::GET, '/'))
        ->setHeaders(['foo' => 'bar'])
        ->setQuery(['baz' => 'qux'])
        ->setBody(['quux' => 'quuz']);

    expect($request)
        ->getHeaders()->toBe(['foo' => 'bar'])
        ->getQuery()->toBe(['baz' => 'qux'])
        ->getBody()->toBe(['quux' => 'quuz'])
        ->getMethod()->toBe(HttpMethod::GET)
        ->getUri()->toBe('/');
});

it('sets request data properly with a key->value', function () {
    $request = (new ApiRequest(HttpMethod::GET, '/'))
        ->setHeaders('foo', 'bar')
        ->setQuery('baz', 'qux')
        ->setBody('quux', 'quuz');

    expect($request)
        ->getHeaders()->toBe(['foo' => 'bar'])
        ->getQuery()->toBe(['baz' => 'qux'])
        ->getBody()->toBe(['quux' => 'quuz'])
        ->getMethod()->toBe(HttpMethod::GET)
        ->getUri()->toBe('/');
});

it('clears request data properly', function () {
    $request = (new ApiRequest(HttpMethod::GET, '/'))
        ->setHeaders(['foo' => 'bar'])
        ->setQuery(['baz' => 'qux'])
        ->setBody(['quux' => 'quuz']);

    $request->clearHeaders()
        ->clearQuery()
        ->clearBody();

    expect($request)
        ->getHeaders()->toBe([])
        ->getQuery()->toBe([])
        ->getBody()->toBe([])
        ->getUri()->toBe('/');
});

it('clears request data properly with a key', function () {
    $request = (new ApiRequest(HttpMethod::GET, '/'))
        ->setHeaders('foo', 'bar')
        ->setQuery('baz', 'qux')
        ->setBody('quux', 'quuz');

    $request->clearHeaders('foo')
        ->clearQuery('baz')
        ->clearBody('quux');

    expect($request)
        ->getHeaders()->toBe([])
        ->getQuery()->toBe([])
        ->getBody()->toBe([])
        ->getUri()->toBe('/');
});

it('creates instance with correct method', function (HttpMethod $method) {
    $request = ApiRequest::{$method->value}('/');

    expect($request->getMethod())->toBe($method);
})->with([
    [HttpMethod::GET],
    [HttpMethod::POST],
    [HttpMethod::PUT],
    [HttpMethod::DELETE],
]);

The ApiRequest tests check that the correct request data is being set and the correct methods are being used.

ApiClient

Testing for the ApiClient will be a little more complex. Since it is an abstract class, we will use an anonymous class in the beforeEach function to create a client to use that extends ApiClient.

Notice, that we also use the Http::fake() method. This creates mocks on the Http facade that we can make assertions against and prevent making API requests in the tests.

<?php

use App\Support\ApiClient;
use App\Support\ApiRequest;
use App\Support\HttpMethod;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;

beforeEach(function () {
    Http::fake();

    $this->client = new class extends ApiClient
    {
        protected function baseUrl(): string
        {
            return 'https://example.com';
        }
    };
});

it('sends a get request', function () {
    $request = ApiRequest::get('foo')
        ->setHeaders(['X-Foo' => 'Bar'])
        ->setQuery(['baz' => 'qux']);

    $this->client->send($request);

    Http::assertSent(static function (Request $request) {
        expect($request)
            ->url()->toBe('https://example.com/foo?baz=qux')
            ->method()->toBe(HttpMethod::GET->name)
            ->header('X-Foo')->toBe(['Bar']);

        return true;
    });
});

it('sends a post request', function () {
    $request = ApiRequest::post('foo')
        ->setBody(['foo' => 'bar'])
        ->setHeaders(['X-Foo' => 'Bar'])
        ->setQuery(['baz' => 'qux']);

    $this->client->send($request);

    Http::assertSent(static function (Request $request) {
        expect($request)
            ->url()->toBe('https://example.com/foo?baz=qux')
            ->method()->toBe(HttpMethod::POST->name)
            ->data()->toBe(['foo' => 'bar'])
            ->header('X-Foo')->toBe(['Bar']);

        return true;
    });
});

it('sends a put request', function () {
    $request = ApiRequest::put('foo')
        ->setBody(['foo' => 'bar'])
        ->setHeaders(['X-Foo' => 'Bar'])
        ->setQuery(['baz' => 'qux']);

    $this->client->send($request);

    Http::assertSent(static function (Request $request) {
        expect($request)
            ->url()->toBe('https://example.com/foo?baz=qux')
            ->method()->toBe(HttpMethod::PUT->name)
            ->data()->toBe(['foo' => 'bar'])
            ->header('X-Foo')->toBe(['Bar']);

        return true;
    });
});

it('sends a delete request', function () {
    $request = ApiRequest::delete('foo')
        ->setBody(['foo' => 'bar'])
        ->setHeaders(['X-Foo' => 'Bar'])
        ->setQuery(['baz' => 'qux']);

    $this->client->send($request);

    Http::assertSent(static function (Request $request) {
        expect($request)
            ->url()->toBe('https://example.com/foo?baz=qux')
            ->method()->toBe(HttpMethod::DELETE->name)
            ->data()->toBe(['foo' => 'bar'])
            ->header('X-Foo')->toBe(['Bar']);

        return true;
    });
});

it('handles authorization', function () {
    $client = new class extends ApiClient
    {
        protected function baseUrl(): string
        {
            return 'https://example.com';
        }

        protected function authorize(PendingRequest $request): PendingRequest
        {
            return $request->withHeaders(['Authorization' => 'Bearer foo']);
        }
    };

    $request = ApiRequest::get('foo');

    $client->send($request);

    Http::assertSent(static function (Request $request) {
        expect($request)->header('Authorization')->toBe(['Bearer foo']);

        return true;
    });
});

For the tests, we are confirming that the request properties are being set correctly on the various request methods. We also confirm the baseUrl and authorize methods are being called correctly. To make these assertions, we are using the Http::assertSent method which expects a callback with a $request that we can test against. Notice that I am using the PestPHP expectations and then returning true. We could just use a normal comparison and return that, but by using the expectations, we get much cleaner error messages when the tests fail. Read this excellent article for more information.

GoogleBooksApiClientTest

The test for the GoogleBooksApiClient is similar to the ApiClient test where we just want to make sure our custom implementation details are being handled properly, like setting the base URL and adding a query parameter with the API key.

Also, not the config helper in the beforeEach method. By using the helper, we can set test values for the Google Books service config that will be used in each of our tests.

<?php

use App\Support\ApiRequest;
use App\Support\GoogleBooksApiClient;
use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Request;

beforeEach(function () {
    Http::fake();
    config([
        'services.google_books.base_url' => 'https://example.com',
        'services.google_books.api_key' => 'foo',
    ]);
});

it('sets the base url', function () {
    $request = ApiRequest::get('foo');

    app(GoogleBooksApiClient::class)->send($request);

    Http::assertSent(static function (Request $request) {
        expect($request)->url()->toStartWith('https://example.com/foo');

        return true;
    });
});

it('sets the api key as a query parameter', function () {
    $request = ApiRequest::get('foo');

    app(GoogleBooksApiClient::class)->send($request);

    Http::assertSent(static function (Request $request) {
        expect($request)->url()->toContain('key=foo');

        return true;
    });
});

Summary

In this article, we covered some helpful steps for integrating third-party APIs in Laravel. By using these simple custom classes, along with the Http facade, we can ensure all integrations function similarly, are easier to test, and don’t require any project dependencies. In a later post, I will expand on these integration tips by covering DTOs, testing with mock responses, and using API resources.

Thanks for reading!

Getting Started

To get started, let's create a file named ignore in the ~/.config/git folder. You may need to create this folder if it does not already exist.

mkdir -p ~/.config/git && touch ~/.config/git/ignore

In the file, we can add some patterns to ignore across all files.

# Ignore files generated by operating systems
.DS_Store
Thumbs.db

Git should automatically load this file. The patterns in the global file are merged with any other .gitignore files in your repositories.

If you wanted to put the file in another location, you would need to update the Git configuration to point to the file. For example, if I had a ~/Code/ folder where I store all of my projects, I could create my file there: ~/Code/.gitignore_global. Then, I can run the following command to update my Git configuration.

git config --global core.excludesfile ~/Code/.gitignore_global

What Should I Add to My Global Gitignore?

What other types of files can be ignored globally? A lot of developers like to ignore the default editor/IDE folders like .vscode and .idea. This would depend on your project though, some projects commit some of the files in these folders.

You can also ignore package folders like node_modules and vendor for PHP Composer.

Generated files can also usually be ignored globally. These files usually exist in the build/ or dist/ folders.

Another great ignore to add is .env. These are used in projects of all types and usually contain sensitive information like API keys and passwords, so it's nice to have some extra protection to make sure you don't accidentally commit the file.

The global .gitignore can also support things specific to your workflow. For example, when working in JetBrains IDEs, I love using scratch files to store notes and pseudo code I might have when coding. If I am using something like Vim or VSCode though, then my scratch files aren't supported. So instead, I add .scratch/ to me global .gitignore and then I can create markdown files or whatever else I might want there without it being committed. I also use .http to store JetBrains HTTP requests if I don't want them committed to the project. Read my post about the PhpStorm HTTP client and requests to learn more.

Gitignore Example

Below is my current global .gitignore:

# OS files
.DS_Store
.AppleDouble
.LSOverride
Thumbs.db
ehthumbs.db
Desktop.ini

# Editor Files
*.swp
*.swo
*.swn
*.swm
*.swl
*.swk
*.bak
*.backup
*.orig
*.ref
*~

# Logs
*.log
log.txt

# Generated files
build/
dist/

# Dependencies
node_modules/
vendor/

# Sensitive files
*.env
*.key
*.pem
*.credentials
*.password
*.secret

# Scratch files
.scratch/

# PhpStorm HTTP Requests
.http/

Conclusion

Using a global .gitignore is helpful to make sure you aren't committing files that shouldn't be committed. Most of these items should already be in the project's .gitignore, however, that might not always be the case.

Also, I don't like adding items to a project's .gitignore that don't apply to all developers, like my .http/ or .scratch. This is where a global .gitignore shines as it lets you add items relevant to your workflows.

For more information, you can refer to the GitHub documentation which has some great content including templates and links to the Git documentation.

• Ignoring files - GitHub Docs

Let me know in the comments if you have any other helpful items to add to the global .gitignore. I would love to hear about any custom workflows you might have that having the global ignore helps support. Thanks for reading!

In this guide, I'll explore how PhpStorm's HTTP Client streamlines API testing and improves my development workflow right within the IDE. I'll delve into organizing requests, utilizing variables, and even importing and exporting requests. By the end, you'll have a solid grasp of how to leverage PhpStorm's capabilities for effective API testing.

Getting Started

To keep things organized, I prefer to create a folder in my project called ".http". This allows me to store all my HTTP requests in a single place. To ensure that these requests don't get accidentally committed, I will add the ".http" folder to my global .gitignore file. Read my article about using a global gitignore for more information. However, if I ever need to share these requests with my team, I can simply store them in a folder that is committed to the repository.

For this article, I will use the JSONPlaceholder - Free Fake REST API website, which provides various API endpoints that can be used for testing purposes.

Once I have the ".http" folder in my project, I can easily create a new request file called "Posts.http". This allows me to organize all my Post-related HTTP requests in one place.

Posts Requests

Get Posts List

In my "Posts.http" file, I create a request to list all posts. I can either type this request manually or use the UI to add it. With the UI, I will click on the plus + icon and select the request type.

For listing posts, I will create a GET request. This will add the following content to the file:

GET http://localhost:80/api/item?id=99
Accept: application/json

###

I will update it to use the JSONPlaceholder - Free Fake REST API. I will remove the Accept header for now.

GET https://jsonplaceholder.typicode.com/posts

###

Once the request is ready, it's time to run it. I click the "Play" button, and the results appear in the console below.

Get Post

To get a specific post, I can add a new request to the file. I can even add comments to describe the requests, either using # or //.

# List Posts
GET https://jsonplaceholder.typicode.com/posts

###

# Get Post
GET https://jsonplaceholder.typicode.com/posts/1

Also, I make sure to separate the requests with ### which is required by the .http syntax.

Create Post

To create a new post, I’ll add a POST request and a JSON body.

# List Posts
GET https://jsonplaceholder.typicode.com/posts

###

# Get Post
GET https://jsonplaceholder.typicode.com/posts/1

###

# Create Post
POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{
  "title": "Post title",
  "body": "Post body",
  "userId": 1
}

It can also be helpful to add the Content-Type header to specify that JSON is being passed to the server.

Update Post

Updating a post is similar to creating a post, but I’ll use a PUT request.

# List Posts
GET https://jsonplaceholder.typicode.com/posts

###

# Get Post
GET https://jsonplaceholder.typicode.com/posts/1

###

# Create Post
POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{
  "title": "Post title",
  "body": "Post body",
  "userId": 1
}

###

# Update Post
PUT https://jsonplaceholder.typicode.com/posts/1
Content-Type: application/json

{
  "title": "New title"
}

Delete Post

Finally, I can delete a post using a DELETE request.

# List Posts
GET https://jsonplaceholder.typicode.com/posts

###

# Get Post
GET https://jsonplaceholder.typicode.com/posts/1

###

# Create Post
POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{
  "title": "Post title",
  "body": "Post body",
  "userId": 1
}

###

# Update Post
PUT https://jsonplaceholder.typicode.com/posts/1
Content-Type: application/json

{
    "title": "New title"
}

###

# Delete Post
DELETE https://jsonplaceholder.typicode.com/posts/1

Variables

Variables are a powerful tool when it comes to managing complex API testing scenarios. PhpStorm offers various types of variables, starting with Environment Variables.

Environment Variables

Environment variables can be used to store information such as usernames, passwords, authentication tokens, and more. They can also be used to support multiple environments. PhpStorm provides both public and private variables, which are merged before a request is made. To begin, create a public environment file.

This creates the file below:

I will update the file to store a dev and production environment with a host and authentication token.

{
    "dev": {
        "host": "<https://jsonplaceholder.typicode.com>",
        "token": ""
    },
    "prod": {
        "host": "<https://jsonplaceholder.typicode.com>",
        "token": ""
    }
}

I will leave the token empty for now and add it to the private environment file. I’ll create that now.

In this file, I will add the authentication tokens. It can also store usernames and passwords depending on the server authentication.

{
    "dev": {
        "token": "DEVELOPMENT_TOKEN"
    },
    "prod": {
        "token": "PRODUCTION_TOKEN"
    }
}

Now, I can add these variables to the requests.

# List Posts
GET {{host}}/posts
Authorization: Bearer {{token}}

###

# Get Post
GET {{host}}/posts/1
Authorization: Bearer {{token}}

###

# Create Post
POST {{host}}/posts
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "title": "Post title",
  "body": "Post body",
  "userId": 1
}

###

# Update Post
PUT {{host}}/posts/1
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "title": "New title"
}

###

# Delete Post
DELETE {{host}}/posts/1
Authorization: Bearer {{token}}

This approach saves me from having to repeat the full URL everywhere and works exceptionally well in scenarios where different environments require different hosts or tokens.

For APIs that have authorization, I can add an Authorization header with a value of Bearer {{token}}.

Before making a request, I will set the environment I want to use to replace my variables.

Per-Request Variables

Per-request variables allow me to set variables before specific requests, offering flexibility in customization. Here's how I set a per-request variable for the "Get Post" request:

# Get Post
< {%
    request.variables.set("postId", "10")
%}
GET {{host}}/posts/{{postId}}
Authorization: Bearer {{token}}

Now, when running the request, it will automatically replace postId in the URL with “10” from the postId variable. Note that request variables must be a string value.

This method is particularly useful when I need to adjust variables for specific requests without affecting global environment variables.

Response Variables

Response variables can be really powerful. They allow me to set a new variable based on the response of a request. For example, after fetching the list of posts, I can create a new postId variable that grabs the first id from the lists of posts.

# List Posts
GET {{host}}/posts
Authorization: Bearer {{token}}

> {%
    client.global.set("postId", response.body[0].id);
%}

Now, if I wanted to test updating the first post from the list, I can do the following:

# Update Post
PUT {{host}}/posts/{{postId}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "title": "New title"
}

The postId is set from previously calling the “List Posts” request, so it will be set to “1”. I can test by running the “Update Post” request.

When running the request, I can see in the console that the postId was replaced with “1” in the URL.

Dynamic Variables

Dynamic variables are kind of like helper variables. They allow automatically generating common data on the fly, like UUIDs, random integers, timestamps, and more.

As an example, if I want to delete a random post, I can use the $random.integer(1, 100) dynamic variable. This will generate a random number between 1 and 100.

# Delete Post
DELETE {{host}}/posts/{{$random.integer(1, 100)}}
Authorization: Bearer {{token}}

When running the request, I see the following output, where the random number is 96.

For a complete list of available dynamic variables, refer to the documentation.

Importing and Exporting Requests

PhpStorm's built-in HTTP client simplifies importing and exporting requests, making it easy to transition my workflow. It handles importing cURL requests and even Postman collections.

cURL

With the following cURL code, I can import it right into a request file.

curl -X POST --location "<https://jsonplaceholder.typicode.com/posts>" \\ 
-H "Authorization: Bearer DEVELOPMENT_TOKEN" \\ 
-H "Content-Type: application/json" \\ 
-d "{ \\"title\\": \\"Post title\\", \\"body\\": \\"Post body\\", \\"userId\\": 1 }"

To import, I click the import button and select the import type, cURL for this example.

This will bring up a new window to paste in the cURL code.

After clicking convert, the cURL request is now added to the file as an HTTP request.

For exporting requests, I simply click the export button, select the environment to use for variable conversion, and the cURL code for the request is copied automatically.

Postman

If I'm transitioning from Postman, JetBrains offers a plugin that allows me to import Postman collections into PhpStorm's HTTP requests. This plugin can ease the migration process.

Conclusion

PhpStorm's built-in HTTP client and requests functionality offers an array of features that have significantly enhanced my API testing process. Beyond simplifying basic requests, I can execute JavaScript logic within < {% %} blocks, handle cookies, and even accommodate GraphQL requests. This all-in-one approach saves me the hassle of switching between different applications like Postman or Insomnia.

For more in-depth information and additional features, consult the PhpStorm documentation:

• HTTP Client | PhpStorm

• Exploring the HTTP request syntax | PhpStorm

Thank you for joining me on this journey exploring PhpStorm’s HTTP client and requests!

In this article, I will use a Laravel application with Laravel Sail as an example for configuration PhpStorm.

Laravel Sail Installation

Use the following command to spin up a new Laravel application with Sail:

curl -s "https://laravel.build/phpstorm-docker" | bash

This can take several minutes to complete. Once it is done, run sail up to start the application.

/vendor/bin/sail up

Quick Tip: Add a relative folder to your PATH to enable calling binaries from Composer and Node by using the name of the binary instead of the whole path. In your .zshrc or .bashrc, add the following:

export PATH="./vendor/bin:$PATH"
export PATH="./node_modules/.bin:$PATH"

Then, instead of calling /vendor/bin/sail up, it is now possible to call sail up!

Set the PhpStorm PHP Interpreter

Open the settings window and go to the PHP section. From there, click the ... next to the CLI Interpreter box.

You may have a local PHP interpreter set up. Now you’ll want to add the Docker interpreter. Use the + in the top left and select the “From Docker, Vagrant, VM, WSL, Remote…” option.

In the next popup, select the “Docker Compose” option. This shows a list of available services included in the docker-compose.yml file. Select the laravel.test service, which is the PHP container for Sail.

Now, the new PHP interpreter should be set as the default for the project.

With the interpreter setup, let’s look at running Laravel Pint to format files.

Running Linters and Formatters in Docker Container

For this article, I will look at running Laravel Pint. However, this same method can be used for PHP CS Fixer, PHPStan, and other quality tools. Later, I will also go through how to do this with Node and tools like Prettier.

Laravel Pint

To start:

1. Go to Settings > PHP > Quality Tools.

2. Expand the Laravel Pint section and turn on the Pint.

3. Set the configuration to the interpreter pointing to the Docker container, in my case, it is laravel.test.

4. Click the three dots ... to set up Pint for the interpreter.

After clicking the three dots ..., a new window opens to allow you to add a new Pint configuration.

1. Click the plus icon + in the top left.

2. Select the interpreter pointing to the Docker container.

After selecting the interpreter and hitting "OK", the configuration should be created. The next step is to set the path and validate.

1. In the "Laravel Pint path" field, add vendor/bin/pint to point to the Pint binary in the Composer vendor directory.

2. Click the "Validate" button.

3. If everything is correct, the Pint version should be shown at the bottom.

With this set, Pint needs to be set as the external formatter. Back in Settings > PHP > Quality Tools, scroll to the bottom and click the radio for "Laravel Pint" in the "External formatters" section.

Now, the code can be reformatted using Laravel Pint from the Docker container.

In the example above, the incorrect code is underlined with a squiggly line because it does not follow the formatting set by Laravel Pint. After formatting, the class and method braces are fixed, braces are added to the conditional, and a blank line is added above the return statement.

To make this even easier, enable formatting on save. To accomplish this, go into Settings > Tools > Actions on Save and check the box for "Reformat Code".

Now, anytime a file is saved, it will automatically be formatted by Laravel Pint, running on the Docker container.

Prettier

First, install Prettier using the following command:

sail npm install --save-dev --save-exact prettier

Notice the command was prefixed with sail, which installs Prettier using the version of Node and npm on the Docker container versus the local version.

Next, similar to PHP, create a Node interpreter that points at the Docker version. Go to Settings > Languages & Frameworks > Node.js. From there, click the three dots ... next to "Node interpreter".

In the new window, click the plus + button in the top left. Then select "Add Remote...".

Just like before with PHP, select the "Docker Compose" option and select the laravel.test service.

Node is now pointing at the version in the Docker container. To continue with Prettier, go to Settings > Languages & Frameworks > JavaScript > Prettier.

In the Prettier settings:

1. Select "Automatic Prettier configuration".

2. Check "Run on save" for automatic formatting when saving a file.

Now, Prettier is all setup and running right from the Docker container. These same steps can be followed to run ESLint.

Running Tests from Docker Container

For this article, I will be using PHPUnit. However, the same steps will also apply to Pest and JavaScript test runners like Jest.

Since laravel.test is already set as the default interpreter for the project, the tests should automatically run using PHPUnit from the Docker container. This can be seen by running a test:

After running the test, the test output shows the command. You can see it was run using docker-compose pointing at the laravel.test service of the local docker-compose.yml file.

If, for some reason, this is not working, maybe an existing project with other configurations, or an alternate test framework, you can continue with the next steps.

Go into Settings > PHP > Test Frameworks. Then, click the plus + button to add a new test framework.

Select the laravel.test interpreter from the new window:

Now, a new PHPUnit Test Framework is available.

Next, modify the run configurations by going to the Run menu and selecting "Edit Configurations...".

From the new window, click the gear icon next to the "Use alternative configuration file" field.

This opens a new window to select the new remote PHPUnit configuration.

Finally, make sure the configuration is pointing to the laravel.test interpreter or the default interpreter if it is set as laravel.test.

That's it! Everything should now be set up to run PHPUnit from the Docker container.

Package Managers

You can even run your package managers like Composer and npm from the Docker container.

Composer

Go to Settings > PHP > Composer, then:

1. Select the radio for "Remote Interpreter".

2. Select laravel.test as the "CLI Interpreter".

With Composer set, go to Tools > Composer, and select a command that will be run from the Docker container.

npm

For npm, the remote Node interpreter should have already been set up from the Prettier steps above. Now, open the npm tool window.

The npm tool window will show all the scripts configured in the package.json file. Right-click on the dev script and click "Edit 'dev' Settings...".

With the new window open:

1. Set the "Node interpreter" to the Docker compose laravel.test interpreter if it is not already set.

2. Add a new environment variable: WWWUSER=sail. This prevents PhpStorm from trying to run the npm commands as the npm user.

Now, the dev script can be run from the npm tool window and the output is shown in PhpStorm.

Conclusion

I hope this is helpful for anyone working on a project with a Docker configuration. Though running these scripts and binaries from Docker can be slower than running locally, it does have the benefit of making sure all the developers on the project are running the same versions. This should help prevent the infamous "it runs on my computer" type issues. By using Docker, these various languages, scripts, and binaries also do not need to be installed locally. I can have all of this running without even having Node installed on my local machine.

Thanks for reading! Please let me know if you have any questions in the comments.

Recently, I was presented with a problem using value objects with the Laravel Data package by Spatie. I have been trying to use value objects a lot more in my code for things like money, emails, phone numbers, etc. When I am working with data from an external API, it is very helpful to convert this data to value objects when I can.

If you haven’t been using value objects or data transfer objects, here are some helpful articles to learn more:

• Value Objects Everywhere — Martin Joo

• Is it a DTO or a Value Object — Matthias Noback

• Building Resilient Code: Harnessing the Power of Value Objects

When using my own custom data transfer objects, I can create fromArray and toArray methods to automatically instantiate these value objects. However, Laravel Data provides a lot of nice features out of the box that can help reduce some of the boilerplate code in my data transfer objects. The problem is, I didn’t know the best ways to use Laravel Data to instantiate my value objects. I knew of some of the various features of Laravel Data, like casts and transformers, but had never used them, until now.

In my project, I receive order data from an API. The order data that comes into the application might look something like the following:

{
    "id": 123,
    "user_id": 345,
    "product_id": 678,
    "amount": "10.99",
    "status": "success",
    "processed_at": "2023-09-30T10:00:00+00:00",
    "created_at": "2023-09-28T10:00:00+00:00",
    "updated_at": "2023-09-30T10:00:00+00:00",
}

To model this in Laravel Data, I could have a class like the following:

class OrderData extends Data
{
    public function __construct(
        public int $id,
        public int $user_id,
        public int $product_id,
        public string $amount,
        public string $status,
        public string $processed_at,
        public string $created_at,
        public string $updated_at,
    ) {}
}

This will map the data from the API fine, but it can be a lot better. The first thing that jumps out to me is the amount comes in as a string. In my application, I typically prefer to deal with monetary values as cents using integers. However, maybe I have another external service that is expecting monetary values to be passed as a float. This is a great case for using a value object so I am not constantly doing these conversions all over the application.

Here’s a simple example of what my Currency value object might look:

class Currency
{
    public readonly string $display;
    public readonly int $cents;
    public readonly float $dollars;

    public function __construct(
        public readonly mixed $value,
    )
    {
        match (true) {
            is_int($value) => $this->cents = $value,
            is_float($value) => $this->cents = $this->floatToCents($value),
            is_string($value) => $this->cents = $this->stringToCents($value),
            default => throw new InvalidArgumentException('Invalid value for Currency'),
        };

        $this->dollars = $this->cents / 100;
        $this->display = number_format($this->dollars, 2);
    }

    private function floatToCents(float $value): int
    {
        return (int) (round($value, 2) * 100);
    }

    private function stringToCents(string $value): int
    {
        return $this->floatToCents((float) $value);
    }
}

The Currency class can accept an integer, string, or float value, and convert as needed into a cents integer. However, it also gives me the option to get a dollar float value or even a display string. It also has some built-in validation to make sure any other value that might be passed into this class will throw an exception. This is just a simple example and in a normal application, you might also be tracking the type of currency or need some additional validation, but this will work for my purposes right now.

So now, I can update my OrderData class to the following:

class OrderData extends Data
{
    public function __construct(
        public int $id,
        public int $user_id,
        public int $product_id,
        public Currency $amount,
        public string $status,
        public string $processed_at,
        public string $created_at,
        public string $updated_at,
    ) {}
}

Now the $amount is a Currency type. However, Laravel Data does not know how to instantiate this object. This is where a cast comes into play. A cast in Laravel Data is used to convert simple API data into a complex object. To create this in Laravel Data, I need a class that implements the Spatie\LaravelData\Casts\Cast interface, which looks like the following:

interface Cast
{
    public function cast(DataProperty $property, mixed $value, array $context): mixed;
}

The $property parameter is an object that represents the property on the Laravel Data object and stores various information about the property. You can read more here. The $value parameter is the value that is being passed into the Laravel data object for the property, in my case, this will be the money string "10.99". Finally, the $context array is an array of the rest of the data being passed into the data object.

A cast implementation for my Currency object looks like the following:

class CurrencyCast implements Cast
{
    public function cast(DataProperty $property, mixed $value, array $context): Currency
    {
        return new Currency($value);
    }
}

Pretty simple right? I just need to return a new Currency object by passing the $value to it. To make this work with my data object, I can use a property attribute:

class OrderData extends Data
{
    public function __construct(
        public int $id,
        public int $user_id,
        public int $product_id,
        #[WithCast(CurrencyCast::class)]
        public Currency $amount,
        public string $status,
        public string $processed_at,
        public string $created_at,
        public string $updated_at,
    ) {}
}

Now, any time my OrderData object is created, instead of just having a string value for $amount, I now have a much more helpful Currency object.

This can still be improved though! This data object has three different date strings and I’d prefer to use those as a Carbon object in Laravel. You can think of a Carbon date as a value object and I want to cast my various dates to that. The good news, this comes out of the box in Laravel Data, all I need to do is update the types in my object.

class OrderData extends Data
{
    public function __construct(
        public int $id,
        public int $user_id,
        public int $product_id,
        #[WithCast(CurrencyCast::class)]
        public Currency $amount,
        public string $status,
        public Carbon $processed_at,
        public Carbon $created_at,
        public Carbon $updated_at,
    ) {}
}

Now, if I create a new data object, I have Carbon instances instead of strings.

$data = OrderData::from([
    'id' => 123,
    'user_id' => 345,
    'product_id' => 678,
    'amount' => "10.99",
    'status' => "success",
    'processed_at' => '2023-09-30T10:00:00+00:00',
    'created_at' => '2023-09-28T10:00:00+00:00',
    'updated_at' => '2023-09-30T10:00:00+00:00',
]);

$data->processed_at::class;
// "Carbon\Carbon"

You might be wondering how this works since I didn’t use a cast anywhere. As I mentioned, this is built-in with Laravel Data and it is handled in the configuration file using a global cast.

// /app/config/data.php

return [
    ...
    /*
     * Global casts will cast values into complex types when creating a data
     * object from simple types.
     */
    'casts' => [
        DateTimeInterface::class => Spatie\LaravelData\Casts\DateTimeInterfaceCast::class,
        BackedEnum::class => Spatie\LaravelData\Casts\EnumCast::class,
    ],
    ...
];

When Laravel Data runs across a complex type, it will first check if a Cast has been configured in the object definition, and if not, it will attempt to fall back to the global casts. For Carbon, this is the DateTimeInterfaceCast. If Laravel Data sees a property that has a type that implements the DateTimeInterface, which Carbon does, it will attempt to cast the value of that property to the type specified.

Now, imagine I have many other data transfer objects that might contain monetary values, which could be integers, strings, or floats. Instead of explicitly adding the cast attribute in each data transfer object, it can instead be added to the global casts array.

return [
  ...
  /*
   * Global casts will cast values into complex types when creating a data
   * object from simple types.
   */
  'casts' => [
      DateTimeInterface::class => Spatie\LaravelData\Casts\DateTimeInterfaceCast::class,
      BackedEnum::class => Spatie\LaravelData\Casts\EnumCast::class,
      \App\ValueObjects\Currency::class => \App\Data\Casts\CurrencyCast::class,
  ],
  ...
];

With the global cast set, the OrderData object no longer needs the cast attribute:

class OrderData extends Data
{
    public function __construct(
        public int $id,
        public int $user_id,
        public int $product_id,
        public Currency $amount,
        public string $status,
        public Carbon $processed_at,
        public Carbon $created_at,
        public Carbon $updated_at,
    ) {}
}

Though not necessarily a value object, the $status can also be improved here. Let’s say status can be one of three values, “pending”, “success”, or “failed”. This is a perfect case for an enum in PHP which could look like the following:

enum OrderStatus: string
{
    case PENDING = 'pending';
    case SUCCESS = 'success';
    case FAILED = 'failed';
}

To handle this in the Laravel Data object, I just need to update the type:

class OrderData extends Data
{
    public function __construct(
        public int $id,
        public int $user_id,
        public int $product_id,
        public Currency $amount,
        public OrderStatus $status,
        public Carbon $processed_at,
        public Carbon $created_at,
        public Carbon $updated_at,
    ) {}
}

Similar to the Carbon casts, Laravel Data has built-in support for casting to enums using Spatie\LaravelData\Casts\EnumCast::class.

I’ve covered using casts in Laravel Data, now I will move on to transformers. A transformer is essentially the opposite of a cast. A transformer takes a complex object and converts it to simple values to pass to JSON.

In my OrderData example, if I wanted to pass the data to another API, I probably don’t want to pass Currency or Carbon objects. When I convert my OrderData instance to JSON, I get something like the following:

{
    "id": 123,
    "user_id": 345,
    "product_id": 678,
    "amount": {
        "display": "$10.99",
        "cents": 1099,
        "dollars": 10.99,
        "value": "10.99"
    },
    "status": "success",
    "processed_at": "2023-09-30T10:00:00+00:00",
    "created_at": "2023-09-28T10:00:00+00:00",
    "updated_at": "2023-09-30T10:00:00+00:00"
}

Some good news and bad news. Like the built-in casts, Laravel Data has built-in transformers for BackedEnum and DateTimeInterface objects, so my $status field and various date fields have been converted to strings. However, my $amount field is incompatible with the API I am calling. I need that data back into a string, so I need a custom transformer class.

To create the transformer, I need to use the Spatie\LaravelData\Transformers\Transformer interface:

interface Transformer
{
    public function transform(DataProperty $property, mixed $value): mixed;
}

So, for my Currency object, a transformer could look like the following:

class CurrencyTransformer implements Transformer
{
    public function transform(DataProperty $property, mixed $value): string
    {
        return $value->display;
    }
}

With that in place, I can add an attribute to my OrderData class.

class OrderData extends Data
{
    public function __construct(
        public int $id,
        public int $user_id,
        public int $product_id,
        #[WithTransformer(CurrencyTransformer::class)]
        public Currency $amount,
        public OrderStatus $status,
        public Carbon $processed_at,
        public Carbon $created_at,
        public Carbon $updated_at,
    ) {}
}

Now, when converting to JSON, my output looks like the following:

{
    "id": 123,
    "user_id": 345,
    "product_id": 678,
    "amount": "10.99",
    "status": "success",
    "processed_at": "2023-09-30T10:00:00+00:00",
    "created_at": "2023-09-28T10:00:00+00:00",
    "updated_at": "2023-09-30T10:00:00+00:00"
}

Just like global casts, global transformers can be configured as well.

I hope this article for learning how to use casts and transformers in Laravel Data to work with value objects. Refer to the documentation for more information:

• Creating a transformer | laravel-data

• Creating a cast | laravel-data

Laravel Data is an extremely useful package and is very flexible to support whatever needs may arise. To learn more, I recommend looking into pipelines for Laravel Data as a next step.

Thanks for reading!

How many times have you worked on an application and you needed a random alpha-numeric string? Did you try to provide a list of numbers and characters in a string and pass in a length to randomly generate a string with a loop?

Using Node.js, this can be a lot simpler. You just need to use the crypto library which is built-in.

const { randomBytes } = require(“node:crypto”);

function randomString(length) {
  if (length % 2 !== 0) {
    length++;
  }

  return randomBytes(length / 2).toString("hex");
}

const string = randomString(8);
// string = "df5ec630"

A few issues with this is the length passed to the randomBytes method needs to be an even number so it can be divided in half. Otherwise, the string returned will be twice the length of the length passed in. This is why the condition is part of the function.

As a bonus, if you just quickly need a random string to use outside of an application, you can just go into your terminal, type node to go into the REPL, then add require(‘node:crypto’).randomBytes(8).toString(‘hex’).

node
Welcome to Node.js v20.4.0.
Type ".help" for more information.
> require('node:crypto').randomBytes(8).toString('hex')
'568b6620639fdf54'

If you want to generate a random string without even going into the REPL, you could use the following:

node -e “console.log(require(‘node:crypto’).randomBytes(8).toString(‘hex’))”

On a Mac, you can even add | pbcopy to the command to have the string copy right to your clipboard.

node -e “console.log(require(‘node:crypto’).randomBytes(8).toString(‘hex’))” | pbcopy

Just remember, when using the command from the terminal or REPL, the length passed to randomBytes will be half the length of what is outputted. So if you need a random string of 8 characters, pass 4 as the length.

I hope this quick tip was helpful. Let me know if the comments if you’ve seen any optimizations to the code above or if there’s an easier way to generate random strings.

Thanks for reading!

Do you use Git in the CLI or GUI? I was a heavy GUI user earlier in my career and I still do some quick operations using VSCode, PhpStorm, or Fork. At a previous company, I was forced to use GitKraken because it helped prevent developers from making Git errors. GitKraken is a great product and using the GUI tools definitely helped me become more comfortable using Git and learning the various commands. It really helps you visualize the changes being made to your repository.

However, as you start to progress in your career, you may find yourself gravitating more to the terminal to do a quick git pull, git push, or git commit. Or maybe you’re already an experienced Git user and do all your work in the CLI.

Using Git aliases in the CLI can make you even more efficient. That’s where Oh My Zsh comes in. Oh My Zsh is a framework for managing your Zsh configuration. Zsh is a shell similar to Bash but with some nice additional features. You can navigate to directories without typing cd. It offers spelling correction, plugins, themes, etc. One of my favorite features is the previous command search. I can start typing a command, then push “up” to see previous commands I’ve used starting with the text I already typed. If you are using a Mac, you’ve likely already have Zsh installed and running as the default. Otherwise, you can actually refer to the Oh My Zsh docs to install it.

Once you are running Zsh, the next step is to install Oh My Zsh. This can be done using a simple curl or wget command:

sh -c “$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

sh -c "$(wget https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh -O -)"

Once installed, you’ll want to edit your .zshrc file, and look for the plugins array and make sure git is added. It should look something like the following:

plugins=(
  git
)

Once that is in place go ahead and source your .zshrc file, or just restart your terminal.

Now, we have a ton of aliases for common Git commands.

Here’s some of my favorites:

Commits

gcmsg ‘Commit messsage’ # Equivalent to git commit -m ‘Commit message’

Amend all files to previous commit

Sometimes I add a commit and realize I forgot to modify a file, so I make the change and then I want to amend the change into the previous commit.

gcan! # Equivalent to git commit — verbose — all — no-edit — amend

Work in progress

This creates a commit with the message --wip-- [skip ci] with all your currently modified files.

gwip

Pushing and Pulling

gl # Equivalent to git pull

gp # Equivalent to git push

Git force push with lease

You always need to be careful with force pushing a branch. One of the best things to do is force push with lease. This means the force push will fail if someone else has added additional commits to the remote branch.

ggfl # Equivalent to git push — force-with-lease

Branches

The aliases for creating and checking out branches are some of my most used.

gcb my-new-branch # Equivalent to git checkout -b my-new-branch

gco - # Equivalent to git checkout — which checks out the previous branch

gcm # Equivalent to git checkout main

Rebasing

I use tend to use git rebase pretty often. It’s definitely something that using a GUI really helped me understand what it was doing. I use git rebase to add my commits onto another branch. I also use git rebase -- interactive HEAD~3 to reorder and modify commits, in this case, HEAD~3 refers to the last three commits.

grb {branch} # Equivalent to git rebase {branch}

grbi HEAD~3 # Equivalent to git rebase — interactive HEAD~3

Diff and Log

gd # Equivalent to git diff

Git log

When I want to quickly see a one line version of all the previous commits, I use the glog alias.

glog # Equivalent to git log — oneline — decorate — graph

For a complete list of aliases available in the plugin, click here.

If you are using a different shell, like bash or fsh, there may be similar plugins available, but if not, you can still easily create you own aliases in your config file, like .bashrc. Or maybe there is a common Git commands (or CLI commands in general) that you use often enough to warrant an alias.

alias gc=’git commit -m’

Thanks for reading! I hope this will help you improve you Git CLI skills. Let me know if you have any other common Git aliases you use, either from the plugin or custom aliases you have created.

This post should help you set up Visual Studio Code to use for PHP and Laravel development. It is a solid base configuration that can be expanded upon using additional workspace-specific configurations. I will cover the best extensions to use as well as some helpful configuration settings and external tools.

Let’s get started with the most important extensions!

Intelephense

• PHP Intelephense - Visual Studio Marketplace

• Intelephense

This is the most important extension to install for PHP support. It provides a fast language server that adds code completion, go-to definition, formatting, and more. You can also purchase a license at Intelephense, which I highly recommend. It adds some additional features like renaming symbols and other code actions.

Once installed, disable the built-in PHP features so Intelephense is used instead:

If a license was purchased, use cmd+shift+p to bring up the Command Palette and search for “Enter licence key”.

For the most part, the default settings are fine for Intelephense. At a workspace level, setting the document path and PHP version can be helpful if working on multiple PHP projects and frameworks.

Finally, if Intelephense will be used for formatting (versus an external tool like PHP CS Fixer or Pint), then set it as the default formatter for PHP files. This is done by pulling up the JSON version of the settings.

"[php]": {
    "editor.defaultFormatter": "bmewburn.vscode-intelephense-client"
},

Phpactor

• phpactor/phpactor: Mainly a PHP Language Server with more features than you can shake a stick at

• phpactor/vscode-phpactor: Phpactor VS Code Extension

This is both an external tool and an extension. However, the extension is not available in the VSCode extension marketplace and needs to be installed manually. The extension provides a lot more helpful code actions like replacing a qualifier with an import and adding return types.

First, install Phpactor by using the instructions or following the steps below:

# Download phpactor.phar
curl -Lo phpactor.phar https://github.com/phpactor/phpactor/releases/latest/download/phpactor.phar

chmod a+x phpactor.phar # update permissions
mv phpactor.phar ~/.local/bin/phpactor # move file into path

# Check the installation
phpactor status

With Phpactor installed on the system, the next step is to install the plugin. Download the latest release (phpactor.vsix). Then install in VSCode either by importing the plugin or using the CLI.

code --install-extension /path/to/phpactor.vsix

With the plugin installed, Phpactor will index the workspace and then add new code actions. The screenshots below show replacing a qualifier with a namespace and adding return types.

Laravel Extra Intellisense

• Laravel Extra Intellisense - Visual Studio Marketplace

This plugin adds additional autocompletion for things like views and routes. For example, in the routes/web.php file, a list of available views displays in the autocompletion popup:

It also adds autocompletion for Laravel validation rules and configuration.

Laravel Goto

• Laravel Goto - Visual Studio Marketplace

This plugin is used to quickly navigate to view, config, and other files in a Laravel application just by hovering over the string. For example, in the routes/web.php file again, when hovering over “welcome” and popup appears to navigate directly to the welcome.blade.php file. The opt+; shortcut can also be used to navigate to the file.

Laravel Blade Snippets

• Laravel Blade Snippets - Visual Studio Marketplace

This plugin adds syntax highlighting for .blade.php files as well as helpful snippets. It can even be used to format Blade files if desired. However, later in this post, Prettier will be set up to format Blade files.

Better Pest / Better PHPUnit

• m1guelpf/better-pest: A better Pest test runner for VS Code

• calebporzio/better-phpunit: A better PHPUnit test runner for VS Code

These plugins provide easy keybindings for running tests. If the project uses Pest, use the Better Pest extension, otherwise, use Better PHPUnit. These plugins can also be enabled/disabled specifically for workspaces as well if using multiple projects.

The following keybindings are provided by default to run a specific test depending on the cursor location or run all the tests in the file, or the previously run test(s).

{
    "key": "cmd+k cmd+r",
    "command": "better-pest.run"
},
{
    "key": "cmd+k cmd+f",
    "command": "better-pest.run-file"
},
{
    "key": "cmd+k cmd+p",
    "command": "better-pest.run-previous"
}

Refer to the docs for additional settings to set up with Docker or other more advanced configurations.

Prettier

• Prettier - Code formatter - Visual Studio Marketplace

Prettier is an opinionated framework for formatting JavaScript/TypeScript files. It is highly recommended for formatting React and Vue files if using something like Inertia. It can also format other file types, like JSON and Markdown. After installing the extension, also install Prettier into the project:

npm install --save-dev --save-exact prettier

Once installed, the command palette (cmd+shift+p) can be opened and use the Prettier: Create Configuration File to create a .prettierrc file in the project. See the following for a list of configurable rules: Options · Prettier.

Additional plugins can be added to support more features and languages for Prettier as well, such as Blade support. Install the shufo/prettier-plugin-blade plugin and add it to the config file:

npm install --save-dev @shufo/prettier-plugin-blade prettier

// .prettierrc
{
  "plugins": ["@shufo/prettier-plugin-blade"],
  "overrides": [
    {
      "files": ["*.blade.php"],
      "options": {
        "parser": "blade",
        "tabWidth": 4
      }
    }
  ]
}

It can even sort Tailwind CSS classes in Blade files by using the sortTailwindcssClasses option. Look at the Github repo for additional settings.

To set the Prettier as the default formatter for various file types, use the following settings in VSCode:

{
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[svelte]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[blade]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

Laravel IDE Helper

• barryvdh/laravel-ide-helper: IDE Helper for Laravel

Though this is not an extension for VSCode, the Laravel IDE Helper greatly improves the development experience in the editor. It generates helper files for Laravel applications to have better autocompletion support for various magic methods in Laravel that Intelephense cannot resolve. It can analyze models, migrations, facades, and more. Install it with composer.

composer require --dev barryvdh/laravel-ide-helper

Once installed, new Artisan commands are available to generate the helper files. The following are the most useful.

php artisan ide-helper:generate # Generate PHPDocs for facades
php artisan ide-helper:meta # Generate meta file to add support for the factory pattern
php artisan ide-helper:models # Generate PHPDocs for models

For the models generation, it is possible to add PHPDocs directly to the model files or use an external file. The former tends to be more accurate but adds a lot of comments to the files. The latter is cleaner but sometimes go-to definition goes to the generated file versus the actual model. Decide what works best for the project.

When the commands are run, VSCode can now autocomplete fields on models, like the email field on the User model below.

This can be made even simpler by adding some scripts to the composer.json file. First, create an ide-helper script to run the various commands. The script below writes the PHPDocs externally for the models versus on the models themselves.

"ide-helper": [
    "@php artisan ide-helper:generate",
    "@php artisan ide-helper:meta",
    "@php artisan ide-helper:models -N --reset"
]

Next, update the post-update-cmd script. This will automatically run the ide-helper script when running composer update.

"post-update-cmd": [
    "@php artisan vendor:publish --tag=laravel-assets --ansi --force",
    "Illuminate\\Foundation\\ComposerScripts::postUpdate",
    "@composer ide-helper"
]

To take this one step further, VSCode tasks can be configured to run this command from within VSCode and even assign it to a shortcut.

To create the tasks.json file, use cmd+shift+p to open the command palette, the search for Tasks: Configure Task. Inside the menu select the Create tasks.json file from template, then select Others. This creates a tasks.json file inside the .vscode directory in the project. In the tasks.json file, add the following:

"tasks": [
    {
        "label": "Laravel IDE Helper",
        "type": "shell",
        "command": "composer ide-helper"
    }
]

Now this command can be run from the command palette by going to Tasks: Run Task.

Finally, to add a keyboard shortcut for the tasks, add the following to the keybindings.json:

{
    "key": "cmd+shift+.",
    "command": "workbench.action.tasks.runTask",
    "args": "Laravel IDE Helper"
}

Now clicking cmd+shift+. will quickly run the IDE helper.

Other Helpful Extensions

• Tailwind CSS IntelliSense - Visual Studio Marketplace Provides better autocompletion and previews for Tailwind CSS classes.

• GitLens — Git supercharged - Visual Studio Marketplace Provides useful Git information right in the editor, like the current line blame.

• Laravel Docs - Visual Studio Marketplace Search and open Laravel documentation from the command palette.

• Laravel Artisan - Visual Studio Marketplace Run Artisan commands from the command palette.

• PHP Debug - Visual Studio Marketplace An extension to use Xdebug from within VSCode.

• Composer - Visual Studio Marketplace Run Composer commands and code actions from within VSCode.

• php cs fixer - Visual Studio Marketplace Adds PHP CS Fixer as an available formatter for PHP files.

Conclusion

I hope this guide will help make you a much more efficient Laravel developer. Visual Studio Code is a powerful editor and with the right extensions and configuration is an excellent editor for PHP and Laravel development.

It is not quite as powerful as PhpStorm (especially with the Laravel Idea package) and requires more work to configure. However, for a free-to-use editor, it is tough to beat. Though I highly recommend PhpStorm, I know a lot of developers have experience with VSCode and may be doing more than just PHP development so the change may not be worth it.

Please let me know in the comments if there’s anything else you would like me to cover or expand on, like Laravel Sail support or additional tools like Phpstan/Larastan. Also, let me know if there are any other helpful extensions or configurations I might have missed.

Finally, below I provided an example of the settings I use in VSCode.

Settings

Here’s an example of the settings I use in VSCode for PHP and Laravel development. I also make heavy use of workspace-specific settings to further customize my setup for individual projects.

{
    "files.autoSave": "onFocusChange",
    "files.defaultLanguage": "markdown",
    "files.encoding": "utf8",
    "files.eol": "\n",
    "files.insertFinalNewline": true,
    "files.trimFinalNewlines": true,
    "files.trimTrailingWhitespace": true,


    // ********************
    // Formatting
    // ********************
    "prettier.endOfLine": "lf",


    // ********************
    // Language Settings
    // ********************

    // JavaScript/TypeScript
    "javascript.preferences.quoteStyle": "single",
    "typescript.preferences.quoteStyle": "single",
    "typescript.updateImportsOnFileMove.enabled": "always",
    "javascript.updateImportsOnFileMove.enabled": "always",
    "javascript.preferences.importModuleSpecifier": "relative",
    "typescript.preferences.importModuleSpecifier": "relative",
    "[javascript]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "editor.formatOnSave": true
    },
    "[javascriptreact]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "editor.formatOnSave": true
    },
    "[typescript]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "editor.formatOnSave": true
    },
    "[typescriptreact]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "editor.formatOnSave": true
    },
    "[svelte]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "editor.formatOnSave": true
    },
    "[vue]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "editor.formatOnSave": true
    },

    // CSS
    "tailwindCSS.emmetCompletions": true,
    "tailwindCSS.includeLanguages": {
      "Typescript": "typescriptreact"
    },

    // PHP
    "php.validate.enable": false,
    "php.suggest.basic": false,
    "[php]": {
      "editor.defaultFormatter": "bmewburn.vscode-intelephense-client"
    },
    "[blade]": {
      "editor.autoClosingBrackets": "always",
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "editor.formatOnSave": true
    },
    "intelephense.telemetry.enabled": false,

    // JSON
    "[json]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "editor.formatOnSave": true
    },
    "[jsonc]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode"
    }
}