Forem: Geni Jaho

Simplifying work with custom stubs in Laravel

Geni Jaho — Sat, 17 May 2025 16:33:25 +0000

Testing is almost always difficult when developing applications that interact with external services, APIs, or complex features. One way to make testing easier is to use stub classes. Here's how I usually work with them.

Quick intro on benefits

Stubs are fake implementations of interfaces or classes that simulate the behavior of real services. They allow you to:

Test code without calling external services
Work locally without API keys
Speed up tests by avoiding expensive API calls
Create predictable test scenarios

External Accounting Service Example

Let's look at a simple interface for an external accounting service. In reality, you don't even need an interface to do this, but it makes it easier to swap implementations, and to keep them in sync.

interface ExternalAccountingInterface
{
    public function createRecord(array $data): string;
}

Here's a real implementation that would call an external API:

class ExternalAccounting implements ExternalAccountingInterface
{
    public function __construct(
        private readonly HttpClient $client,
        private readonly string $apiKey,
    ) {}

    public function createRecord(array $data): string
    {
        $response = $this->client->post("https://api.accounting-service.com/v1/records", [
            'headers' => [
                'Authorization' => "Bearer {$this->apiKey}",
                'Content-Type' => 'application/json',
            ],
            'json' => $data,
        ]);

        $responseData = json_decode($response->getBody(), true);

        return $responseData['record_id'];
    }
}

Now, here's a fake implementation for testing:

class FakeExternalAccounting implements ExternalAccountingInterface
{
    private array $createdRecords = [];
    private bool $hasEnoughCredits = true;

    public function createRecord(array $data): string
    {
        if (! $this->hasEnoughCredits) {
            throw new InsufficientCreditsException("Not enough credits to create a record");
        }

        $recordId = Str::uuid();

        $this->createdRecords[$recordId] = $data;

        return $recordId;
    }

    // Edge case simulation
    public function withNotEnoughCredits(): self
    {
        $this->hasEnoughCredits = false;
        return $this;
    }

    // Helper methods for assertions
    public function assertRecordsCreated(array $eventData): void
    {
        Assert::assertContains(
            $eventData,
            $this->createdRecords,
            'Failed asserting that the record was created with the correct data.'
        );
    }

    public function assertNothingCreated(): void
    {
        Assert::assertEmpty($this->createdRecords, 'Records were created unexpectedly.');
    }
}

Before and After: Refactoring to Use Stubs

Before: Using Mockery

public function testCreateAccountingRecord(): void
{
    // Create a mock using Mockery
    $accountingMock = $this->mock(ExternalAccountingInterface::class);

    // Set expectations
    $accountingMock->shouldReceive('createRecord')
        ->once()
        ->with(Mockery::on(function ($data) {
            return isset($data['type']) && $data['type'] === 'invoice' &&
                   isset($data['amount']) && $data['amount'] === 99.99;
        }))
        ->andReturn('rec_123456');

    // Bind the mock
    $this->swap(ExternalAccountingInterface::class, $accountingMock);

    // Execute the test
    $response = $this->post('/api/invoices', [
        'product_id' => 'prod_123',
        'amount' => 99.99,
    ]);

    // Assert the response
    $response->assertStatus(200);
    $response->assertJson(['success' => true]);
}

After: Using the Stub

public function testCreateAccountingRecord(): void
{
    // Create an instance of our custom stub
    $fakeAccounting = new FakeExternalAccounting;

    // Bind the stub
    $this->swap(ExternalAccountingInterface::class, $fakeAccounting);

    // Execute the test
    $response = $this->post('/api/invoices', [
        'product_id' => 'prod_123',
        'amount' => 99.99,
    ]);

    // Assert the response
    $response->assertStatus(200);
    $response->assertJson(['success' => true]);

    // Assert that records were created with the expected data
    $fakeAccounting->assertRecordsCreated([
        'type' => 'invoice',
        'amount' => 99.99,
    ]);
}

Testing Edge Cases

Custom stubs make it easy to test edge cases and error scenarios:

public function testInvoiceFailsWhenNotEnoughCredits(): void
{
    // Create an instance of our custom stub
    $fakeAccounting = new FakeExternalAccounting;

    // Configure the stub to simulate not enough credits
    $fakeAccounting->withNotEnoughCredits();

    // Bind the stub
    $this->swap(ExternalAccountingInterface::class, $fakeAccounting);

    // Execute the test expecting a failure
    $response = $this->post('/api/invoices', [
        'product_id' => 'prod_123',
        'amount' => 99.99,
    ]);

    // Assert the response handles the failure correctly
    $response->assertStatus(422);
    $response->assertJson(['error' => 'Insufficient credits']);

    // Assert that no records were created
    $fakeAccounting->assertNothingCreated();
}

Swapping Stubs in Your Base Test Case

To avoid having to swap implementations in every test, you can set up your stubs in your base test case:

class TestCase extends BaseTestCase
{
    protected function setUp(): void
    {
        parent::setUp();

        // Create and register the stub for all tests
        $this->swap(ExternalAccountingInterface::class, new FakeExternalAccounting);
    }
}

Now in your tests, you can directly use the stub without having to register it, and you don't have to worry about accidentally using the real implementation, and forgetting to swap it.

class InvoiceTest extends TestCase
{
    public function testCreateInvoice(): void
    {
        // The accounting service is already swapped in the base test case
        // Just get it from the container
        $fakeAccounting = app(ExternalAccountingInterface::class);

        // Execute the test
        $response = $this->post('/api/invoices', [
            'product_id' => 'prod_123',
            'amount' => 99.99,
        ]);

        // Assert the response
        $response->assertStatus(200);

        // Use the stub's assertion methods
        $fakeAccounting->assertRecordsCreated([
            'type' => 'invoice',
            'amount' => 99.99,
        ]);
    }
}

Using Stubs During Local Development

Custom stubs aren't just useful for testing; they can also improve your local DX. Here's how to use them during development to avoid hitting API rate limits or needing API keys:

// In a service provider
public function register(): void
{
    // Only use the mock in local environment
    if ($this->app->environment('local')) {
        $this->app->bind(ExternalAccountingInterface::class, function () {
            return new FakeExternalAccounting;
        });
    } else {
        // Use the real implementation in other environments
        $this->app->bind(ExternalAccountingInterface::class, function (Application $app) {
            return new ExternalAccounting(
                $app->make(HttpClient::class),
                config('services.accounting.api_key')
            );
        });
    }
}

With this setup, your local development environment will use the fake implementation, allowing you to work without an API key and without worrying about hitting rate limits. When deployed to staging or production, the application will use the real implementation.

The best part: you can have more than one fake implementation, so you can have a different one for local development and one for running tests.

So try them out!

I'm not going to list any more benefits of using stubs, but let me say, you'll definitely have fun with them 😁.

Upgrading to Laravel 10, PHPUnit 10, and Pest 2

Geni Jaho — Sun, 17 Sep 2023 15:25:30 +0000

We're upgrading from Laravel 9 to 10, and PHPUnit 9 to 10, and, if all goes well, we'll top it off by migrating to Pest, the latest version. To keep the positive vibes on I'll skip an upgrade from PHP 8.1 to 8.2, just because I don't want to restart Docker in the production server for now. Sunday is for safe stuff only.

Remove or upgrade outdated packages

Firstly, check the dependencies guide here, and complete all the steps outlined in that section. You need to update the composer.json with the new versions, and then run composer update. It will fail, most probably. The error logs will show you which packages are incompatible or need to be updated to support the latest version.

I was using some packages that were deprecated or didn't have support for Laravel 10 as of now. Luckily, in my very specific case, I didn't really need or use them, so I just removed them. The two packages were:

CORS Middleware for Laravel - all supported Laravel versions now include the CORS middleware in the core.
Laravel Slack - helper package to make Slack notifications easier to send. I wasn't making good use of this package, and Laravel has built-in logging to Slack anyway.

After you've handled this step according to your specific case, you should now have a clean installation of Laravel 10. I'd make a commit for it.

Install Rector for Laravel

Rector will help us migrate to the new Laravel version with practically no effort. Follow the Composer installation guide here, and then install the Laravel extension. Among other configurations you might have in your rector.php file, add the Laravel 10 set:

use Rector\Config\RectorConfig;
use RectorLaravel\Set\LaravelSetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->sets([
        LaravelSetList::LARAVEL_100,
    ]);
};

Now just run vendor/bin/rector process and see what happens. It will handle most of the changes for you, like model "dates" property, the Bus facade's dispatchNow to dispatchSync, the Relation's getBaseQuery to getBaseQuery, etc. At this point, I make another commit to separate the automatic changes from my own changes.

Add the finishing touches to the upgrade

As a final step, take a good look at the upgrade guide for anything that needs your attention. There are certain things that Rector can not cover for you, like moving lang files around. You're not entirely out of luck though, there's a paid service called Shift, that has that capability and is tailored for Laravel projects. I suggest you give it a chance to prove itself, it's worth every penny. But still, double-check with the upgrade guide and see if anything's missing.

Make another commit for it if you've made any changes, and run your tests. Hopefully, everything's green.

Upgrade to PHPUnit 10

Update your PHPUnit version to "phpunit/phpunit": "^10" and run a composer update. It will probably go smoothly. The first time you'll run your tests, it will ask you to update your phpunit.xml schema to a newer version, you should run a command for that. Run it: ./vendor/bin/phpunit --migrate-configuration.

In your rector.php file add the PHPUnit rule:

use Rector\Config\RectorConfig;
use Rector\PHPUnit\Set\PHPUnitSetList;
use RectorLaravel\Set\LaravelSetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/app',
        __DIR__ . '/database',
        __DIR__ . '/tests',
    ]);

    $rectorConfig->sets([
        LaravelSetList::LARAVEL_100,
        PHPUnitSetList::PHPUNIT_100,
    ]);
};

Don't forget to include your tests directory in the paths that Rector will look for. Run ./vendor/bin/rector again and see what happens. All your tests will be migrated to the new Attributes syntax, and your data providers will be made static. If you run your tests now they should all pass, unless you've written some suspicious test classes and used $this inside your data providers, as I did 😀. And now's the time for another commit.

Migrate to Pest v2

Pest has a migration tool of its own, it's called Drift, and it's a Pest Plugin. You can install it with composer require pestphp/pest-plugin-drift --dev. To convert all your tests you simply run ./vendor/bin/pest --drift. It will remove all classes of your tests, rename the tests to use spaces instead of snake case or camel case, and convert most of the assertions to the expectation APIs.

Depending on your test structure, there might be some more work involved. For example, you might have tests in directories other than Feature or Unit, like Billing, etc. You can either specify the directories one by one in your Pest.php file, or include the whole directory to use the correct TestCase with a single line:

uses(\Tests\TestCase::class)->in('./');.

The migration will remove all classes in your tests, so if you had private helper methods, they will be converted to functions. Inside those functions, you lose access to the $this variable, so you must check each case and fix it manually, at least at the time of this post. For example, instead of $this->mock(...) you have to use just mock(...).

And now you should be good to go. Probably all or most of your tests are green.

Speed up GitHub Actions by caching Composer, Rector, & Pint

Geni Jaho — Tue, 20 Jun 2023 18:51:47 +0000

GitHub's 2000 minutes per month of free usage of GitHub Actions is usually enough to handle light workflows. However, as more tech is run automatically, we are forced to upgrade to a paid plan or optimize our workflows.

Currently, I am running Rector, Pint, and PHPUnit tests on every PR. If Rector or Pint discover something that can be improved on the PR they're configured to make another commit. That triggers another run of the pipeline.

In a modest codebase, the three of them together added up to an average of 15 minutes per execution, which is painfully a lot. By using the GitHub Actions caching mechanism we managed to bring it down to an average of 4.5 minutes. The full code and some useful links are at the bottom, here are the steps.

Caching Composer vendor

This is part of the job definition where we cache the vendor folder:

jobs:
  code-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: shivammathur/setup-php@v2
        with:
          php-version: 8.1
      - uses: actions/checkout@v3
      - name: Cache Vendor
        id: cache-vendor
        uses: actions/cache@v3
        with:
          path: vendor
          key: ${{ runner.os }}-vendor-${{ hashFiles('**/composer.lock') }}
      - name: "Install Dependencies"
        if: steps.cache-vendor.outputs.cache-hit != 'true' # Skip if cache hit
        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist

It's not much of an improvement, as Composer installs are usually fast, but you shelve off about 6-8 seconds out of every run. Caching the other stuff is much more impactful.

Caching Rector

Rector is run in parallel by default, and it's usually really fast locally. However, GitHub-hosted runners have only 2 cores, so Rector is a bit slow. On average, Rector took about 5 minutes to run, before caching.

The first thing we do is enable file-based caching in our rector.php configuration.

<?php

declare(strict_types=1);

use Rector\Caching\ValueObject\Storage\FileCacheStorage;
use Rector\Config\RectorConfig;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__.'/app',
        __DIR__.'/tests',
    ]);

    $rectorConfig->importNames();

    $rectorConfig->sets([...]);

    // Ensure file system caching is used instead of in-memory.
    $rectorConfig->cacheClass(FileCacheStorage::class);

    // Specify a path that works locally as well as on CI job runners.
    $rectorConfig->cacheDirectory('./storage/rector/cache');
};

This will also speed up your subsequent local Rector runs, as it will only check the modified files instead of the whole codebase.

Next up, in GitHub Actions we do the same caching as before, but instead of caching the vendor directory, we cache the storage/rector/cache directory, or wherever you stored your Rector cache.

jobs:
  code-quality:
    runs-on: ubuntu-latest
    steps:
      - ...
      - name: Cache Rector
        uses: actions/cache@v3
        with:
          path: ./storage/rector/cache
          key: ${{ runner.os }}-rector-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-rector-
      - name: Run Rector
        run: vendor/bin/rector --ansi

The first time the pipeline is triggered it will take the full amount of time to run. However, it will store the Rector cache and use it in subsequent runs. Depending on the number of files affected in your PRs, the Rector step now only takes a few seconds.

Caching Pint

I struggled with this a bit as Pint is built on top of PHP CS Fixer and there was no clear way on how to configure caching. I found out that PHP CS Fixer is using a cache by default, and you can specify the cache file location by providing an option when running the fixer command. However, Pint did not pass the --cache-file option to the PHP CS Fixer.

Instead, you can configure the Pint cache location in your pint.json:

{
    "preset": "laravel",
    "exclude":[...],
    "cache-file": "storage/pint.cache",
    "rules": {...}
}

You can choose whatever location fits you best. Now that we have a fixed cache location, we do the same code for GitHub Actions:

jobs:
  code-quality:
    runs-on: ubuntu-latest
    steps:
      - ...
      - name: Cache Pint
        uses: actions/cache@v3
        with:
          path: ./storage/pint.cache
          key: ${{ runner.os }}-pint-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-pint-
      - name: Run Pint
        run: ./vendor/bin/pint

This brings Pint execution down to just a few seconds as well, depending on the size of your PRs.

The complete pipeline

Here's the full code of a Laravel project pipeline that runs Rector and Pint, and does a commit to your PR with refactoring or styling changes, if needed. When the Rector and Pint job finishes, the PHPUnit tests start to run.

name: Rector, Pint & Tests

on:
  pull_request:
    branches: [ master ]

jobs:
  code-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: shivammathur/setup-php@v2
        with:
          php-version: 8.1
      - uses: actions/checkout@v3
        with:
          # Must be used to trigger workflow after push
          token: ${{ secrets.ACCESS_TOKEN }}
      - name: Cache Vendor
        id: cache-vendor
        uses: actions/cache@v3
        with:
          path: vendor
          key: ${{ runner.os }}-vendor-${{ hashFiles('**/composer.lock') }}
      - name: "Install Dependencies"
        if: steps.cache-vendor.outputs.cache-hit != 'true' # Skip if cache hit
        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
      - name: Cache Rector
        uses: actions/cache@v3
        with:
          path: ./storage/rector/cache
          key: ${{ runner.os }}-rector-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-rector-
      - name: "Run Rector"
        run: vendor/bin/rector --ansi
      - name: Cache Pint
        uses: actions/cache@v3
        with:
          path: ./storage/pint.cache
          key: ${{ runner.os }}-pint-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-pint-
      - name: "Run Pint"
        run: ./vendor/bin/pint
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: '[ci-review] Rector & Pint'
          commit_author: 'GitHub Action <actions@github.com>'
          commit_user_email: 'action@github.com'

  tests:
    runs-on: ubuntu-latest
    needs: code-quality
    services:
      mysql:
        image: mysql:8.0.25
        env:
          MYSQL_ALLOW_EMPTY_PASSWORD: false
          MYSQL_ROOT_PASSWORD: password
          MYSQL_DATABASE: my_app_test
        ports:
          - 3306/tcp
        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3
    steps:
      - uses: shivammathur/setup-php@2.23.0
        with:
          php-version: '8.1'
          extensions: mbstring, dom, fileinfo, mysql
      - uses: actions/checkout@v3
        with:
          # Must be used to trigger workflow after push
          token: ${{ secrets.ACCESS_TOKEN }}
      - name: Copy .env
        run: php -r "file_exists('.env') || copy('.env.example', '.env');"
      - name: Cache Vendor
        id: cache-vendor
        uses: actions/cache@v3
        with:
          path: vendor
          key: ${{ runner.os }}-vendor-${{ hashFiles('**/composer.lock') }}
      - name: Install Dependencies
        if: steps.cache-vendor.outputs.cache-hit != 'true' # Skip if cache hit
        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
      - name: Generate key
        run: php artisan key:generate
      - name: PHPUnit
        run: php artisan test --parallel
        env:
          DB_TEST_PORT: ${{ job.services.mysql.ports['3306'] }}

Check out these resources for more:

Doing stricter checks in PHP

Geni Jaho — Sun, 09 Apr 2023 10:41:36 +0000

A nice refactoring I've learned recently is to utilize types in conditionals.

For years I’ve been doing if (!empty($posts)), but Rector, a tool to automatically refactor code, changed that to if ($posts === []). The main advantage of using $posts === [] is that it is more explicit and less prone to unexpected behavior.

It might not seem like much, but it's quite telling of the codebase you're working with. Using $posts === [] demonstrates a higher level of attention to detail and a commitment to writing more reliable and predictable code. It shows that you are thinking about the specific requirements of your code and taking steps to ensure that it behaves as expected.

On the other hand, using !empty($posts) can suggest a more casual approach to programming, where you are relying on PHP's default behavior rather than explicitly defining the expected behavior of your code. While this may be acceptable for smaller projects, it can lead to unexpected bugs and difficulties as your codebase grows and becomes more complex.

Here are some other refactorings I've learned that make me feel like I'm in charge of the code, and not the way around.

Using strict comparison to check for null or empty strings:

// Before
if ($username == null) {}
if (!$username) {}

// After
if ($username === null) {}

The first two conditions check if $user is not truthy, which includes checking if it's null, false, 0, or an empty string. With the after example, we can use the strict comparison operator === to specifically check if $username is null.

Type hints in function parameters:

function calculate(int $x, int $y) {
    // Do something
}

In this example, the int type hint ensures that $x and $y are integers. If a non-integer value is passed to the function, PHP will throw a TypeError.

Using `array_key_exists()` to check for array keys:

// Before
if (isset($data['username'])) {
    // Do something
}

// After
if (array_key_exists('username', $data)) {
    // Do something
}

In the before example, we're using the isset() function to check if $userData['username'] exists. With the after example, we can use the array_key_exists() function to specifically check if the 'username' key exists in $userData.

Null coalescing operator and null coalescing assignment operator:

// Before
if (isset($userData['username'])) {
    $username = $userData['username'];
} else {
    $username = 'Guest';
}

// After
$username = $userData['username'] ?? 'Guest';

In the before example, we're using an if statement to check if $userData['username'] exists and setting $username accordingly. With the after example, we can use the null coalescing operator ?? to set $username to $userData['username'] if it exists, and 'Guest' if it doesn't. Additionally, we can use the null coalescing assignment operator ??= to assign the default value to $username only if it's not already set.

These stricter checks help us write more reliable and predictable code, catch errors early, and save ourselves from potential headaches in the future. While some of these refactorings may take some getting used to, they are worth the effort to improve the quality of our code. Or, just install Rector and let it handle them for you. Happy coding!

Upgrading to Eloquent accessors & mutators from Laravel 9

Geni Jaho — Sun, 26 Feb 2023 13:16:54 +0000

Laravel 10 is making the headlines these days. However, many apps are stuck in older versions, or at least still use the syntax and methods of older releases. One of the most significant changes introduced in Laravel 9 is the syntax for accessors and mutators.

The old syntax used a simple convention, just wrapping the attribute between 'get' or 'set' and the word 'Attribute', such as getFullNameAttribute and setFullNameAttribute, that did the trick. In the new syntax, you may define an accessor and mutator using a single, non-prefixed method by type-hinting a return type of Illuminate\Database\Eloquent\Casts\Attribute (docs):

use Illuminate\Database\Eloquent\Casts\Attribute;

public function name(): Attribute
{
    return new Attribute(
        get: fn ($value) => strtoupper($value),
        set: fn ($value) => $value,
    );
}

While the old syntax is still usable, it might get removed in the future, or might confuse Laravel newcomers, so it's best to update it sooner rather than later. You can modify those methods by hand, or you can use an automated tool, like Rector. It's an open-source tool to upgrade PHP projects and automate the boring stuff for you.

You can install Rector with composer require rector/rector --dev. Apart from the core package, we'll require another package that is specifically tailored to Laravel apps. You can install it with composer require driftingly/rector-laravel:dev-main --dev, and initiate a config file with vendor/bin/rector init.

You only need to apply one Rector rule to migrate to the new syntax automatically. Just write this in your rector.php file:

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use RectorLaravel\Rector\ClassMethod\MigrateToSimplifiedAttributeRector;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/app',
    ]);

    $rectorConfig->rule(MigrateToSimplifiedAttributeRector::class);
};

It will take care of migrating all your Eloquent models to use the new syntax. If you found a bug or something went wrong, let me know. This Rector rule was contributed to the library by yours truly 😊.

There is one gotcha

The old syntax allowed you to use the accessors and mutators however you wanted. So, if you had a getFullNameAttribute(), you could use it either like $user->full_name or $user->fullName. Both would work. The new attributes in Laravel 9 still allow you to use both cases, however, if you append the attributes to your models using camel case, you're a bit out of luck. Suppose you have protected $appends = ['firstName'];, you will see this error: Call to undefined method App\Models\User::getFirstNameAttribute().

The problem is that Laravel is trying to determine your attribute using the snake case name, but it can't find it (we're doing protected function firstName(): Attribute), so it defaults to searching for attributes in the old syntax and it fails.

To overcome that, you need to double-check your Eloquent $appends property or any other manual appends that you apply to your models that use camelCase names for your accessors or mutators. Change them to snake case. Also, if you're using your models in the front end, check to see if the front-end logic is still working. Better yet, make these changes before you migrate to the new syntax and check them beforehand. I know, it does not look that fun now, but what were you going to do on a weekend anyway?

The other hacky solution I found was to disable attribute snake casing by using this in your models: public static $snakeAttributes = false;. This will make all your errors go away and will properly find the attributes regardless of their casing. However, I think this is also used to determine the names of model relationships, and it might have implications for them as well. I think you shouldn't take this approach, and your safest bet is to just not upgrade right away the mutators/accessors that cause this issue.

Overall, the new syntax for accessors and mutators in Laravel 9 provides a more intuitive and readable way of working with Eloquent models. By upgrading your existing code to the new syntax, you can take advantage of the latest features and enhancements, and ensure that your code is more maintainable and easy to read.

Development Driven Testing

Geni Jaho — Wed, 01 Feb 2023 15:18:56 +0000

One of the first roles that I've been working on since I went full-time remote was that of the unit tester. I wasn't used to being the QA guy before and although this was new to me, I've gotten the hang of it. However, as part of my role, I had to write the tests as well (PHPUnit). The other devs in my teams were not initially comfortable writing tests, or they were just more focused on releasing stuff.

Testing after the fact is pretty common

I am sure this doesn't happen only to me. I'm sure there are countless other projects out there that follow the same process. Devs do the feature, someone does some QA, and then the task card is moved to the Unit Testing column. For anyone appreciating a TDD workflow, that's just straight-out weird.

What is this Development Driven Testing thing weird? It's weird because you lose so many of the benefits of writing tests alongside the features.

Testing after the fact is often unproductive

For starters, let's say you found the feature to test to be very badly architected because of... deadlines. So bad that writing tests for it is either too difficult and non-productive, or the only way to do it is to refactor the whole thing. But the other dev has already delivered a refactored code, should you do it again? Or just skip the whole testing thing and release it, because, of deadlines?

Let's say the code to be tested is well-written and can be worked with. By what metric? Most of the untested code that I've seen is controllers, services, and methods with hundreds of lines of code and very high complexity. Sure, it may look simple and well written for a programmer's eye, but what does Phpmetrics have to say? Even if I, the tester, wrote a large feature without tests, I'd still produce the same suboptimal code that another programmer would call mehh 😂.

Not testing at all is the path to the dark side

The other way around with untested code, over-engineering, is also a problem. It's easy to get distracted from a feature you're building and start accounting for details and sub-features that weren't requested and will probably never be used. It's hard sometimes to just stay focused and build only what you need to build. It's hard to know when to stop refactoring, but then again, it happens.

Ever worked on a legacy project? Why do all legacy projects have the same problems? How did they come to be like that? My biggest bet is that they grew with time, started making real money, and everyone was too afraid to mess around and "do things properly". Why upgrade and groom a project if it's working? If only there was a way to improve the project safely...

Hey, but doesn't TDD take up a lot of time?

That's another big misconception when it comes to writing tests alongside features. I've written tested code and I've written untested code and I can say with full confidence that tests haven't cost me as much time as I anticipated they would. There are many cases when a testing environment helps me to write a feature faster. For example, when implementing a form with various inputs. I'm writing the inputs one by one and without tests, I have to check constantly with the browser to make sure that everything works. Otherwise, I don't even have to leave the editor.

Oh, and it's this other critical win when using tests. They change your way of thinking about problems, or rather, they help you uncover a sane path to dealing with them. The reason for this is that you are forced to think about use cases and implement them in sequential steps, which is very similar to the way machines process instructions. Eventually, you write code that follows this sequential thought process, steadily built with pieces that form a whole feature, and guess what, it will be very readable and easy to grasp by an outside observer, or future you.

TDD is your decision to make

I still think writing tests after the fact is here to stay. People who make decisions are not easily convinced by some software "theories", right? They want hard facts and results. However, the decision on this is in your hands, fellow developer. You're not going to change anything by asking for permission.

Funny enough, to prove this point even to myself, I got introduced to a modern Laravel project that had no tests, and I insisted that I would only accept the work if I was allowed to write tests. A few months in, we needed to do a major refactoring and upgrade to PHP 8.2. We did that, the tests were all green, and we were good to go. We all felt safe and protected and decided that every developer write their own tests, the benefits were obvious.

So give it a try at your projects. YOLO, don't tell anybody. Just write some tests for your own tasks, let them hang in there, and grow them in size for some months, you'll see the benefit in time. Your whole team will see.

TDD in the era of Copilot and ChatGPT

With the recent rise of ChatGPT and GitHub Copilot, the experience of writing tests has gone to another level. Once you get a bit comfortable with writing stuff by hand, an AI assistant will just blow your mind. Copilot is already generating so many of my tests these days, it barely takes minutes to write complex logic and assertions. I feel like these tools were made for TDD.

I thank you for reading this far and I hope you got some value for your time. I write about refactoring and testing from time to time. See you in the next post.

Allowing users to send emails with their own SMTP settings in Laravel 9

Geni Jaho — Sun, 22 Jan 2023 22:09:57 +0000

Various guides exist on how to do this in Laravel, but all the ones I found (this and this) worked only up to Laravel 8. The reason is that in v9 the Swift Mailer was no longer supported in favor of Symfony Mailer. The Laravel docs show how to write your own custom transports, but that's not what we need here. There might be a package that sends emails with custom SMTP params when reading this post, so you might want to take a look first.

What Laravel does behind the scenes

The first thing we want to handle is related to a class called MailManager. It is responsible for configuring and resolving the various transport drivers. We already know that we want to use the SMTP transport, we just need to know how to override the default configuration coming from the .env file. This MailManager has a method for that:

protected function getConfig(string $name)
{
    return $this->app['config']['mail.driver']
        ? $this->app['config']['mail']
        : $this->app['config']["mail.mailers.{$name}"];
}

This is the method that we want to override. Before we do that, we need to know how the MailManager is resolved and used by the framework. In the framework's MailServiceProvider we find this piece of code:

protected function registerIlluminateMailer()
{
    $this->app->singleton('mail.manager', function ($app) {
        return new MailManager($app);
    });
    $this->app->bind('mailer', function ($app) {
        return $app->make('mail.manager')->mailer();
    });
}

This tells us that to work with another mailer instead of the default one, we have to use another instance of a MailManager and get the mailer from it.

Implementing the custom Mailer

So we make this new class called App\Extensions\UserMailManager, place it or call it anything you want, that accepts a configuration when created and overrides the getConfig() method we saw earlier to use that configuration.

namespace App\Extensions;

use Illuminate\Mail\MailManager;

class UserMailManager extends MailManager
{
    public function __construct($app, private readonly array $customConfig)
    {
        parent::__construct($app);
    }

    protected function getConfig(string $name)
    {
        return $this->customConfig;
    }
}

In your AppServiceProvider, or any other provider, we bind an instance of this new MailManager to the container, which will allow us to pass custom SMTP parameters when needed. It could've been a singleton, not sure.

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind('user.mailer', function ($app, $parameters) {
            return (new UserMailManager($app, $parameters))->mailer();
        });
    }
    ...
}

You would utilize our setup so far like this:

/** @var Mailer $mailer */
$mailer = app('user.mailer', $smtpParams);
$mailer->send($mailable);

This does not look all that handy though. Usually, you have your SMTP params in a column in your users table (or another table, doesn't matter). We're going to use that to our advantage, by creating a helper method in the User model.

public function sendMail(Mailable $mailable)
{
    if ($this->smtp_enabled) {
        $smtpParams = [
            'transport' => 'smtp',
            'host' => $this->smtp_params['smtp_host'] ?? null,
            'port' => $this->smtp_params['smtp_port'] ?? null,
            'username' => $this->smtp_params['smtp_user'] ?? null,
            'password' => $this->smtp_params['smtp_password'] ?? null,
            'timeout' => null,
            'verify_peer' => false,
        ];

        /** @var Mailer $mailer */
        $mailer = app('creator.mailer', $smtpParams);
        $mailer->send($mailable);
    } else {
        Mail::send($mailable);
    }
}

Using the mailer with custom SMTP params

Now, in the other parts of the code where you want to use the custom params, you can swap Mail::send(new TestMail($testVariable)) with $user->sendMail(new TestMail($testVariable)). Handy, right?

If you want to queue the mail instead, I'd suggest you add a new method called queueMail($mailable, ...), and tailor it to your needs. The only difference would probably be using $mailer->queue($mailable); inside the method.

That's it. Leave a thumbs up if this helped you, and thank you for making it this far.

Safely upgrade from PHP 7.4 to 8.1 using Rector

Geni Jaho — Sun, 25 Sep 2022 20:53:17 +0000

I have to say it from the start, the only thing that comes close to safely upgrading a codebase is having a solid set of automated tests. Nothing gives you more comfort than a bunch of green checkmarks dancing on the screen.

With that said, we're going to upgrade a Laravel project running on the soon-to-be-dead PHP 7.4 (Nov 28). Currently, the last stable PHP version is 8.1 and we're going to upgrade to it using a tool called Rector. Rector will help us move on to the new syntax in a very comfortable way.

Without further ado, here are the steps I followed.

Change `composer.json` to the new PHP 8.1

"require": {
    "php": "^8.1",
    ...
}

Alongside manually changing the version in composer.json, I also changed my environment to use PHP 8.1. In Homestead, that's done simply by running php81. In Valet that command is valet use php@8.1. If you're on Windows and using Wamp or Xampp, well, good luck 😁.

Do a `composer update`

After changing the environment, I ran a nice and risky composer update. Not entirely sure about this, as there might be a cleaner way, but I guess composer needs to check and update all packages to the specified PHP version.

This is the point where you'll probably get stuck and face composer errors because not all packages you use support the new PHP.

Check for packages that might break

In this particular project, the only package that did not have support was fzaninotto/faker, and that's because that project has said goodnight since 2020. Good news though, there's an alternative to it called fakerphp/faker, which you can just use directly in composer.json ("fzaninotto/faker" => "fakerphp/faker"). And you don't need to change a thing in your factories, it just works.

Run the tests

At this point, I run the tests, and I notice nothing breaks, they're all passing. Phew.
However, if it doesn't go as smoothly for you, or you don't have tests, check out the deprecations here. Just make sure that you've handled those and ignore the new syntax, because we're not going to upgrade to it the old fashion way. Just commit your changes so you have a clean slate for the syntax changes.

Install, configure, and run Rector

composer require rector/rector --dev
vendor/bin/rector init

This command will install Rector for you and create a rector.php file at the root of your project. You can modify it to tell Rector to upgrade all the codebase up to PHP 8.1, with this configuration:

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/app',
    ]);

    $rectorConfig->importNames();

    $rectorConfig->sets([
        LevelSetList::UP_TO_PHP_81,
    ]);

    $rectorConfig->skip([
        SpatieEnumClassToEnumRector::class,
    ]);
};

We'll discuss that last rule shortly, but now you should be able to run vendor/bin/rector --dry-run. If your codebase is huge, you'll have to wait a minute or two. When it's done you'll see all the changes that are to be applied, like a git diff. If you omit the --dry-run it will instead go ahead and do all those changes to your code, so you can pick what you want to keep in your diff browser of choice.

That last rule SpatieEnumClassToEnumRector is skipped because I'm using the spatie/enum package, and I don't want it to be converted to PHP native enums automatically. The reason for that is that the Spatie package has some nice little helpers, and it's safer in my opinion to migrate some of the enums manually.

Another little gotcha I want to point out is with the match expression. It does strict comparisons, unlike switch, and that might do some damage if left unchecked. As a remedy, you can use the match (true) {...} version, which is not as beautiful but will do a loose comparison like the switch.

I'm not going to go over what's new in 8.1 and what Rector will do for you, but damn it feels good to see all the code clean itself. PHPStorm supports it out of the box. You just have to try it, heck, let the tests break, just run it.

Originally published at https://blog.genijaho.dev.

Refactoring #8: What is dead may never run

Geni Jaho — Sun, 04 Sep 2022 20:08:10 +0000

It's important to take a good look at your code and clean up when you're done with it. Once in a while, we tend to forget this little detail and just move on, leaving behind trails of unreachable statements.

Here's a very blatant example of a dead piece of code.

{
    $user = auth()->user();

    return $user->posts;

    // This line will never run
    $user->posts->each->publish();
}

The last line above will never execute, and while this type of code looks like a very rare occurrence, it still shows up a lot. There is this automated tool called Rector that is fantastic at finding dead code like this and removing it, or letting you know of its existence.

Rector also unearths other dead code that is not completely obvious at first sight. This one below is very common, actually.

    /**
     * @param GeocoderInterface $geocoder
     */
    public function __construct(GeocoderInterface $geocoder)
    {...}

The PHPDoc is expressing the same information that is clearly stated in the method declaration. A dev can easily see that the method needs a GeocoderInterface object, the extra comment does not tell more than that. Same for an IDE, you will get the autocomplete you need without the comment.

PHPDocs can be liars in disguise

One more thing I don't like about these redundant docs is that they often 'lie'. Take this for example:

    /**
     * @return User
     */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }

This keeps me up at night. This Eloquent relation has a return type of BelongsTo, but if you use it as a method $post->user() somewhere in code, the IDE will wrongly suggest you autocomplete options that belong to an Eloquent Model. It will be fun trying to find these bugs when they happen in runtime, so just remove the comment entirely.

If you find yourself doing this often because you want some more autocomplete options when accessing the actual model $post->user, consider annotating it, like this:

/**
 * @property User $user
 */
class Post extends Model

Laravel's default stubs

Another piece of dead code is the Laravel framework's default stubs. They're there so we can easily input our dependencies. What do we do if we don't have any? Nothing, we just leave it there, because we're lazy.

    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
    }

    /**
     * Create a new command instance.
     *
     * @return void
     */
    public function __construct()
    {
        parent::__construct();
    }

No harm in keeping them, but if you're not injecting anything, frankly, wipe these suckers from the face of the earth, they're just taking valuable space and pushing the real code down below. You can also change the default stubs by running php artisan stub:publish.

Conditions that are always true

Dead code candidate #4 is tricky. Usually, it's safe to remove the redundant check like in this simple case:

     if (! auth()->check()) {
         return 'not logged in';
     }

    // This second condition is always true
-    if (auth()->check()) {
-        return 'logged in';
-    }

    // You can just execute the code without the condition
+    return 'logged in';

However, there may be cases where a check like that is needed if there's stuff happening behind the scenes, like in this uninspired example:

    if (! $user->canPost()) {
        ...
        return false;
    }

    ...
    $this->updateUserPermissions();

    // You might want to keep this check
    // even if you've checked at the top
    if ($user->canPost()) {
        return true;
    }

A tool like Rector won't magically understand the underlying sorcery that is happening and will simply suggest removing the last condition. To silence it, simply add this comment:

/** @noRector \Rector\DeadCode\Rector\If_\RemoveAlwaysTrueIfConditionRector */
if ($user->canPost()) {
    return true;
}

That's it for the dead code. You killed it. I've also posted about other spells Rector can cast for you, like using updated syntax from PHP 8.1 and above, auto-importing class names in the whole codebase, etc. Check out their site, they add refactorings weekly 🏠🔥.

Refactoring #7: Upping the coding style game in PHP using Rector

Geni Jaho — Wed, 31 Aug 2022 14:06:41 +0000

Continuing from the last post, we're now exploring other Rector configurations that help us improve our code.

It's funny actually, Rector is a refactoring tool, but I'd be lying if I didn't use it to learn a good practice or two. Really, they have a catalog of refactorings ready for us to consume and expand upon.

Anyway, proceeding with the SetList::CODING_STYLE configuration sets.

    $rectorConfig->sets([
        LevelSetList::UP_TO_PHP_74,
        SetList::CODE_QUALITY,
        SetList::CODING_STYLE,
    ]);

Upgrades I absolutely love

We'll start with some top-notch improvements that I think we should apply to every PHP project.

New line after statement

 class Invoice extends Model
 {
-    protected $appends = ['order_subtotal', 'total'];
-    protected $guarded = [];

+    protected $appends = ['order_subtotal', 'total'];
+
+    protected $guarded = [];

This might seem a bit intrusive, in the sense that there might be cases where you want to pack lines together, but I don't think you'll have problems with that. This refactoring only touches the code that you really want to have some breathing room for, like class methods and properties, conditionals, loops, etc. Actually here's the full list as of Aug 2022.

Separate multiple `use` statements

 class Delivered
 {
-    use Dispatchable, InteractsWithSockets, SerializesModels;

+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;

I love this one. Putting the use statements one under the other lets me find them more easily. Also, hidden gems, if you add/remove one of them they'll appear as additions/deletions when viewing the git diff, instead of a one-line change that will take you a second to figure out.

Notice that the rule with the new lines above does not affect the use statements, they're still packed together nicely.

Simplify quote escaping

-    return ['message' => 'You\'re already verified.'];

+    return ['message' => "You're already verified."];

Oh, I am guilty of this. It's pretty common actually to start a string with single quotes when it fits in pleasantly with neighboring strings, only to find out you need to use 'you\'re' with an awkward backslash. Same with using double quotes. What a lovely refactor.

Wrap variables in curly braces

-    return "Service $service does not exist!";

+    return "Service {$service} does not exist!";

Do I really need this refactoring? Quite some time ago PHPStorm suggested that you use the curly braces on all occasions. Lately, I'm seeing that it advocates removing unnecessary braces. My mind is split right now, but I guess I liked having them in my strings in the first place. So I'm keeping the braces, and telling PHPStorm to stop complaining for now.

Convert `switch` to `if-else`

-    switch ($event->type) {
-        case 'payment_intent.succeeded':
-            $this->handlePaymentIntentSucceeded($event);
-            break;
-        default:
-            abort(404);
-    }

+    if ($event->type == 'payment_intent.succeeded') {
+        $this->handlePaymentIntentSucceeded($event);
+    } else {
+        abort(404);
+    }

This is a perfect example of a developer thinking of far-future use cases when writing code, making things harder to read. If your switch only contains one case, you're better off with the good old if. I'd never think of doing this refactoring manually, by the way, this tool rocks.

Match `catch` exceptions with their types

-    } catch (Card $e) {
-        $body = $e->getJsonBody();

+    } catch (Card $card) {
+        $body = $card->getJsonBody();

At first, I had some doubts about this rule. I liked the short $e version, it was nice and clean, but I guess a proper exception name provides more context after all. Alright, alright, I'm keeping this one.

Inherited method same visibility as parent

     use RefreshDatabase;

-    public function setUp():void

+    protected function setUp():void
     {
         parent::setUp();

I didn't notice this before but I had a lot of test classes where I'd set the setUp function as public. I remember doing it once in one test, and then I've copied that method ever since 😂.

Don't do that mistake, generate your tests with php artisan make:test ExampleTest, and modify the stubs however you like with php artisan stub:publish.

Upgrades I have mixed feelings for

Static arrow functions and closures

    $schedule->command('some:dummy-command')
-        ->when(fn() => Carbon::now()->endOfWeek()->isToday());

+        ->when(static fn() => Carbon::now()->endOfWeek()->isToday());

There are these two rules, which actually occurred quite frequently, that prefix the arrow functions and closures with static whenever possible. That is, if a closure does not need the $this reference, it can be made static. I'm dropping these rules, however, since the RFC notes that I probably don't need them.

Static closures are rarely used: They're mainly used to prevent $this cycles, which make GC behavior less predictable. Most code need not concern itself with this.

You can skip rules by simply adding them to your rector configuration, like this:

    $rectorConfig->skip([
        // ...
        StaticArrowFunctionRector::class,
        StaticClosureRector::class,
    ]);

Convert post increments to pre increments

-    $count++;

+    ++$count;

This one really made me hmmm big time. Why do I need this? I check in with the issue and PR that added the rule and I find out that this is a mirror rule from PHPStan. I know there are some edge cases when developers will ++ everywhere they can, in if statements and array keys, but damn this rule made a lot of code a bit suspicious. Or I'm just not used to this and it's actually pretty common. I'm skipping it right now, maybe we cross paths again in the future (PostIncDecToPreIncDecRector).

Convert inline variables to `sprintf`s

-    "Order canceled with reason {$reason}."

+    sprintf('Order canceled with reason %s', $reason)

I'm not sure I understand how the sprintf version is more readable than the encapsed one. Maybe if I wanted to do some formatting, but in an existing project, the formatting has already been done in some other way. This feels a lot like C, ignoring this one as well (EncapsedStringsToSprintfRector).

We're pausing here for now. This list is of course, incomplete, it's impossible to cover all the Code Style refactorings it can do. We'll continue exploring other refactorings like dead code and early returns in another post. See ya 🏠.

Refactoring #6: Improve Code Quality in Laravel using Rector

Geni Jaho — Thu, 11 Aug 2022 13:41:00 +0000

I recently discovered Rector and was completely blown away by its power and effectiveness. The promise is simple: you install and run the package, you get instant automated upgrades and refactorings.

Damn, that's bold, I thought as I dry ran it into one of my projects. While still reading their first page instructions at getrector.org, I decided to dive in and refactor a whole project overnight, to whatever extent possible.

I'm running a Laravel 8 project in a PHP 7.4 environment, and I started out with this simple configuration that handles simple code quality improvements:

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/app'
    ]);

    $rectorConfig->importNames();

    $rectorConfig->sets([
        LevelSetList::UP_TO_PHP_74,
        SetList::CODE_QUALITY,
    ]);
};

Don't worry if you don't understand the code above, I didn't either half an hour ago 😂.

After running vendor/bin/rector --dry-run, I immediately saw these little upgrades that I was never going to do myself anyway.

Auto import class names

     /**
-     *
-     * @return \Illuminate\Broadcasting\Channel|array
-     */

+     *
+     * @return Channel|array
+     */
     public function broadcastOn()

This change is coming from the $rectorConfig->importNames(); configuration, and it's a lifesaver. Most coding standards prefer short class names, so auto-importing the classes in the whole project is a big big win.

Changing the string class name to a class constant

    public function user() {
-      return $this->belongsTo('App\User');

+      return $this->belongsTo(User::class);
     }

This is fantastic for old Laravel projects since most of them still use the string version to this day. It's a great upgrade because IDEs have much better support for the User::class version.

Arrow functions from PHP 7.4

       $schedule->command('dummy-command')
         ->daily()

-        ->when(function () {
-          return \Carbon\Carbon::now()->endOfWeek()->isToday();
-        });

+        ->when(fn() => Carbon::now()->endOfWeek()->isToday());

I didn't even know that arrow functions were introduced in PHP 7.4, and I could have used them without any language upgrade. Now I get to utilize their power with a single rector command.

Inline useless variables

-        $phone = str_replace(' ', '', $phone);
-        return $phone;

+        return str_replace(' ', '', $phone);

This is another low-hanging fruit. The $phone variable here adds nothing to the quality of the code, so it can be safely removed.

Combine the assignment operator

-        $this->order_count = $this->order_count + 1;

+        $this->order_count += 1;

This is an easy one as well. The short version is always better in my opinion.

Simplify the `if` return statements

-        if ($user->company_id == $this->id) {
-            return true;
-        }
-
-        return false;


+        return $user->company_id == $this->id;

I think you almost always want to do this, it's a beautiful one-liner that's easy to the eye and helps you grasp the logic quicker.
If, however, it ruins your formatting in one of your files, where the existing way makes more sense, you can ignore this rule by adding a comment like this:

/** @noRector \Rector\CodeQuality\Rector\If_\SimplifyIfReturnBoolRector */.

Throw error on JSON operations

     public function setImageUrlsAttribute($value)
     {
-        $this->attributes['image_urls'] = json_encode($value);

+        $this->attributes['image_urls'] = json_encode($value, JSON_THROW_ON_ERROR);
     }

This extra parameter makes it so that when encoding or decoding JSON goes wrong, it won't return null but it will throw an exception instead. I like this one, but I'm not entirely sure I'm ready to have this optimization in my code yet. Since this throws an exception, I'm a bit weary and will store this for later.

We can ignore certain rules by using this configuration.

Convert `compact` usages into arrays

         $user= auth()->user();
         $credits= $user->credits()->latest()->get();

-        return view('user.credits', compact('user', 'credits'));


+       return view('user.credits', ['user' => $user, 'credits' => $credits]);

Today I learned that there's an opinion about using the compact() function that states it's not ideal, and maybe an antipattern. Not sure how I feel about this, but I'm keeping this refactoring and going with the flow. Nothing wrong with plain old arrays, right?

And many other small upgrades actually. Not to forget that this is coming from just the CODE_QUALITY rules that I imported in a single line above. There are 30+ other categories that I can't wait to use and see what they offer.

At this point I just run vendor/bin/rector, all tests are still passing, commit, push, and deploy. All is well in production now 😁.

Adding user-specific settings in Laravel

Geni Jaho — Thu, 28 Apr 2022 19:58:39 +0000

The latest feature we added to OLM is the ability to make yourself known to the world using your social media accounts. The links to your accounts appear on the photos you upload, in the Global Map. See the end result in this photo on the map. This is the approach we're following in our back-end.

There are many ways to handle this, but after some googling, we came to the conclusion that the best solution in our case was to use a settings column in our User model. Database JSON columns come to the rescue. We copied a good chunk of code from this awesome post 🤣.

Storing the settings in the database

Starting off with adding the new column to the users table, this simple migration does the trick:

We want it to be nullable since existing users of the platform won't have any settings whatsoever, and it's easier than updating everyone with a default value. We could also provide a default value to this JSON column, like {}, but it's only supported from MySQL version 8.0.13 onwards.

To save the user's settings, we have a SettingsController and a method we called update():

Notice that we're using the $request->validated() method instead of $request->all(). That's because we don't want any setting that we don't have validation for to be stored in our database. The settings() method on the User model is a nice helper that does the actual heavy lifting.

It simply merges the new settings we add with the existing ones, overriding the old values where the keys match. Again, inspired by this awesome post.

Data validation is handled in a FormRequest:

The UpdateSettingsRequest does just some simple validation, it requires that the links provided be valid URLs. Through the messages() method we can override the default error messages to be more user-friendly.

Sprinkle some getters on the User

Now that we have a simple way to set a user's settings, we need a simple way to get them as well.

From top to bottom:

It feels very comfortable when using the @property doc blocks. Through them, we notify our IDE that, on every $user instance, we can access properties like $user->settings and $user->social_links, and they will return an array. The more you have of these doc blocks, the merrier.
We add the 'settings' => 'array' pair to the $casts array so that we don't have to json_encode() and json_decode() all the time to access the settings. You can also use 'json' instead of 'array'.
The setting() method is straightforward, it simply checks if we have a setting with a given name and returns it, otherwise, it returns the default value provided. One gotcha here is that if the setting exists, but has a null-ish value, this method will return that instead of the default fallback. We want that by the way, at least for now. Also, notice $this->settings ?? [], we need this check since the column could be null.
The getSocialLinksAttribute() method will allow us to access it like $user->social_links, and it will return only the settings that are not null-ish. This is for easier access in the front-end or other places in code. From Laravel 9 and above, there's a better way to define Accessors and Mutators on your models, you should check it out, it's the new kid in the block.

Does this work with nested settings?

In closing, we didn't go with a nested settings approach, something like this:

The reason is the complexity of dealing with it in the front end. Saving and updating nested settings would require some deep watching of properties and suspicious object merging operations. This solution does allow us to do that as it is implemented here, but we're keeping it simple for now.

See you in the next post, and thank you for making it here.

The code used for illustration is taken from the OpenLitterMap project. They're doing a great job at creating the world's most advanced open database on litter, brands & plastic pollution. The project is open-sourced and would love your contributions, both as users and developers.

Originally published at https://genijaho.dev.