Forem: Sean Kegel

Elevate Your Laravel Eloquent Queries with Tappable Scopes

Sean Kegel — Tue, 23 Apr 2024 11:57:13 +0000

In this article, I want to go over how to use tappable scopes in Laravel. I’ve used similar patterns in Java Spring Boot, but never really considered using it in Laravel until I read Unorthodox Eloquent by Muhammed Sari which is an excellent guide to many advanced features in Laravel Eloquent.

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!

Laravel Cache Classes

Sean Kegel — Tue, 23 Apr 2024 11:54:08 +0000

I’ve been working on a Laravel project that requires numerous database calls, so I have started implementing caching to try to improve performance and reduce database queries.

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!

Fix Flaky Tests with Pest Repeat

Sean Kegel — Sun, 25 Feb 2024 20:34:10 +0000

I recently ran into an issue with a flaky test in our CI process. Most of the time, it would pass, but when it failed, it meant running all the tests again and hoping it would pass on the next try.

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, Id be confused about what was going on in CI.

Thats 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 Ive seen is data not being cleaned up properly between tests, so something created in one test is affecting the next test. Another is timestamps. Ive 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 cant 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!

What I’m Reading - January 2024

Sean Kegel — Sun, 04 Feb 2024 15:23:24 +0000

RSS, Modular Laravel, React Complexity, Dev tooling, and Event Sourcing

We finally made it through January! It always seems like such a long month and it was a busy one for me. I’ve been working on a large project at work, freelancing, side projects, and this blog.

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.

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 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.

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!

Handling Errors with Third-Party APIs

Sean Kegel — Tue, 30 Jan 2024 00:19:07 +0000

Learn how to create, throw, and handle custom exceptions when making requests to third-party APIs

This is the fourth part of my series on Integrating Third-Party APIs in Laravel. If you haven’t been following along, I highly recommend checking out the previous posts to gain the necessary context for a better understanding of this post.

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!

Creating API Resources in Laravel

Sean Kegel — Tue, 16 Jan 2024 02:02:12 +0000

Using controller-like classes and Laravel-data for efficient API communication

Welcome back to my series for Integrating Third-Party APIs in Laravel. In this post, I will discuss creating API Resources. An API resource in this case is like a RESTful controller. It adds CRUD-like methods for communicating with the API when dealing with a specific resource, like books, products, users, etc. If you haven’t read the previous posts, I suggest reading them first.

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!

Streamlining API Responses in Laravel with DTOs

Sean Kegel — Tue, 05 Dec 2023 03:11:36 +0000

A comprehensive guide for creating custom Data Transfer Objects (DTOs) to enhance readability, efficiency, and testability in Laravel API integrations.

Introduction

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.

Simplifying API Integration with Laravel's Http Facade

Sean Kegel — Fri, 10 Nov 2023 03:19:13 +0000

Building a reusable API request and client class

I’ve been working a lot lately integrating third-party APIs. There are several different approaches to this such as using the third-party provided SDK. However, I feel sticking to Laravel’s Http facade is often a better choice. By using the Http facade, all third-party integrations can have a similar structure, and testing and mocking becomes a lot easier. Also, your application will have fewer dependencies. You won’t have to worry about keeping the SDK up to date or figuring out what to do if the SDK is no longer supported.

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!

Git Quick Tip: Using a Global Gitignore

Sean Kegel — Fri, 20 Oct 2023 14:28:31 +0000

Did you know Git supports a global .gitignore file that can be used across all of your local repositories?

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!

Simplify API Testing with PhpStorm HTTP Requests

Sean Kegel — Sat, 14 Oct 2023 20:05:59 +0000

A Convenient Alternative to Postman and Insomnia

API testing is a critical aspect of modern software development, ensuring that the services we build and integrate work seamlessly. While developers often rely on dedicated tools like Postman and Insomnia, what many aren't aware of is that JetBrains' IDEs, including PhpStorm, offer powerful built-in features for handling HTTP requests.

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.

![Convert cURL to HTTP Request]

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:

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

PhpStorm with Docker

Sean Kegel — Mon, 09 Oct 2023 01:14:09 +0000

Learn how to use Docker in PhpStorm with Laravel Sail

I have come across developers on social media and at various jobs having trouble setting up their editors when Docker is involved. In this article, I will go over PhpStorm and how to use it properly with Docker. When using Docker, it is usually best to run various scripts and binaries from the Docker container versus running locally. This includes linters, formatters, and even tests.

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:

Go to Settings > PHP > Quality Tools.
Expand the Laravel Pint section and turn on the Pint.
Set the configuration to the interpreter pointing to the Docker container, in my case, it is laravel.test.
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.

Click the plus icon + in the top left.
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.

In the "Laravel Pint path" field, add vendor/bin/pint to point to the Pint binary in the Composer vendor directory.
Click the "Validate" button.
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:

Select "Automatic Prettier configuration".
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:

Select the radio for "Remote Interpreter".
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:

Set the "Node interpreter" to the Docker compose laravel.test interpreter if it is not already set.
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.

Laravel Data and Value Objects

Sean Kegel — Sat, 30 Sep 2023 20:07:48 +0000

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’s some helpful articles to learn more:

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 things 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 dollars 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 actually 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 really prefer to use those as a Carbon object in Laravel. You can actually 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. Like 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 fallback 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 was helpful in learning how to use casts and transformers in Laravel Data to work with value objects. Refer to the documentation for more information:

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!

Forem: Sean Kegel

Elevate Your Laravel Eloquent Queries with Tappable Scopes

Related Links

Laravel Cache Classes

Fix Flaky Tests with Pest Repeat

What I’m Reading - January 2024

RSS, Modular Laravel, React Complexity, Dev tooling, and Event Sourcing

RSS and Blogging

Modular Laravel

Productivity and Maintainability

React Complexity

Dev Tooling

Event Sourcing

Handling Errors with Third-Party APIs

Learn how to create, throw, and handle custom exceptions when making requests to third-party APIs

Creating a Custom Exception

Throwing the ApiException

Testing

Testing the Client

Testing the Exception

Using the Response in the Exception

Additional Techniques

Summary

Creating API Resources in Laravel

Using controller-like classes and Laravel-data for efficient API communication

Getting Started

Filling out the API Resource

List Method

Show and Delete Methods

Create and Update Methods

Summary

Streamlining API Responses in Laravel with DTOs

Introduction

Map the Response Data to a DTO

Test the Response Data

Prevent HTTP Requests in Tests

Expand the DTOs

Test the Full DTO

Create Test Response Helpers

Summary

Simplifying API Integration with Laravel's Http Facade

Building a reusable API request and client class

Add Google Books Configuration to Laravel

Create an ApiRequest Class

Create an API Client

Abstract ApiClient

GoogleBooksApiClient

Query Books By Title

Bonus: Tests

ApiRequest

ApiClient

GoogleBooksApiClientTest

Summary

Git Quick Tip: Using a Global Gitignore

Getting Started

What Should I Add to My Global Gitignore?

Gitignore Example

Conclusion

Simplify API Testing with PhpStorm HTTP Requests

A Convenient Alternative to Postman and Insomnia

Getting Started

Posts Requests

Get Posts List

Get Post

Create Post

Update Post

Delete Post

Variables

Environment Variables

Per-Request Variables

Response Variables

Dynamic Variables

Importing and Exporting Requests

cURL

Postman

Conclusion

PhpStorm with Docker

Learn how to use Docker in PhpStorm with Laravel Sail

Laravel Sail Installation

Set the PhpStorm PHP Interpreter