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

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

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:

• https://getrector.com/documentation/cache-in-ci
• https://getrector.com/blog/new-setup-ci-command-to-let-rector-work-for-you
  https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows

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:

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:

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:

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:

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!

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.

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.

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.

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

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

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:

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.

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

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.

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:

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:

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.

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:

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:

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:

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

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.

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

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

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

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

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

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

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

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

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:

Convert post increments to pre increments

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 sprintfs

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