DEV Community: Yannick Chenot

Upgrade your project to PHP 8.2 with Rector

Yannick Chenot — Sat, 18 Mar 2023 15:07:23 +0000

I wanted to upgrade a project to PHP 8.2 and figured I could use Rector for this.

Not only was that the case, but I also completely underestimated how easy it was going to be.

What is Rector?

Rector is a free and open-source tool written in PHP allowing you to automate various refactoring tasks. It analyses your code and applies whatever rules you've specified in its configuration. It is also possible to create your own rules.

How to upgrade your project to PHP 8.2

First, install Rector as a development dependency:

$ composer require --dev rector/rector

Then, generate the rector.php configuration file at the root of your project:

$ ./vendor/bin/rector init

Open that file and replace its content with the following:

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->sets([LevelSetList::UP_TO_PHP_82]);
};

Perform a dry run to check what changes Rector is about to make (the below analyses the app folder as an example):

$ ./vendor/bin/rector process app --dry-run

Apply the changes if you're happy with them:

$ ./vendor/bin/rector process app

You can also specify the paths to analyse in the configuration file directly:

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;

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

    $rectorConfig->sets([LevelSetList::UP_TO_PHP_82]);
};

And then simply run:

$ ./vendor/bin/rector process

What's happening under the hood?

In the above, the UP_TO_PHP_82 constant means that not only the rules to upgrade from PHP 8.1 to PHP 8.2 were applied, but so did those from PHP 8.0 to PHP 8.1, as well as all the other versions' down to PHP 5.2.

In other words, you can bring an entire code base from PHP 5.2 to the latest version with a single command, using predefined rulesets provided by Rector.

But there's more – you can check the available rules and their description here, which go way beyond version-related changes. And, as mentioned earlier, you can also create your own rules if need be.

Closing thoughts

Rector has been on my radar for a while and I even used it a few times before, yet I'm still surprised by how powerful it is.

While it seems to be getting a little more traction recently, along with other static analysis tools like PHPStan, it is still very much underused. One of the reasons is probably that developers are unaware of its potential, of which the above is just a taste.

There is a book covering Rector in depth, which I'm planning on reading soon.

A GitHub Workflow to Check the Compatibility of Your PHP Package with a Range of Dependency Versions

Yannick Chenot — Tue, 05 Jul 2022 08:05:28 +0000

A common aspect of a PHP developer's job is to deal with Composer dependencies. We use the work of others as Lego bricks to build our own projects, making the most of the beautiful thing that is the open-source movement.

As typical end-users of these community efforts, we maintain a list of dependencies whose versions are pinned through the composer.lock file. We don't need to think about supporting other versions of these dependencies, just as we don't need to think about accommodating a range of PHP versions – we work within the constraints of our application's target environments, which are known and expected to be stable over time.

Things are different for open-source software maintainers. They are largely agnostic to the constraints of their users' environments, so the best they can do is make sure their libraries are compatible with as many PHP and dependency versions as possible.

This is where compatibility testing is crucial. Open-source maintainers need to ensure that any change made to the code will work with all the versions listed in composer.json. Doing so manually is unpractical, so they resort to test coverage and automated scripts.

This post explores one such way of automating compatibility testing, using a combination of test coverage and a GitHub Actions workflow.

In this post

Complete workflow
Breakdown
Closing thoughts
Resources

Complete workflow

Here is the final version of the workflow. If you're just here for the code, feel free to copy and reuse the below as much as you please. Otherwise keep reading for a progressive breakdown of the file, supported by an example project.

You can also check out this article's repository for reference.

Breakdown

The following is a full breakdown of the workflow. We will build it up incrementally, using an example project that we will update as we expand the range of supported dependency versions.

Initial setup

This step is optional, but if you're a "learn through practice" kind of person, you may want to build this example project on your machine and update it as we go. If you don't, you may want to read this section anyway, as it contains some relevant information.

If you do, go ahead and create a new empty GitHub repository now. Call it php-compatibility-demo (or anything else if you feel inspired) and make sure it's public so you can enjoy the free GitHub Actions allowance (unless you've got a paid account, in which case feel free to keep the repository private).

The below assumes that your development setup supports PHP 8.0+ and that you've got access to a terminal with Composer and Git.

Clone the repository on your development machine and initialise a new Composer project:

$ git clone php-compatibility-demo
$ cd php-compatibility-demo
$ composer init

The last command will ask you a series of questions and generate a composer.json file at the end. Most questions don't matter in the context of this article, but make sure to select library for the type of project, stable for the minimum stability, and to leave the default values for the PSR-4 autoload bit.

Once that's done, add /vendor/ and composer.lock to the .gitignore file:

/vendor/
composer.lock

This is the first major difference from regular company projects, where developers will usually commit the composer.lock file so the application is consistent across environments. Here we embrace inconsistency instead, and let Composer figure out what dependency versions to use based on the constraints of client environments.

In this context, the GitHub workflow is yet another client environment, and we don't want it to pick up a composer.lock file that will force the installation of specific versions while our goal is to test a whole range of them.

Library and test coverage

With that in place, let's talk about our test project for a minute. We are going to build a small library on top of Money, a popular PHP package facilitating the manipulation of monetary values and currencies.

Our library will consist of a single helper class – CurrencyHelper.php – that will simplify working with currencies. It will expose two methods – one to make sure that a bunch of Money objects have the same currency, and another one returning the numeric ISO 4217 code of a Money object.

You will soon realise that this library is pretty pointless, but it makes up a good example to support this article, so I trust you will turn a blind eye.

Here's the file structure you should get at the end of this section (remember that you can also refer to this article's repository at any time for comparison):

php-compatibility-demo/
├── src/
│   └── CurrencyHelper.php
├── tests/
│   └── CurrencyHelperTest.php
├── vendor/
├── .gitignore
├── composer.json
└── composer.lock

Let's instal the Money library:

$ composer require moneyphp/money:^4.0

Note that we intentionally import v4 here, even though it may not be the latest version when you're reading this.

Let's also instal PHPUnit as a development dependency:

$ composer require --dev phpunit/phpunit

If you're also building this example library on your machine, don't forget to update the vendor name in the namespace at the top.

The isSame method takes any number of Money objects and returns a boolean indicating whether they share the same currency. The way it works is that it removes the first element from the array (using array_shift) and then compares this element's currency with that of the other ones, using the isSameCurrency method from the Money class.

The second method – numericCode – takes a Money object as its only parameter and returns its currency's numeric ISO code, using the numericCodeFor method from the ISOCurrencies helper class (which is part of the Money library).

And here is the content for tests/CurrencyHelperTest.php, the class testing the behaviour of our "library":

These tests will allow us to confirm whether our library works with various PHP and dependency versions later on. Again, don't forget to update the vendor's name at the top.

Let's check that the tests are passing:

$ ./vendor/bin/phpunit tests

If they do, we can move on to the workflow.

Basic workflow

Let's start with a simple GitHub Actions workflow whose only job will be to run the test suite. Basically what we just did, but in an automated way.

We need to create a new .github folder at the root of the project, itself containing a workflows folder in which we add a file named ci.yml. These directories are GitHub conventions – that's where the platform expects to find our workflows, ci.yml being one of them.

This is the updated file structure:

php-compatibility-demo/
├── .github/
│   └── workflows/
│       └── ci.yml
├── src/
│   └── CurrencyHelper.php
├── tests/
│   └── CurrencyHelperTest.php
├── vendor/
├── .gitignore
├── composer.json
└── composer.lock

And here's the content of ci.yml:

Let's break it down quickly – we first give the workflow a name ("CI" stands for "Continuous Integration"), and then define the conditions on which it should trigger (here, any changes pushed to the main branch, or any pull request opened towards it).

We then list the jobs to be executed. There's only one in our case – running the test suite. We call this job "PHPUnit" and specify that it will run on the latest Ubuntu version.

Then we define the steps making up the job – checking out the code, setting up PHP, installing the Composer dependencies and, finally, running the test suite. The first three steps are using popular GitHub Actions (see the uses keys):

We don't need a GitHub Action for the last step as it is a simple command.

Save the file, commit and push. After a few seconds, you should see a screen similar to this under the Actions tab of your GitHub repository:

You can click on the workflow run to see the logs.

And that's it for the first version of our workflow. It's a decent first step already, as the workflow will trigger any time some new code is pushed to/a pull request is opened towards main, automatically reporting any breaking changes.

But so far we're only testing a single set of dependency versions – whatever Composer decides is best when the workflow reaches the Install composer dependencies step.

Let's go one step further.

Dependency ranges

Say we want to support both PHP 7.4+ and PHP 8.0+. Instead of letting Composer do its best based on what software version is available on the client environment, we are going to tip it off by explicitly listing the PHP versions our library is compatible with.

Open composer.json and update the require section as follows:

"require": {
    "php": "^7.4|^8.0",
    "moneyphp/money": "^4.0"
},

We're now supporting both PHP 7.4+ and PHP 8.0+. But wait, that's not going to work – the Money library requires PHP 8.0+ for its v4, so if we want to add support for PHP 7.4+, we also need to include an older version of Money.

Let's update composer.json again:

"require": {
    "php": "^7.4|^8.0",
    "moneyphp/money": "^3.0|^4.0"
},

We're now also supporting both Money v3 and v4. As Money v3 needs PHP 5.6+, we should be compatible with PHP 7.4 as well.

As we've updated composer.json, let's make sure our local composer.lock is up to date with the following command:

$ composer update --lock

We now need to update our workflow to ensure the test suite will run for both versions of PHP:

The main change here is the addition of the strategy section. A strategy allows us to define a matrix for our jobs – a way to run the steps using different configurations.

But let's have a quick look at fail-fast first – by setting this property to false, we make sure the steps will run for all configurations and won't be interrupted even if one of them fails. We want comprehensive feedback for all PHP versions here, so we can fix any issue that comes up.

Then comes the matrix section, composed of a single php-version key, which is an array of values. What that does is that for each successive run of the steps, the php-version key will be assigned a new value from the array, until we reach the end of the array.

Note that we've also listed PHP 8.1 in there, as there are some notable differences with PHP 8.0.

We can see the php-version key being referenced further down, in the Setup PHP step. We added a new php-version key under the with section – that's where we assign the value of the current run (${{ matrix.php-version }}), using a configuration option from the Setup PHP GitHub Action.

Let's try this out – commit and push the changes and head over to the repository's Actions tab again. Give it a few seconds – you should see that this time, the run has failed:

Click on the workflow run – there was an issue with the PHP 7.4 job:

Click on it and expand the Run PHPUnit logs:

Interesting. One of our test assertions is failing on line 23:

$this->assertFalse($checker->isSame($amount1, $amount2, $amount4));

Looking at the Money library's changelog, the reason appears to be because the Money@isSameCurrency method only added support for multiple arguments from v4. We know that this version can only be used with PHP 8.0+, which explains why Composer instals Money v3 when it detects PHP 7.4.

To fix the issue, we need to change the way the isSame method works in CurrencyHelper.php:

public function isSame(Money ...$amounts): bool
{
    if (count($amounts) === 1) {
        return true;
    }

    $first = array_shift($amounts);

    foreach ($amounts as $amount) {
        if (! $first->isSameCurrency($amount)) {
            return false;
        }
    }

    return true;
}

Instead of passing all the remaining elements of the $amounts array to isSameCurrency at once, we now loop through them and compare their currency to that of the first element, one by one.

Let's make sure we haven't broken our library before pushing our changes:

$ ./vendor/bin/phpunit tests

Commit and push and check the Actions tab again:

The error is gone!

So it appears our library is now compatible with both PHP 7.4+ and PHP 8.0+.

Or is it?

Testing lower dependency versions

Let's take a look at the logs again. Click on the latest successful workflow run and enter the PHPUnit (7.4) job from the left-hand side. Expand the Install composer dependencies logs and look for the line referencing the Money library.

It looks like Composer is picking the latest minor version by default (v3.3.1 at the time of writing):

The issue is we want our library to be compatible with previous versions as well – how can we force Composer to instal the lowest version – v3.0.0?

We need to update ci.yml again:

Note that we've added a new key to our matrix – dependency-versions. It is also an array, with two values – lowest and highest.

This time we're taking advantage of a configuration option from the Composer Install GitHub Action, allowing us to force Composer to either use the lowest or highest versions of the dependencies.

We can see the dependency-versions key being used further down, in the Install composer dependencies step. We added a new with section to it, with a single dependency-versions key to which we assign the current value from the matrix (${{ matrix.dependency-versions }}).

When that value is lowest, the Composer Install GitHub Action will run this command behind the scenes:

$ composer update --prefer-lowest --prefer-stable

What's the consequence of adding a new array of values to our matrix? The answer is that it will trigger as many step runs as there are combinations from both arrays.

Let's see it in action – commit and push the new workflow, and check the Actions tab again:

Looks like there was an issue with the new run. If we click on it, we'll see that the test suite was run for each PHP and dependency version, as well as for each value from the dependency-versions array.

But all the runs using the lowest value have failed:

Let's find out why. Click on the PHPUnit (7.4, lowest) job and expand the Run PHPUnit logs:

The error is the following:

Call to undefined method Money\Currencies\ISOCurrencies::numericCodeFor()

If we take a look at the Money library's changelog again, we can see that this method was added with v3.0.5.

We now have two ways to fix this – either we update the CurrencyHelper@numericCode method and manually implement the change, or we bump the minimum supported version to 3.0.5.

Since this version is a small patch, it feels reasonable to do the latter.

Let's update composer.json one last time:

"require": {
    "php": "^7.4|^8.0",
    "moneyphp/money": "^3.0.5|^4.0"
},

Commit and push, and wait for the workflow run to finish:

No more errors!

For good measure, let's make sure our local composer.lock is in sync with composer.json again:

$ composer update --lock

Closing thoughts

Compatibility testing highlights once again the importance of having good test coverage for our applications. Even if we don't need to support a range of dependency versions, whenever we find ourselves in need to update one of them, having a strong test suite gives us the confidence that it won't break some parts of our code. That also goes for upgrading to a newer PHP version.

But then again, most PHP developers don't have to think about this too much. I personally started to look into compatibility testing more seriously when I created my first open-source library and, later on, when I started exploring building for the console with PHP.

Yet you may eventually find yourself in a situation where you need to build and provide a PHP package with limited knowledge of target environments. Be it in the context of a private company or as a way to contribute back to the community, when that day comes it may be useful to have this kind of guide handy.

Resources

Validate Your PHP API Tests Against OpenAPI Definitions – a Laravel Example [2023 update]

Yannick Chenot — Tue, 22 Mar 2022 12:03:37 +0000

OpenAPI is a specification for describing RESTful APIs in JSON and YAML format, aiming at being understandable by both humans and machines.

OpenAPI definitions are language-agnostic and can be used in several ways:

An OpenAPI definition can be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

– The OpenAPI Specification

This article demonstrates how to write integration tests that compare API responses to OpenAPI 3+ definitions to validate that the former conform to the latter.

We will use the OpenAPI HttpFoundation Testing package in a fresh Laravel installation for which we'll also generate a Swagger UI documentation using the L5 Swagger package.

The first part of the post will describe the issue and provide further context – if you're just here for the code, you're welcome to skip ahead and go to the Laravel example section straight away.

The issue

APIs are commonplace nowadays and the decent ones come with documentation describing the endpoints and how to use them. These documents come in various shapes and forms, but a fact they can't escape is that they need to be updated every time the API changes.

To many developers, API documentation is an afterthought – it's boring, tedious, and often unrewarding. Using annotations to keep the code and the documentation in one place helps to some extent, but these are often painful to write and even the most willing developer is likely to introduce errors that won't necessarily be caught by reviewers.

The result is documentation and API getting out of sync, leading to frustrated consumers.

Another goal of API maintenance is to ensure that existing endpoints keep functioning properly – regressions can and will appear over time, and may go unnoticed if there isn't a proper testing strategy in place.

One approach is to write integration tests controlling the API's behaviour and automatically detecting breaking changes as soon as they are introduced. While this is a good strategy, it isn't foolproof – there's no guarantee that the expectations set in the tests will always 100% match the documentation.

How can we make sure they remain in sync?

A solution

Let's assume that we have an API documented with OpenAPI, some integration tests, and that we want to align the expectations of the latter with the operations described in the former.

OpenAPI comes with a growing number of tools built on top of it, pushing its utility far beyond the documenting aspect.

One tool destined for the PHP community and maintained by The PHP League is OpenAPI PSR-7 Message Validator, a package validating PSR-7 HTTP messages against OpenAPI definitions.

The idea is to compare HTTP requests and responses with OpenAPI definitions and return errors when they don't match.

In other words, we can use this package to add an extra layer on top of our integration tests that will compare API requests and responses with the OpenAPI definitions describing our API and fail the test if they don't match.

Here is a fancy diagram to illustrate the relationship between the API, the integration tests and the OpenAPI definition:

The definition describes the API, and the tests use the definition to make sure the API behaves the way the definition says it does.

All of a sudden, our OpenAPI definition becomes a reference for both our code and our tests – it acts as the API's single source of truth.

PSR-7

One caveat of the OpenAPI PSR-7 Message Validator package is that, as its name indicates, it only works with PSR-7 messages.

The issue is that not all frameworks support this standard by default – in fact, a lot of them use Symfony's HttpFoundation component under the hood, whose requests and responses do not implement that standard out of the box.

The Symfony folks thought of this, however, and provided a bridge that converts HttpFoundation objects to PSR-7 ones. The bridge simply needs a PSR-7 and PSR-17 factory, for which they suggest using Tobias Nyholm's PSR-7 implementation.

All these pieces are brought together by OpenAPI HttpFoundation Testing, a package allowing developers to back their integration tests with OpenAPI definitions in applications relying on the HttpFoundation component.

Let's see how to use it in a Laravel project, which falls into this category.

A Laravel example

The code featured in this section is also available as a GitHub repository for reference.

First, let's create a new Laravel 10 project, using Composer:

$ composer create-project --prefer-dist laravel/laravel openapi-example "10.*"

Enter the project's root folder and instal a couple of dependencies:

$ cd openapi-example
$ composer require --dev osteel/openapi-httpfoundation-testing
$ composer require darkaonline/l5-swagger -W

The first one is the OpenAPI HttpFoundation Testing package mentioned earlier, which we instal as a development dependency as it's intended to be used as part of our test suite.

The second one is L5 Swagger, a popular package bringing Swagger PHP and Swagger UI to Laravel. We actually don't need Swagger PHP here, as it uses Doctrine annotations to generate OpenAPI definitions and we're going to manually write our own instead. We do need Swagger UI, however, and L5 Swagger conveniently adapts it to work with Laravel.

If you're wondering, the -W option is simply here to also update related dependencies and thus avoid conflicts.

To make sure Swagger PHP doesn't overwrite the OpenAPI definition, let's set the following environment variable in the .env file, at the root of the project:

L5_SWAGGER_GENERATE_ALWAYS=false

Let's also make YAML the default format:

L5_FORMAT_TO_USE_FOR_DOCS=yaml

Create a file named api-docs.yaml in the storage/api-docs folder (which you need to create), and add the following content to it:

openapi: 3.1.0

info:
    title: OpenAPI HttpFoundation Testing Laravel Example
    version: 1.0.0

servers:
    - url: http://localhost:8000/api

paths:
    '/test':
    get:
        responses:
        '200':
            description: Ok
            content:
            application/json:
                schema:
                type: object
                required:
                    - foo
                properties:
                    foo:
                    type: string
                    example: bar

This is a simple OpenAPI definition describing a single operation – a GET request to the /api/test endpoint, that should return a JSON object containing a required foo key.

Let's check whether Swagger UI displays our OpenAPI definition correctly. Start the PHP development server (from the project's root):

$ php artisan serve

Open localhost:8000/api/documentation – you should see the OpenAPI definition rendered as a Swagger UI documentation:

Expand the /test endpoint and try it out – it should fail with a 404 Not Found error because we haven't implemented it yet.

Let's fix that now. Open the routes/api.php file and replace the example route with this one:

Route::get('/test', function (Request $request) {
    return response()->json(['foo' => 'bar']);
});

Go back to the Swagger UI tab and try the endpoint again – it should now return a successful response.

Time to write a test! Open tests/Feature/ExampleTest.php and replace its content with the following:

<?php

namespace Tests\Feature;

use Osteel\OpenApi\Testing\ValidatorBuilder;
use Tests\TestCase;

class ExampleTest extends TestCase
{
    /**
     * A basic test example.
     *
     * @return void
     */
    public function testBasicTest()
    {
        $response = $this->get('/api/test');

        $validator = ValidatorBuilder::fromYamlFile(storage_path('api-docs/api-docs.yaml'))->getValidator();

        $result = $validator->validate($response->baseResponse, '/test', 'get');

        $this->assertTrue($result);
    }
}

Let's unpack the above. If you're unfamiliar with Laravel, $this->get() is a test method provided by the MakesHttpRequests trait to perform a GET request to the provided endpoint, executing the request's lifecycle without leaving the application. It returns a response that is identical to one you would obtain if you'd perform the same request from the outside.

We then create a validator using the Osteel\OpenApi\Testing\ValidatorBuilder class, to which we feed the YAML definition we wrote earlier via the fromYamlFile static method (the storage_path function is a helper returning the path to the storage folder, where we placed the definition).

Had we had a JSON definition instead, we could have used the fromJsonFile method (note that other methods are available and listed in the documentation).

The builder returns an instance of Osteel\OpenApi\Testing\Validator, on which we call the get method, passing the path and the response as parameters ($response is an instance of Illuminate\Testing\TestResponse here – a wrapper for the underlying HttpFoundation object, which can be retrieved through the baseResponse public property).

The above is basically the equivalent of saying:

I want to validate that this response conforms to the OpenAPI definition of a GET request to the /test path.

It could also be written this way:

$result = $validator->get($response->baseResponse, '/test');

That's because the validator exposes a shortcut method for each of the HTTP methods supported by OpenAPI (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS and TRACE), to make it simpler to test responses for the corresponding operations.

Note that the specified path must exactly match one of the OpenAPI definition's paths.

You can now run the test, which should be successful:

$ php artisan test tests/Feature

Open routes/api.php again, and change the route for this one:

Route::get('/test', function (Request $request) {
    return response()->json(['baz' => 'bar']);
});

Run the test again – it should now fail because the response contains baz instead of foo, and the OpenAPI definition says the latter is expected.

Our test is officially backed by our OpenAPI definition!

The above is an oversimplified example for demonstration purposes, but in real-life situations, a good practice would be to overwrite the MakesHttpRequests trait's call method, so it performs both the request and the OpenAPI check.

This way, our test would boil down to this line:

$this->get('/api/test');

This could be implemented as a new MakesOpenApiRequests trait that would "extend" the MakesHttpRequests one, and that would first call the parent call method to get the response. It would then work out the path from the URI, and validate the response against the OpenAPI definition before returning it, for the calling test to perform any further assertions, as needed.

The OpenAPI HttpFoundation Testing package has more to offer, like extension points and caching to speed up the execution of your tests (Laravel's caching API is supported out of the box) – please refer to the documentation for details.

Conclusion

While this setup is a great step towards improving an API's robustness, it is no silver bullet – it requires that every single endpoint is covered with integration tests, which is not easily enforceable in an automated way and ultimately still requires some discipline and vigilance on the part of developers.

It may even feel a bit coercive at first since, as a result, maintainers are basically forced to keep the documentation up to date to write successful tests.

The added value, however, is that said documentation is now guaranteed to be much more accurate, leading to happy consumers which, in turn, should lead to less frustrated developers, who will spend less time hunting down pesky discrepancies.

All in all, making OpenAPI definitions the single source of truth for both the API documentation and integration tests is in itself a strong incentive to keep them up to date. They naturally become a priority, where they used to be an afterthought.

As for maintaining the OpenAPI definition itself, doing so manually can feel a bit daunting. Annotations are a solution, but I personally don't like them and prefer to maintain a YAML file directly. IDE extensions like this one for VSCode make it much easier, but if you can't bear the sight of a YAML or JSON file, you can also use tools like Stoplight Studio to do it through a more user-friendly interface.

And since we're talking about Stoplight, this article about API Design-First vs Code First by Phil Sturgeon is a good starting point for API documentation in general and might help you choose an approach to documenting that works for you.

Resources

A Complete Guide to Laravel Sail

Yannick Chenot — Wed, 09 Mar 2022 09:43:02 +0000

Truman continues to steer his wrecked sailboat towards the infinitely receding horizon. All is calm until we see the bow of the boat suddenly strike a huge, blue wall, knocking Truman off his feet. Truman recovers and clambers across the deck to the bow of the boat. Looming above him out of the sea is a cyclorama of colossal dimensions. The sky he has been sailing towards is nothing but a painted backdrop.

– Andrew M. Niccol, The Truman Show

On December 8 2020, Taylor Otwell announced the launch of Laravel Sail, a development environment based on Docker, along with a large overhaul of Laravel's documentation:

// Detect dark theme var iframe = document.getElementById('tweet-1336357588791947264-751'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1336357588791947264&theme=dark" }

The announcement caused a wave of excitement across the community, as a lot of people identified the new environment as an opportunity to finally get into Docker. But it also left some confusion in its wake, as Sail isn't exactly a guide to becoming a Docker expert, and it introduces an approach to development that is quite different from its predecessors.

This post is about what to expect from Laravel Sail, how it works and how to make the most of it. It is also a plea to developers to break away from it, in favour of their own, tailored solution.

But before we get there, we need to take a look under the deck, starting with a high-level explanation of what Sail is.

In this post

What is Laravel Sail?
How does it compare to its predecessors?
How does it work?
Extending Laravel Sail
What's wrong with Laravel Sail anyway?
The whale in the cabin
You don't need Laravel Sail
Conclusion
Resources

What is Laravel Sail?

Sail is Laravel's latest development environment. It is the most recent addition to an already long list featuring official solutions like Homestead and Valet on the one hand, and community efforts like Laragon, Laradock, Takeout and Vessel on the other (according to the GitHub repository, Sail is largely inspired by the latter).

Laravel Sail is based on Docker, a technology leveraging containers to essentially package up applications so they can run quickly and easily on any operating system.

The future of Sail appears to be bright, as the Laravel documentation immediately featured it as the preferred way to instal and run Laravel projects locally, a spot that Homestead and Valet had occupied for a long time.

How does it compare to its predecessors?

As a refresher, Homestead is a Vagrant box (a virtual machine) featuring everything most Laravel applications need. That includes essential components like PHP, MySQL and a web server (Nginx), but also other technologies like PostgreSQL, Redis or Memcached.

Valet, on the other hand, is a lightweight environment for macOS focussed on performance. It relies on a local installation of PHP instead of a virtual machine, and is intended to be used alongside other services like DBngin or Takeout to manage other dependencies like databases.

While Homestead and Valet look quite different on paper, they promote the same general approach to local development, which is also shared by most of the aforementioned solutions: they try to be one-size-fits-all environments for Laravel projects and aim at managing them all under one roof.

Sail's approach is different, in that the instructions to build the development environment come with the project's source code. Instead of relying on the presence of a third-party solution like Homestead on the developer's machine, Docker will read the set of instructions and build the corresponding environment from scratch.

In other words, the application comes with batteries included and a single command will spin up and configure its dependencies. It will work regardless of the developer's operating system, so long as Docker is installed on it.

Laravel Sail introduces the notion of a bespoke development environment for the application, which, in my opinion, is the technology's real kicker.

While this approach is a major departure from traditional solutions, Sail still bears some resemblance to them around the tools it comes with, some of which are essential, others not.

Let's review the most important ones and how they are implemented.

How does it work?

From here on, it will be easier to follow along with a fresh installation of Laravel, although the files I refer to always point to the official GitHub repository. If you've got a little bit of time, go follow the instructions for your operating system now and come back once you've successfully run ./vendor/bin/sail up – I'll take it from there.

While Sail allows us to pick the services we're interested in when creating a new Laravel application, by default it is composed of three main components – PHP, MySQL and Redis. As per the documentation, the whole setup gravitates around two files – docker-compose.yml (located at the root of the project after a fresh installation) and the sail script (under vendor/bin).

The `docker-compose.yml` file

As mentioned already, Laravel Sail is based on Docker, which is a technology leveraging containers. The rule of thumb is that each container should only run one process, which roughly translates to each container running a single piece of software. Applying this rule to the above setup means we'll need a container for PHP, one for MySQL, and a third one for Redis.

These containers make up your application, and for it to function properly, they need to be orchestrated. There are several ways to do this, but Laravel Sail relies on Docker Compose for the job, which is the preferred solution for local setups.

Docker Compose expects us to describe the various components of our application in a docker-compose.yml file, in YAML format. If you open the one at the root of the project, you will see a version parameter at the top, followed by a services section containing a list of components comprising the ones I've just mentioned – laravel.test, mysql and redis (and some other ones I'll briefly cover later).

I'll describe the mysql, redis and laravel.test services in that order, as the two first ones are simpler than the last.

The `mysql` service

As the name suggests, the mysql service handles the MySQL database:

mysql:
    image: 'mysql/mysql-server:8.0'
    ports:
        - '${FORWARD_DB_PORT:-3306}:3306'
    environment:
        MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}'
        MYSQL_ROOT_HOST: "%"
        MYSQL_DATABASE: '${DB_DATABASE}'
        MYSQL_USER: '${DB_USERNAME}'
        MYSQL_PASSWORD: '${DB_PASSWORD}'
        MYSQL_ALLOW_EMPTY_PASSWORD: 1
    volumes:
        - 'sailmysql:/var/lib/mysql'
    networks:
        - sail
    healthcheck:
        test: ["CMD", "mysqladmin", "ping", "-p${DB_PASSWORD}"]
        retries: 3
        timeout: 5s

The image parameter indicates which image should be used for this container. An easy way to understand the difference between images and containers is to borrow from Object-Oriented Programming concepts – an image is akin to a class and a container to an instance of that class.

Here, we specify that we want to use the tag 8.0 of the mysql/mysql-server image, corresponding to MySQL Server version 8.0. By default, images are downloaded from Docker Hub, which is the largest Docker image registry. Have a look at the page for MySQL Server – most images come with simple documentation explaining how to use them.

The ports section allows us to map local ports to container ports, following the local:container notation. In the code snippet above, the value of the FORWARD_DB_PORT environment variable (or 3306 if that value is empty) is mapped to the container's 3306 port. This is mostly useful to connect third-party software to the database, like MySQL Workbench or Sequel Ace (the setup would also work without it).

environments is where we define environment variables for the container. Here, most of them receive the value of existing environment variables, which are loaded from the .env file at the root of the project – docker-compose.yml automatically detects and imports the content of this file. For instance, in the MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}' line, the container's MYSQL_ROOT_PASSWORD environment variable will receive the value of DB_PASSWORD from the .env file.

volumes is to declare some of the container's files or folders as volumes, either by mapping specific local files or folders to them or by letting Docker deal with it.

Here, a single Docker-managed volume is defined: sailmysql. This type of volume must be declared in a separate volumes section, at the same level as services. We can find it at the bottom of the docker-compose.yml file:

volumes:
    sailmysql:
        driver: local
    sailredis:
        driver: local
    sailmeilisearch:
        driver: local

The sailmysql volume is mapped to the container's /var/lib/mysql folder, which is where the MySQL data is stored. This volume ensures that the data is persisted even when the container is destroyed, which is the case when we run the ./vendor/bin/sail down command.

The networks section allows us to specify which internal networks the container should be available on. Here, all services are connected to the same sail network, which is also defined at the bottom of docker-compose.yml, in the networks section above the volumes one:

networks:
    sail:
        driver: bridge

Finally, healthcheck is a way to indicate which conditions need to be true for the service to be ready, as opposed to just be started. I'll get back to this soon.

The `redis` service

The redis service is very similar to the mysql one:

redis:
    image: 'redis:alpine'
    ports:
        - '${FORWARD_REDIS_PORT:-6379}:6379'
    volumes:
        - 'sailredis:/data'
    networks:
        - sail
    healthcheck:
        test: ["CMD", "redis-cli", "ping"]
        retries: 3
        timeout: 5s

We pull the alpine tag of the official image for Redis (Alpine is a lightweight Linux distribution) and we define which port to forward. We then declare a volume to persist the data, connect the container to the sail network, and define the health check to perform to ensure the service is ready.

The `laravel.test` service

The laravel.test service is slightly more complex:

laravel.test:
    build:
        context: ./vendor/laravel/sail/runtimes/8.0
        dockerfile: Dockerfile
        args:
            WWWGROUP: '${WWWGROUP}'
    image: sail-8.0/app
    extra_hosts:
        - 'host.docker.internal:host-gateway'
    ports:
        - '${APP_PORT:-80}:80'
    environment:
        WWWUSER: '${WWWUSER}'
        LARAVEL_SAIL: 1
        XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
        XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
    volumes:
        - '.:/var/www/html'
    networks:
        - sail
    depends_on:
        - mysql
        - redis
        - meilisearch
        - selenium

For starters, the name is a bit confusing, but this service is the one handling PHP (i.e. the one serving the Laravel application).

Next, it has a build section that we haven't seen before, which points to the Dockerfile that is present under the vendor/laravel/sail/runtimes/8.0 folder.

Dockerfiles are text documents containing instructions to build images. Instead of using an existing image as-is from Docker Hub, the Laravel team described their own in a Dockerfile. The first time we run the ./vendor/bin/sail up command, we build that image and create a container based on it.

Open the Dockerfile and take a look at the first line:

FROM ubuntu:21.04

This means that the tag 21.04 of Ubuntu's image is used as a starting point for the custom image; the rest of the file is essentially a list of instructions to build upon it, installing everything a standard Laravel application needs. That includes PHP, various extensions, and other packages like Git or Supervisor, as well as Composer.

The end of the file also deserves a quick explanation:

COPY start-container /usr/local/bin/start-container
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
COPY php.ini /etc/php/8.0/cli/conf.d/99-sail.ini
RUN chmod +x /usr/local/bin/start-container

EXPOSE 8000

ENTRYPOINT ["start-container"]

We can see that a bunch of local files are copied over to the container:

the php.ini file is some custom configuration for PHP;
the supervisord.conf file is a configuration file for Supervisor, a process manager here responsible for starting the PHP process;
the start-container file is a Bash script that will do a few things every time the container starts, because it is defined as the container's ENTRYPOINT. We can see that it's made executable by the RUN chmod +x instruction;
finally, EXPOSE 8000 doesn't do anything, apart from informing the reader that this container listens on the specified port at runtime (which actually seems wrong here, since the application is served on port 80, not 8000).

Other things are happening in this Dockerfile, but the above is the gist of it. Note that this one pertains to PHP 8.0, but Laravel Sail also supports other versions whose Dockerfiles you can point to from the laravel.test service in docker-compose.yml, instead of that of PHP 8.0.

Bringing our attention back to docker-compose.yml, we can see that there is an extra_hosts section we haven't encountered before. I won't get into too much detail, but it's here to ensure Xdebug runs smoothly across operating systems.

The service also has a depends_on section containing the list of services that should be available before the Laravel application starts. Here, we need MySQL, Redis, Meilisearch and Selenium to be up and running first to avoid connection errors.

This is where the health checks described earlier are useful. By default, depends_on will wait for the specified services to be started, which doesn't necessarily mean they are ready. By specifying on which conditions these services are deemed ready, we ensure they are in the required state prior to starting the Laravel application.

The rest of the settings should be familiar by now, so I'll skip them.

The `meilisearch`, `mailhog` and `selenium` services

These are the smaller services I referred to earlier; they are already documented here, here and here. The point is they work the same way as the other ones: they pull existing images from Docker Hub and use them as-is, with minimal configuration.

The `sail` script

If you followed Laravel's installation instructions earlier, you must have run the following command at some point:

$ ./vendor/bin/sail up

The sail file that we call here is a Bash script whose function is to present a user-friendly interface to interact with Sail, saving us the pain to run and remember sometimes long-winded Docker commands.

Let's open it now for closer inspection (don't worry if you're not familiar with Bash – it's pretty straightforward).

We can ignore the whole first part of the file and focus on the big if statement which starts like this:

if [ $# -gt 0 ]; then
    # Proxy PHP commands to the "php" binary on the application container...
    if [ "$1" == "php" ]; then
        # ...

In plain English, the $# -gt 0 bit translates to "if the number of arguments is greater than 0", meaning whenever we call the sail script with arguments, the execution will enter that if statement.

In other words, when we run the ./vendor/bin/sail up command, we call the sail script with the up argument, and the execution gets inside the big if statement where it looks for a condition matching the up argument. Since there is none, the script goes all the way down to the end of the big if, in the sort of catch-all else we can find there:

# Pass unknown commands to the "docker-compose" binary...
else
    docker compose "$@"
fi

The comment already tells us what's going on – the script passes the up argument on to the docker-compose binary. In other words, when we run ./vendor/bin/sail up we actually run docker-compose up, which is the standard Docker Compose command to start the containers for the services listed in docker-compose.yml.

This command downloads the corresponding images once if necessary, and builds the Laravel image based on the Dockerfile we talked about earlier.

Give it a try! Run ./vendor/bin/sail up first, then docker compose up – they do the same thing.

Let's now look at a more complicated example, one involving Composer, which is among the packages installed by the application's Dockerfile. But before we do that, let's start Sail in detached mode to run the containers in the background:

$ ./vendor/bin/sail up -d

The sail script allows us to run Composer commands, e.g.:

$ ./vendor/bin/sail composer --version

The above calls the sail script with composer and --version as arguments, meaning the execution will enter that big if statement again.

Let's look for the condition dealing with Composer:

# ...
# Proxy Composer commands to the "composer" binary on the application container...
elif [ "$1" == "composer" ]; then
    shift 1

    if [ "$EXEC" == "yes" ]; then
        docker-compose exec \
            -u sail \
            "$APP_SERVICE" \
            composer "$@"
    else
        sail_is_not_running
    fi
    # ...

The first line of the condition starts with shift, which is a Bash built-in that skips as many arguments as the number it is followed by. In this case, shift 1 skips the composer argument, making --version the new first argument. The program then makes sure that Sail is running, before executing a weird command split over four lines, which I break down below:

docker-compose exec \
    -u sail \
    "$APP_SERVICE" \
    composer "$@"

exec is the way Docker Compose allows us to execute commands on a container which is already running. -u is an option indicating which user we want to execute the command as, and $APP_SERVICE is the container on which we want to run it all. Here, its value is laravel.test, which is the service's name in docker-compose.yml as explained in a previous section. It is followed by the command we want to run once we're in the container, namely composer followed by all the script's arguments. These now only comprise --version, since we've skipped the first argument.

In other words, when we run:

$ ./vendor/bin/sail composer --version

The command that is executed behind the scenes is the following:

$ docker compose exec -u sail "laravel.test" composer "--version"

It would be quite cumbersome to type this kind of command every single time; that's why the sail script provides shortcuts for them, making the user experience much smoother.

Have a look at the rest of the smaller if statements inside the big one to see what else is covered – you'll see that the same principle is always more or less applied.

There are a few other features available out of the box (like making local containers public), but we've now covered the substance of what Laravel Sail currently offers. While this is a pretty good start already, it is somewhat limited, even for a basic application.

The good news is that the Laravel team is aware of this, and built the environment with extension in mind:

Since Sail is just Docker, you are free to customize nearly everything about it.

– The Laravel documentation

Let's see what that means in practice.

Extending Laravel Sail

The code covered in this section is also available as a GitHub repository you can refer to at any moment.

We're going to explore three ways to extend Laravel Sail, using MongoDB as a test subject. But before we proceed, let's make sure we get our hands on as many configuration files as possible.

The only thing we've got access to initially is the docker-compose.yml file, but we can publish more assets with the following command, which will create a new docker folder at the root of the project:

$ ./vendor/bin/sail artisan sail:publish

We'll get back to those in a minute; for the time being, let's try and instal the Laravel MongoDB package, which will make it easy to use MongoDB with our favourite framework:

$ ./vendor/bin/sail composer require jenssegers/mongodb

Unfortunately, Composer is complaining about some missing extension:

...
- mongodb/mongodb[dev-master, 1.10.0, ..., v1.10.x-dev] require ext-mongodb ^1.11.0 -> it is missing from your system. Install or enable PHP's mongodb extension.
...

Let's fix this!

Installing extra extensions

Earlier in this post, we talked about the way Sail uses Dockerfiles to build images matching Laravel's requirements for various PHP versions. These files were published with the command we ran at the beginning of this section – all we need to do is edit them to add the extensions we need, and to rebuild the corresponding images.

Many extensions are available out of the box and we can list them with the following command:

$ ./vendor/bin/sail php -m

MongoDB is not part of them; to add it, open the docker/8.0/Dockerfile file and spot the RUN instruction installing the various packages:

RUN apt-get update \
    && apt-get install -y gnupg gosu curl ca-certificates zip unzip git supervisor sqlite3 libcap2-bin libpng-dev python2 \
    && mkdir -p ~/.gnupg \
    && chmod 600 ~/.gnupg \
    && echo "disable-ipv6" >> ~/.gnupg/dirmngr.conf \
    && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys E5267A6C \
    && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C300EE8C \
    && echo "deb http://ppa.launchpad.net/ondrej/php/ubuntu hirsute main" > /etc/apt/sources.list.d/ppa_ondrej_php.list \
    && apt-get update \
    && apt-get install -y php8.0-cli php8.0-dev \
        php8.0-pgsql php8.0-sqlite3 php8.0-gd \
        php8.0-curl php8.0-memcached \
        php8.0-imap php8.0-mysql php8.0-mbstring \
        php8.0-xml php8.0-zip php8.0-bcmath php8.0-soap \
        php8.0-intl php8.0-readline php8.0-pcov \
        php8.0-msgpack php8.0-igbinary php8.0-ldap \
        php8.0-redis php8.0-swoole php8.0-xdebug \
    && php -r "readfile('http://getcomposer.org/installer');" | php -- --install-dir=/usr/bin/ --filename=composer \
    && curl -sL https://deb.nodesource.com/setup_$NODE_VERSION.x | bash - \
    && apt-get install -y nodejs \
    && npm install -g npm \
    && curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - \
    && echo "deb https://dl.yarnpkg.com/debian/ stable main" > /etc/apt/sources.list.d/yarn.list \
    && apt-get update \
    && apt-get install -y yarn \
    && apt-get install -y mysql-client \
    && apt-get install -y postgresql-client \
    && apt-get -y autoremove \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

It's easy to identify the block related to PHP extensions since they all start with php8.0. Add the MongoDB extension at the end of the list:

php8.0-redis php8.0-swoole php8.0-xdebug php8.0-mongodb \

You can see the detail of available PHP extensions for Ubuntu 21.04 here.

Save the file and run the following command:

$ ./vendor/bin/sail build

This will go through all the services listed in docker-compose.yml and build the corresponding images if they have changed, including the laravel.test service's, whose Dockerfile we've just updated.

Once it's done, start the containers again:

$ ./vendor/bin/sail up -d

The command will detect that the image corresponding to the laravel.test service has changed, and recreate the container:

...
laravel-sail-extended_mailhog_1 is up-to-date
laravel-sail-extended_meilisearch_1 is up-to-date
Recreating laravel-sail-extended_laravel.test_1 ... done

That's it! The MongoDB extension for PHP is now installed and enabled. We've only done it for the PHP 8.0 image, but you can apply the same process to other PHP versions by updating their own Dockerfile, with the right extension name (e.g. php7.4-mongodb).

We can now safely import the Laravel MongoDB package:

$ ./vendor/bin/sail composer require jenssegers/mongodb

Next up: adding a Docker service for MongoDB.

Adding new services

MongoDB is essentially another database, meaning the corresponding service will be very similar to that of MySQL and Redis. A quick search on Docker Hub reveals that there is an official image for it, which we are going to use.

Its documentation contains an example configuration for Docker Compose, which we can copy and adjust to our needs. Open docker-compose.yml and add the following service at the bottom, after the other ones:

mongo:
    image: 'mongo:4.4'
    restart: always
    environment:
        MONGO_INITDB_ROOT_USERNAME: '${DB_USERNAME}'
        MONGO_INITDB_ROOT_PASSWORD: '${DB_PASSWORD}'
        MONGO_INITDB_DATABASE: '${DB_DATABASE}'
    volumes:
        - 'sailmongo:/data/db'
    networks:
        - sail

The changes I've made are the following: first, I specified the tag 4.4 of the mongo image. If you don't specify one, Docker Compose will pull the latest tag by default, which is not a good practice since it will refer to different versions of MongoDB over time, as new releases are available. The introduction of breaking changes could create instability in your Docker setup, so it's better to target a specific version, ideally matching the production one.

Then, I declared a MONGO_INITDB_DATABASE environment variable for the container to create a database with the corresponding name at start-up, and I matched the value of each environment variable to one coming from the .env file (we'll come back to those in a minute).

I also added a volumes section, mounting a Docker-managed volume in the container's /data/db folder. The same principle as MySQL and Redis here applies – if you don't persist the data on your local machine, it will be lost every time the MongoDB container is destroyed. In other words, as the MongoDB data is stored in the container's /data/db folder, we persist that folder locally using a volume.

As this volume doesn't exist yet, we need to declare it at the bottom of docker-compose.yml, after the other ones:

volumes:
    sailmysql:
        driver: local
    sailredis:
        driver: local
    sailmeilisearch:
        driver: local
    sailmongo:
        driver: local

Finally, I added the networks section to ensure the service is on the same network as the others.

We can now configure Laravel MongoDB as per the package's instructions. Open config/database.php and add the following database connection:

'mongodb' => [
    'driver' => 'mongodb',
    'host' => env('DB_HOST'),
    'port' => env('DB_PORT'),
    'database' => env('DB_DATABASE'),
    'username' => env('DB_USERNAME'),
    'password' => env('DB_PASSWORD'),
    'options' => [
        'database' => env('DB_AUTHENTICATION_DATABASE', 'admin'),
    ],
],

Open the .env file at the root of the project and change the database values as follows:

DB_CONNECTION=mongodb
DB_HOST=mongo
DB_PORT=27017
DB_DATABASE=laravel_sail
DB_USERNAME=root
DB_PASSWORD=root

The above makes MongoDB the main database connection. In a real case scenario, you might want to make it a secondary database like Redis, but for demonstration purposes, this will do.

DB_HOST is the name of the MongoDB service from docker-compose.yml. Behind the scenes, Docker Compose resolves the service's name to the container's IP on the networks it manages (in our case, that's the single sail network defined at the end of docker-compose.yml).

DB_PORT is the port MongoDB is available on, which is 27017 by default, as per the image's description.

We're ready for a test! Run the following command again:

$ ./vendor/bin/sail up -d

It will download MongoDB's image, create the new volume and start the new container, which will also create the laravel_sail database:

➜  ./vendor/bin/sail up -d
Pulling mongo (mongo:4.4)...
4.4: Pulling from library/mongo
7b1a6ab2e44d: Pull complete
90eb44ebc60b: Pull complete
...

Let's make sure of that by running Laravel's default migrations:

$ ./vendor/bin/sail artisan migrate

We can push the test further by updating the User model so it extends Laravel MongoDB's Authenticable model:

<?php

namespace App\Models;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Notifications\Notifiable;
use Jenssegers\Mongodb\Auth\User as Authenticatable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    // ...

Use Tinker to try and create a model:

$ ./vendor/bin/sail tinker

Psy Shell v0.10.5 (PHP 8.0.0 — cli) by Justin Hileman
>>> \App\Models\User::factory()->create();

Great! Our MongoDB integration is functional.

We can keep interacting with it using Tinker and Eloquent, but oftentimes it is useful to have direct access to the database, through third-party software or via a command-line interface such as the Mongo shell.

Let's add the latter to our setup.

Custom `sail` commands

The good news is the Mongo shell is already available, as long as we know the right formula to summon it. Here it is, along with some extra commands to log into the database and list the users (run the first command from the project's root):

$ docker-compose exec mongo mongo

MongoDB shell version v4.4.10
connecting to: mongodb://127.0.0.1:27017/?compressors=disabled&gssapiServiceName=mongodb
Implicit session: session { "id" : UUID("be711959-a359-4d1f-8fd4-9af7bad42c23") }
MongoDB server version: 4.4.10
Welcome to the MongoDB shell.
For interactive help, type "help".
For more comprehensive documentation, see
    https://docs.mongodb.com/
Questions? Try the MongoDB Developer Community Forums
    https://community.mongodb.com
> use admin
switched to db admin
> db.auth("root", "root")
1
> use laravel_sail
switched to db laravel_sail
> db.users.find()

The docker-compose exec mongo mongo command should look familiar – earlier in the article, we looked at what the sail script does behind the scenes, which mostly consists of translating simple sail commands into more complex docker-compose ones. Here, we're telling the docker-compose binary to execute the mongo command on the mongo container.

To be fair, this command isn't too bad and we could easily remember it; but for consistency, it would be nice to have a simpler sail equivalent, like the following:

$ ./vendor/bin/sail mongo

To achieve this we'd need to complete the sail script somehow, but as it is located inside the vendor folder – which is created by Composer – we cannot update it directly. We need a way to build upon it without modifying it, which I've summarised below:

make a copy of the sail script at the root of the project;
replace the content of its big if statement with custom conditions;
if none of the custom conditions matches the current arguments, pass them on to the original sail script.

If we take a closer look at the sail file with ls -al, we can see that it's a symbolic link to the vendor/laravel/sail/bin/sail file:

➜  ls -al vendor/bin
total 0
drwxr-xr-x   8 yannick  staff   256 26 Nov 10:37 .
drwxr-xr-x  48 yannick  staff  1536 26 Nov 12:24 ..
...
lrwxr-xr-x   1 yannick  staff    24 26 Nov 10:36 sail -> ../laravel/sail/bin/sail
...

Copy that file and paste it at the root of our project:

$ cp vendor/laravel/sail/bin/sail .

Open the new copy and replace the content of its big if with the following, leaving the rest as-is:

if [ $# -gt 0 ]; then
    # Initiate a Mongo shell terminal session within the "mongo" container...
    if [ "$1" == "mongo" ]; then

        if [ "$EXEC" == "yes" ]; then
            docker-compose exec mongo mongo
        else
            sail_is_not_running
        fi

    # Pass unknown commands to the original "sail" script...
    else
        ./vendor/bin/sail "$@"
    fi
fi

In the above code, we removed all the if...else conditions inside the big if and added one of our own, which runs the command we used earlier to access the Mongo shell if the value of the script's first argument is mongo. If it's not, the execution will hit the last else statement and call the original sail script with all the arguments.

You can try this out now – save the file and run the following command:

$ ./sail mongo

It should open a Mongo shell session in your terminal.

Try another command, to make sure the original sail script is taking over when it's supposed to:

$ ./sail artisan

The Artisan menu should display.

That's it! If you need more commands, you can add them as new if...else conditions inside the big if of the copy of the sail script at the root of the project.

It works exactly the same way, except that you now need to run ./sail instead of ./vendor/bin/sail (or update your Bash alias if you created one as suggested in the documentation).

We are now running a fully functional instance of MongoDB as part of our Docker setup, nicely integrated with Laravel Sail. But MongoDB is a mere example here – you can do the same with pretty much any technology you'd like to use.

Go take a look now! Most major actors have Docker images – official or maintained by the community – with easy-to-follow instructions. In most cases, you'll have a local instance of the software running in minutes.

There are probably many more things we could do to customise Laravel Sail, but the three methods described above should get you a long way already.

At this stage, you may be thinking that Laravel's new environment has a lot going for it, maybe even more so than you initially thought. Yet, the point of this article is to move away from it...

So where am I going with this?

What's wrong with Laravel Sail anyway?

If you made it this far, you're probably wondering what's wrong with Laravel Sail, now that it's clear how far we can push it.

As it stands, it's a pretty decent solution. In an earlier version of this article, I was pointing to a whole list of issues which have now largely been solved. So why not use it?

Let me break it to you right now: once you know and understand everything I've explained in the previous sections, you don't need Laravel Sail anymore.

That's right – you can take that knowledge and walk away.

But before I elaborate on this, let's review some remaining pain points of Sail, even though I expect the Laravel team to address most of them sooner rather than later.

The first one concerns the custom sail commands: while it's possible to extend the sail script as demonstrated above, the process is a bit ugly and somewhat hacky. Sail's maintainers could fix this with an explicit Bash extension point allowing users to add their own shortcuts, or by publishing the sail script along with the other files.

Second, the Laravel application is served by PHP's development server. I won't go into too much detail here, but as mentioned earlier, Supervisor manages the PHP process in the laravel.test container. This line is where Supervisor runs the php artisan serve command, which starts PHP's development server under the hood.

The point here is that the environment doesn't use a proper web server (e.g. Nginx), which means we can't easily have local domain names, nor bring HTTPS to the setup. This may be fine for quick prototyping, but more elaborate development will most likely need those.

The last issue belongs to a separate category, as it relates to Docker overall and not Laravel Sail specifically. It should be carefully considered before going down the Docker path and deserves a section of its own.

The whale in the cabin

The one major caveat that appears to be absent from the conversation so far relates to performance. While this shouldn't affect Linux users, if you run Docker Desktop on your system you will most likely experience long execution times, especially on macOS (it seems that using WSL 2 on Windows can mitigate the slowness).

While HTTP response times have improved a great deal, running local commands like Yarn or Composer is still very slow. You've probably experienced it yourself while going through this tutorial, when we installed the Laravel MongoDB package with Composer, for instance.

I won't go into too much detail here, but the reason essentially comes from the host's underlying filesystem, which does not perform well around mounted local directories. As we've seen, this is how Laravel Sail gets the application's source code in the Laravel application's container.

This is where an approach like Takeout's makes sense, as instead of running PHP from a Docker container, they expect developers to run it on their local machine (e.g. via Valet), all the while providing instances of services like MySQL or MongoDB, thus offering convenience without sacrificing performance. But from the moment you choose to run PHP via a Docker container (like Sail does), the added value of Takeout decreases, in my opinion.

There are strategies to mitigate these performance issues, but the Laravel documentation doesn't mention them, let alone that performance might be degraded at all, which I find surprising.

That being said, you might be comfortable enough with performance as it is; I, for one, have been OK with it for years, even though I use Docker Desktop on macOS. The bottom line is that this aspect should be carefully considered before moving your whole setup to a solution running PHP in a container, be it Laravel Sail or something else.

But once you've made that decision, and whether or not the other issues are eventually addressed, the main idea of this article remains the same.

You don't need Laravel Sail

If you're considering building anything substantial using Laravel Sail as your development environment, sooner or later you will have to extend it. You'll find yourself fumbling around the Dockerfiles and eventually writing your own; you'll have to add some services to docker-compose.yml, and maybe throw in a few custom Bash commands.

Once you get there, there's one question you should ask yourself:

What's stopping me from building my own setup?

The answer is nothing. Once you feel comfortable extending Laravel Sail, you already have the knowledge required to build your own environment.

Think about it: the docker-compose.yml file is not specific to Laravel Sail, that's just how Docker Compose works. The same goes for Dockerfiles – they are standard Docker stuff. The Bash layer? That's all there is to it – some Bash code, and as you can see, it's not that complicated.

So why artificially restrain yourself within the constraints of Sail?

And more importantly: why limit yourself to using Docker in the context of Laravel?

Your application may start as a monolith, but it might not always be. Perhaps you've got a separate frontend, and you use Laravel as the API layer. In that case, you might want your development environment to manage them both; to run them simultaneously so they interact with each other like they do on a staging environment or in production.

If your whole application is a monorepo, your Docker configuration and Bash script could be at the root of the project, and you could have your frontend and backend applications in separate subfolders, e.g. src.

The corresponding tree view would look something like this:

my-app/
├── bash-script
├── docker-compose.yml
└── src/
    ├── backend/
    │   └── Dockerfile
    └── frontend/
        └── Dockerfile

The docker-compose.yml file would declare two services – one for the backend and one for the frontend – both pointing to their respective Dockerfile.

If the backend and the frontend live in different repositories, you could create a third one, containing your Docker development environment exclusively. Just git-ignore the src folder and complete your Bash script so that it pulls both application repositories into it, using the same commands you would normally run by hand.

Even if your project is a Laravel monolith, this kind of structure is already cleaner than mixing up development-related files with the rest of the source code. Moreover, if your application grows bigger and needs other components besides Laravel, you're already in a good position to support them.

Once you've made the effort to understand Laravel Sail to extend it, nothing's stopping you from building your own development environments, whether or not Laravel is part of the equation. That's right, you can build bespoke Docker-based environments for anything.

And if Laravel is part of the stack, nothing prevents you from reusing Sail's Dockerfiles if you're not comfortable writing your own yet; after all, they are already optimised for Laravel. Likewise, you can draw inspiration from Sail's docker-compose.yml file if that helps.

Conclusion

Don't get me wrong – Sail has a lot going for it, and I am glad to see an established actor such as Laravel push forward the adoption of Docker for local development.

We love our frameworks because they offer guidelines to achieve desired results in a way we know to be efficient and battle-tested, and it's only natural that they also seek to provide the environment that will allow their users to build upon them. But one thing that Sail incidentally shows us is that this doesn't have to be part of the framework's mandate anymore.

Much like Truman's sailboat helps him overcome his fear of the sea and takes him to the edges of the artificial world he lives in, Sail reveals both the confines of Laravel and a way to escape from them.

You may feel that Sail is more than enough for your needs today, or that you're not yet ready to go on your own. That's fine. But Laravel will always be limited by its monolithic nature, and as you grow as a developer, the day will come where your Laravel application will be but a single component of a larger system, for which Sail won't be enough anymore. Eventually, your small sailboat will bump into a painted backdrop.

If you'd like to explore this further but feel like you need more guidance, I've published a series on the subject that should get you going. It requires no prior knowledge of Docker and covers web servers, HTTPS, domain names and many other things. It doesn't have all the answers but will get you to a place where you can find your own.

What you do next is entirely up to you; just know that there's a whole world out there, waiting for you.

Truman hesitates. Perhaps he cannot go through with it after all. The camera slowly zooms into Truman's face.

TRUMAN: "In case I don't see you – good afternoon, good evening and good night."

He steps through the door and is gone.

Resources

How to Build and Distribute Beautiful Command-Line Applications with PHP and Composer

Yannick Chenot — Sat, 12 Feb 2022 15:55:00 +0000

When you think of command-line applications, PHP doesn't immediately come to mind. Yet the language powers many popular tools, either as independent programs or to be used within projects.

Here are a few examples:

Be it through its vast ecosystem of libraries and frameworks, its ability to interact with the host, or the versatility of its dependency manager, PHP features everything you need to build and ship powerful CLI applications.

This tutorial will walk you through the process of creating a simple game running in the terminal, using Symfony's Console Component as a bedrock, GitHub Actions for compatibility checking, and Composer for distribution.

We won't use specialised frameworks like Minicli or Laravel Zero because the goal is not so much to focus on features but to better understand the development, testing, and distribution phases of command-line programs.

You will find that you can build a lot of things on top of such a simple foundation, but you can always check out these frameworks later on, should you need extra capabilities.

In this post

Prerequisites
Repository and core dependencies
Entry point
Command
Styling the output
Distribution test
PHP version support
Release
Cleaning up
Conclusion
Resources

Prerequisites

To complete this tutorial, you will need:

A GitHub account (a free one will do)
A local PHP instal
A local Composer instal
A terminal to interact with the above

If at any time you feel lost, you can also refer to this article's repository.

Repository and core dependencies

The first thing we need to do is create a GitHub repository named php-cli-demo (or anything you like, but the rest of this guide will refer to this name so it might be simpler to stick to it).

You can make the repository public straight away if you want, but I like to do so only when the code is pretty much ready. No matter what you choose, I will let you know when is a good time to make it public.

Next, open a terminal and clone the project locally, and enter its root directory:

$ git clone git@github.com:<YOUR GITHUB USERNAME>/php-cli-demo.git
$ cd php-cli-demo

Run the following command to create a composer.json file interactively:

$ composer init

It will ask you a series of questions – here is some guidance on how to answer them:

Package name (<vendor>/<name>): I distribute all my packages under the vendor name osteel, so in my case, it's osteel/php-cli-demo. If you're not sure, you can just pick your GitHub username
Description: shown as optional but will be required for distribution later on. You can set "PHP command-line tool demo"
Author: make sure you set values that you are comfortable sharing publicly
Minimum stability: go for stable. You may sometimes need to pick dev instead if some of your tool's dependencies aren't marked as stable (see here for details). That won't be the case in this tutorial though
Package type: choose library (see here)
License: this is up to you, but since the code will be distributed and available publicly, it has to be open source. MIT is fine in most cases, but if you need something more specific this guide will help. Make sure to set a value that is recognised by Composer, too. For this article, MIT will do

We will set our dependencies manually, so answer no when asked about defining them interactively. Keep the default value (src/) for PSR-4 autoload mapping.

The last question is about adding the vendor directory to the .gitignore file, to which you should reply yes.

That should be it for composer init – it will generate a composer.json file at the root of your project based on the values you've selected.

Before we instal any dependency, let's create a LICENSE file at the top of our project and paste the content of the chosen license in it (here's the MIT one – you will find the others here). Make sure to edit the placeholders for the name and year.

Let's now require Symfony's Console Component as a dependency:

$ composer require symfony/console

This component is used as a foundation for many frameworks' command-line features such as Laravel's Artisan. It's a robust and battle-tested set of classes for console applications and is pretty much a standard at this stage, so it makes sense to use it as a starting point instead of reinventing the wheel.

Once the script is done, you should see the dependency listed in the require section of composer.json (your version might be different based on when you're completing this tutorial):

"require": {
    "symfony/console": "^6.0"
},

Entry point

Console programs, like web applications, need an entry point through which all "requests" come through. In other words, we need an index.php for our commands.

To get started, we will reuse the example given in the Console Component's documentation. Create a new folder named bin at the root of the project and add a demo file to it, with the following content:

The demo file will be the entry point of our program, allowing us to call it from a terminal using commands like this one:

$ demo play

If you already have a local application named demo, give it a different name (if you're not sure, run which demo and see if it returns a path to an existing application).

Back to our demo file – notice the first line:

#!/usr/bin/env php

This is a way for the system to know which executable it should use to run the script, saving us from having to explicitly call it.

In other words, that's what will allow us to run this:

$ demo play

Instead of this:

$ php demo play

#!/usr/bin/env means the system will use the first php executable found in the user's PATH, regardless of its actual location (see here for details).

Speaking of execution, this will only work if demo is executable. Let's make sure that is the case:

$ chmod +x bin/demo

Now run the following commands:

$ php bin/demo
$ ./bin/demo

Both should display the default console menu:

Command

Now that the base structure of our application is in place, we can focus on the command that will contain the core of our program. What we're building is a simple game of calculation, giving the user basic sums to solve and returning whether the answer is correct or not.

Once again, the documentation provides some guidance on how to write commands, but for the sake of simplicity, I will give you the code straight away, followed by a breakdown.

Create some new folders src and src/Commands at the root of the project and add the following Play.php file to the latter:

Make sure to change the namespace at the top to reflect your vendor name.

Our class extends Symfony Console's Command class and overwrites some of its static properties. $defaultName and $defaultDescription are the command's name and description, which will both appear in the application's menu. The former will also allow us to invoke the command in the terminal later on.

Next comes the execute method, that the parent class requires us to implement. It contains the actual logic for the game and receives an instance of the console's input and output.

There are several ways to interact with those and I admittedly find the official documentation a bit confusing on the topic. My preferred approach is to rely on the SymfonyStyle class because it abstracts away most typical console interactions and I like the default style it gives them.

Let's take a closer look at the body of the execute method:

First, we randomly generate the two terms of the sum and calculate the result in advance. We instantiate SymfonyStyle, pass the console's input and output to it and use it to display the question and request an answer (with the ask method).

If you're unfamiliar with sprintf, it's a PHP function allowing developers to format strings in a way that I find easier to read than the standard concatenation operator (.). Feel free to use the latter instead, though.

We collect and save the answer in the $answer variable, cast it to an integer (inputs are strings by default), and compare it to the expected result. If the answer is correct, we display a success message; if not, we display an error.

We then ask the user if she wants to play another round, this time using the confirm method since we need a boolean answer ("yes" or "no").

If the answer is "yes", we call the execute method recursively, essentially starting the game over. If the answer is "no", we exit the command by returning Command::SUCCESS (a constant containing the integer 0, which is a code signalling a successful execution).

The returned value is a way to tell the console whether the program executed correctly or not, and has nothing to do with the answer being right or wrong. These exit codes are standardised and anything other than 0 usually means "failure". You can see here which exit codes the Command class defines by default and come up with your own if you need to.

The above breakdown is more than enough for this article, but feel free to check out the official documentation for details and advanced command usage.

We now need to register our command to make it available from the outside. Update the content of the bin/demo file to match the following:

The only thing we've changed is we now pass an instance of our command to the application before running it (again, don't forget to update the namespace of the imported class).

Go back to your terminal and run this from the project's root:

$ ./bin/demo

The help menu should display again, only this time the play command should be part of it, alongside its description:

We should now be able to play the game, so let's give it a try:

$ ./bin/demo play

Make sure it behaves as you would expect – if it doesn't, go back a few steps or take a look at the tutorial's repository to check if you missed something.

As our application will expose a single command play, we could also have made it the default one. Doing so would have allowed us to start the game by running demo instead of demo play.

Styling the output

The defaults provided by the SymfonyStyle class are quite good already, but these [OK] and [ERROR] messages are a bit dry and not very suitable for a game.

To make them a bit more user-friendly, let's create a new Services folder in src, and add the following InputOutput.php file to it:

Once again, make sure to change the vendor namespace at the top.

The purpose of this class is to extend SymfonyStyle to adapt its behaviour to our needs.

The program interacts with the player in three ways – it asks questions and indicates whether an answer is right or wrong.

I've reflected this in the InputOutput class above by creating three public methods – question, right, and wrong. question simply calls the parent class' ask method and prepends the question with the ✍️ emoji.

For right and wrong, I drew inspiration from the parent class' success and error methods and adapted their content to replace the default messages with more convivial emojis.

And that's all there is to it – the only thing left is to adapt the Play command to use our new service instead of SymfonyStyle:

As usual, pay attention to namespaces.

Let's play the game again and appreciate the new look:

$ ./bin/demo play

Now, you might be wondering why I created new methods instead of extending the ask, success and error methods. The quick answer is that doing so increases compatibility across library versions.

Extending a method means the signature of the child method must be identical to that of the parent (with some subtleties), which is fine as long as the parent class doesn't change. For the sake of portability, however, we want our application to be compatible with various PHP and dependency versions, and in the case of the Console Component, method signatures vary from one major version to another.

In short, creating new methods instead of extending existing ones allows us to avoid errors related to signature mismatch across versions.

The above is a quick example of how you can customise the style of console outputs. It also gives you an idea of how you can structure your application, with the introduction of the Services folder where you can put utility classes to decouple your code.

Concerning styling, if you need to push the appearance of your console program a bit further, you might want to take a look at Termwind, a promising new framework described as "Tailwind CSS, but for PHP command-line applications".

Distribution test

Let's now take a few steps towards the distribution of our application. First, we need to tweak our demo script:

The bit we've updated is the following:

$root = dirname(__DIR__);

if (! is_file(sprintf('%s/vendor/autoload.php', $root))) {
    $root = dirname(__DIR__, 4);
}

require sprintf('%s/vendor/autoload.php', $root);

We're now looking for the autoload.php file in two different places. Why? Because this file will be located in different folders based on whether we're in development mode or distribution mode.

So far we've used our application in the former mode only, so we knew exactly where the vendor folder was – at the project's root. But once it'll be distributed (installed globally on a user's system), that folder will be located a few levels above the current one.

Here's for instance the path to the application's bin folder on my system, once I've installed it globally:

~/.composer/vendor/osteel/php-cli-demo/bin

And here is the path to the global autoload.php file:

~/.composer/vendor/autoload.php

The path to /vendor/autoload.php is then four levels above bin, hence the use of dirname(__DIR__, 4) (this function returns the path of the given directory's parent, which here is the parent of the current directory __DIR__. The second parameter is the number of parent directories to go up).

Save the file and make sure you can still access the application by displaying the menu:

$ ./bin/demo

Since Composer 2.2, a $_composer_autoload_path global variable containing the path to the autoloader is available when running the program globally. This variable would allow us to simplify the above script, but also means we'd have to enforce the use of Composer 2.2 as a minimum requirement, potentially impacting compatibility.

Another thing we need to do is add composer.lock to the .gitignore file:

/vendor/
composer.lock

If you come from regular PHP application development, you may be used to committing this file to freeze dependency versions (also called dependency pinning), thus guaranteeing consistent behaviour across environments. When it comes to command-line tools, however, things are different.

As mentioned earlier, your CLI application should ideally work with various PHP and dependency versions to maximise compatibility. This flexibility means you can't dictate which versions your users should instal, and instead let client environments figure out the dependency tree for themselves.

Note that you can commit this file – it will be ignored when your application is installed via Composer. But in practice, explicitly ignoring composer.lock best reflects real usage conditions, and forces you (and your team) to consider version variation early on.

By the way, if you'd like to know more about when to and when not to commit composer.lock, I published a Twitter thread on the subject:

// Detect dark theme var iframe = document.getElementById('tweet-1465285217892114443-192'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1465285217892114443&theme=dark" }

Since we don't enforce specific dependency versions anymore, we need to define the range of versions our application will support. Open composer.json and update the require section as follows:

"require": {
    "php": "^8.0",
    "symfony/console": "^5.0|^6.0"
},

We need to specify the PHP version because down the line we won't know which versions our users are running. By making it explicit, Composer will then be able to check whether a compatible version of PHP is available and refuse to proceed with the installation if that's not the case.

Right now we're only interested in running a distribution test on our current machine though, so specifying your local PHP version is enough (adjust it if it's different from the above – if you're not sure, run php -v from a terminal).

You'll notice that I also added version 5.0 of the Console Component – that's because while running my own tests, I experienced some compatibility issues with my local instance of Laravel Valet, which needed Console 5.0 at the time.

Based on when you're completing this tutorial, versions may have changed and this constraint may not be true anymore, but it's a good example of the kind of compatibility issues you may have to deal with.

There's one last change we need to make to this file, and that is the addition of a bin section:

"require": {
    "php": "^8.0",
    "symfony/console": "^5.0|^6.0"
},
"bin": [
    "bin/demo"
],

This is how you specify the vendor binary, which is a way to tell Composer "this will be the application's entry point, please make it available in the user's vendor/bin directory". By doing so, our users will be able to call our application globally.

Commit and push the above changes. Then, if your repository was private so far, now is the time to make it public. Go to the Settings tab, enter the Options section, and scroll all the way down to the Danger Zone (which always reminds me of Archer).

There you can change the repository's visibility to public:

Now head over to packagist.org and create an account (or sign in if you already have one).

Once you're logged in, click the Submit button in the top right corner and submit the URL of your repository. Allow a few moments for the crawler to do its job and your repository will appear:

Don’t worry too much about publishing a dummy package – the worst that can happen is that no one but yourself will instal it (and you will be able to delete it later anyway).

Let's now try and instal it on your machine. Go to your terminal and run the following command:

$ composer global require osteel/php-cli-demo:dev-main

Then again, make sure to set the right vendor name. Notice the presence of :dev-main at the end – this is a way to target the main branch specifically, as there is no release available yet.

Once the instal is successful, make sure that the system recognises your application (you may need to open a new terminal window):

$ which demo

This command should return the path to your application's entry point (the demo file). If it doesn't, make sure the ~/.composer/vendor/bin directory is in your system's PATH.

Give the game a quick spin to ensure it behaves as expected:

$ demo play

Our distribution test is successful!

PHP version support

Before we carry on and publish a proper release, we need to tackle something we've now mentioned a few times – PHP version support.

This will be a two-step process:

Write a test that controls the correct end-to-end execution of our program
Add a GitHub workflow that will run the test using various PHP versions

Automated test

We will use PHPUnit as our testing environment – let's instal it as a development dependency:

$ composer require --dev phpunit/phpunit

Create the folders tests and tests/Commands at the root of the project and add a PlayTest.php file to the latter, with the following content:

As usual, make sure to update the vendor in the namespace and use statement.

As per the documentation, the Console Component comes with a CommandTester helper class that will simplify testing the Play command.

We instantiate the latter and pass it to the tester, which allows us to simulate a series of inputs.

The sequence is as follows:

Answer 10 to the first question
Say yes to playing another round
Answer 10 again
Say no to playing another round

We then have the tester execute the command and check if it ran successfully using the assertCommandIsSuccessful method (which controls that the command returned 0).

And that's it. We're not testing the game's outputs – we're merely making sure that the program runs successfully given a series of inputs. In other words, we're ensuring that it doesn't crash.

Feel free to add more tests to control the game's actual behaviour (e.g. whether it gives the correct answers), but for our immediate purpose, the above is all we need.

Let's make sure our test is passing:

$ ./vendor/bin/phpunit tests

If it doesn't, go back a few steps or take a look at the tutorial's repository to check if you missed anything.

GitHub workflow

Now that we have a test controlling the correct execution of our program, we can use it to ensure the latter's compatibility with a range of PHP versions. Doing so manually would be a bit of a pain, but we can automate the process using GitHub Actions.

GitHub Actions allow us to write workflows triggering on selected events, such as the push of a commit or the opening of a pull request. They're available with any GitHub account, including the free ones (they come with a monthly allowance).

Workflows are in YAML format and must be placed in a .github/workflows folder at the root.

Create this folder and add the following ci.yml file to it:

At the very top of the workflow is its name ("CI" stands for Continuous Integration), followed by the events on which it should trigger, in the on section. Ours will go off anytime some code is pushed to the main branch, or whenever a pull request is open towards it.

We then define jobs to be executed, which in our case is just one – running the test. We specify that we'll use Ubuntu as the environment, and then define the execution strategy to apply. Here, we'll be using a matrix of PHP versions, each of which will run our test in sequence (the listed versions are the supported ones at the time of writing).

Finally, we define the steps of our job, that we break down as follows:

Check out the code
Set up PHP using the current version
Instal Composer dependencies
Run the test

We now need to list the same PHP versions in our application's composer.json so Composer won't refuse to instal it for some of them. Let's update the require section again:

"require": {
    "php": "^7.4|^8.0",
    "symfony/console": "^5.0|^6.0"
},

If you're wondering why I didn't list 8.1, that's because as per the rules of Semantic Versioning (semver), ^8.0 covers all versions above or equal to 8.0 but strictly under 9.0, which includes 8.1. If you're like me and tend to forget the rules of semver when you need them, keep this cheatsheet handy and thank me later.

Save, commit and push the above – if it went well, you should see the workflow running in the Actions tab of your GitHub repository:

Then again, refer to the article's repository if something goes wrong.

This workflow gives us the confidence that our application will run successfully with any of the listed PHP versions, and will confirm whether this is still the case any time we push some changes.

The above is a simplified workflow that doesn't quite cover all dependency versions. We can push the concept of matrix even further, but to avoid making this post longer than it already is, I've published a separate blog post dedicated to the topic.

Release

We now have a tested application that is compatible with a range of PHP versions and an early version of which we managed to instal on our machine. We're ready to publish an official release.

But before we do that, we need to ensure our future users will know how to instal and use our application – that's what README.md files are for.

Let's create one at the root of the project (click "view raw" at the bottom to see the source code):

This is a basic template mixing some HTML and markdown code. I won't spend too much time explaining it, so here is a quick summary of the content:

Title and subtitle
Preview image
Some badges
Installation instructions
Usage instructions
Update instructions
Deletion instructions

You'll need to replace instances of osteel with your vendor name again (and maybe some other things like the application name or entry point if you chose something other than demo).

For the preview image I like to take a simple screenshot of the application being used:

Note that this is also the image I used to illustrate this post.

Create an art folder at the root of the project and place a preview.png image in it (update the code accordingly if you pick a different name).

You can also use this picture for social media by setting it in the Social preview section of the repository's Settings tab.

That's pretty much it – feel free to reuse and adapt this template as you please.

Save and push README.md, and head over to the repository's Releases section, available from the column on the right-hand side:

Create a tag for your release, which should follow the rules of Semantic Versioning. We'll make ours version 1:

Give your release a name and a description and publish it:

After a few moments, you should see it appear on the Packagist page of your repository:

Now go back to your terminal and run the following command (using the appropriate vendor name):

$ composer global require osteel/php-cli-demo

Now that a proper release is available, there's no need to append :dev-main anymore.

Make sure you can still play the game:

$ demo play

And that's it! Your application is now ready to be advertised and distributed.

You can instal future minor releases by running the following command:

$ composer global update osteel/php-cli-demo

And major ones with the following:

$ composer global require osteel/php-cli-demo

Cleaning up

This tutorial is drawing to an end and if after playing with your application you feel like cleaning up after yourself, you can delete your package from Packagist:

And this is how you'd remove it from your local system:

$ composer global remove osteel/php-cli-demo

Of course, you can also delete your GitHub repository at any time.

Conclusion

I hope this will inspire you to write your own command-line tools in PHP.

While the language's primary application remains for web development, the above should show that it's versatile enough to assist you in other ways.

Let's be honest – if your goal is the widespread use of a standalone CLI application, PHP is probably not the best language. Users would still need an environment that supports it, a local instal of Composer, and also to edit their local PATH to include Composer's bin directory. These are all steps that most people won't be comfortable taking.

But if you're already a PHP developer, your environment is very likely to satisfy these conditions already, and as a result, the barrier to building your own CLI tools is very low.

Think of repetitive tasks that you perform regularly, and that could be automated away without the need of a full-blown website. I, for instance, grew tired of having to manually import my Kobo annotations to Readwise, so came up with a tool to make the conversion easier.

PHP has no issue running system commands and if you need more muscle than what the Console Component alone has to offer, frameworks like Laravel Zero will greatly expand the realm of possibility.

You don't necessarily have to distribute your programs via Packagist for a strictly personal use, but it's a way to share your work with others who might have similar needs and a potential foray into open-source development.

Besides, the process of writing and distributing your own CLI tools is not so dissimilar to that of application libraries – once you're comfortable with the former, the latter becomes more accessible, and both are ways to give back to the community.

Resources

Here are some of the resources referenced in this post:

How to Build a Dynamic GitHub Profile with GitHub Actions and PHP

Yannick Chenot — Sun, 06 Feb 2022 17:59:32 +0000

In the summer of 2020, GitHub quietly released a feature that was quickly noticed by the community – profile READMEs. A profile README is a global README file for your GitHub profile, which you can set up by creating a public repository whose name is identical to your GitHub username. For instance, as my username is osteel, I created the osteel/osteel repository.

A little box like this one should appear while you add your own:

Once the repository is created, add a README file with a short description explaining how great you are, and your GitHub profile page will display its content by default:

Neat and simple.

As I was browsing examples for some inspiration, I stumbled upon Simon Willison's version, which features some dynamic content like recent work and blog publications. He explained how he used a combination of GitHub Actions and Python to achieve this in a blog post, and I decided to do something similar with PHP.

The placeholder

The first thing to do is to create a placeholder in the README file where the dynamic content will go. Since I wanted to automatically insert the latest publications of my blog, I used the following tags:

<!-- posts --><!-- /posts -->

You might recognise this format; since Markdown files also support HTML, I used some HTML comment tags to make sure they wouldn't show up on my profile page.

The PHP script

I can't remember the last time I wrote some PHP without a framework; as a result, I had to do a quick search just to get started with a basic PHP script and some Composer dependencies.

Turn out it's quite simple! The first step is to initialise the project with the following command:

$ composer init

From there, I installed a lightweight library to parse my blog's RSS feed:

$ composer require dg/rss-php

I then added a posts.php file at the root of the project, with the following content:

<?php

// Load Composer's autoload
require_once __DIR__ . '/vendor/autoload.php';

// Load the RSS feed
$feed = Feed::loadRss('https://tech.osteel.me/feeds/rss.xml')->toArray();

// Generate the list of blog posts
$posts = '';
foreach (array_slice($feed['item'], 0, 5) as $post) {
    $date   = date('d/m/Y', strtotime($post['pubDate']));
    $posts .= sprintf("\n* **[%s]** [%s](%s \"%s\")", $date, $post['title'], $post['link'], $post['title']);
}

// Generate the new content
$content = preg_replace(
    '#<!-- posts -->.*<!-- /posts -->#s',
    sprintf('<!-- posts -->%s<!-- /posts -->', $posts),
    file_get_contents('README.md')
);

// Overwrite the file
file_put_contents('README.md', $content);

Nothing too complicated here – Composer's autoload is required at the top, allowing me to load the RSS parser to generate a list of blog posts as a string, in Markdown format.

The existing content of the README file is then loaded into the $content variable, and the Markdown string is inserted between its  and  tags with preg_replace.

Finally, the file's entire content is replaced with the new one, using the file_put_contents function.

The workflow

GitHub Actions allow developers to write workflows to automate various tasks like running test suites or deploying web services.

They must be defined using YAML format in a .github/workflows folder at the root of the project, and contain a list of steps that they are to execute.

Here's mine, which I named posts.yml:

name: Update blog posts

on:
  push:
  workflow_dispatch:
  schedule:
    - cron:  '0 0 * * *'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Clone repository
      uses: actions/checkout@v2
    - name: Install PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.1'
    - name: Install Composer dependencies
      run: composer install
    - name: Insert blog posts
      run: php posts.php
    - name: Push changes
      uses: stefanzweifel/git-auto-commit-action@v4
      with:
        commit_message: Updated latest blog posts

Again, nothing too complicated. We first give the action a name, and then define a list of events that should trigger it – pushing some code to the repository, a manual trigger from the interface (workflow_dispatch), or periodically like a cron job (here, every day at midnight).

We then indicate that the action should run on an Ubuntu image, where it will:

clone the repository;
instal PHP 8.1;
instal the Composer dependencies;
run the PHP script;
commit and push the changes, if any.

That's it! My GitHub profile is now automatically updated every time I publish a new article.

Conclusion

This was a quick experiment aiming at exploring GitHub Actions, which I expect to use more and more in the future. It was also fun to use PHP as a simple scripting language again, in a procedural way.

I've voluntarily left out a few things in order to keep this article short and simple – please refer to the repository for implementation details.

DEV Community: Yannick Chenot

Upgrade your project to PHP 8.2 with Rector

What is Rector?

How to upgrade your project to PHP 8.2

What's happening under the hood?

Closing thoughts

A GitHub Workflow to Check the Compatibility of Your PHP Package with a Range of Dependency Versions

In this post

Complete workflow

Breakdown

Initial setup

Library and test coverage

Basic workflow

Dependency ranges

Testing lower dependency versions

Closing thoughts

Resources

Validate Your PHP API Tests Against OpenAPI Definitions – a Laravel Example [2023 update]

The issue

A solution

PSR-7

A Laravel example

Conclusion

Resources

A Complete Guide to Laravel Sail

In this post

What is Laravel Sail?

How does it compare to its predecessors?

How does it work?

The docker-compose.yml file

The mysql service

The redis service

The laravel.test service

The meilisearch, mailhog and selenium services

The sail script

Extending Laravel Sail

Installing extra extensions

Adding new services

Custom sail commands

What's wrong with Laravel Sail anyway?

The whale in the cabin

You don't need Laravel Sail

Conclusion

Resources

How to Build and Distribute Beautiful Command-Line Applications with PHP and Composer

In this post

Prerequisites

Repository and core dependencies

Entry point

Command

Styling the output

Distribution test

PHP version support

Automated test

GitHub workflow

Release

Cleaning up

Conclusion

Resources

How to Build a Dynamic GitHub Profile with GitHub Actions and PHP

The placeholder

The PHP script

The workflow

Conclusion

Resources

The `docker-compose.yml` file

The `mysql` service

The `redis` service

The `laravel.test` service

The `meilisearch`, `mailhog` and `selenium` services

The `sail` script

Custom `sail` commands