DEV Community: lotyp

Laravel Config Problem: Is It Time for a Revolution?

lotyp — Wed, 17 Jul 2024 10:26:38 +0000

📄 Introduction

While working on the Bridge package Laravel Symfony Serializer, I ran into an unexpected limitation: Laravel configurations don't work with objects.

This issue made me look closely at how Laravel is built and rethink how we set up the framework.

→ In This Article

Why caching configs matters
The challenge of using objects in configs
Existing workarounds and their drawbacks
How others tackle this issue
Applying the "Strategy" pattern to our problem
Spiral Framework's approach and its advantages
Potential improvements for Laravel configuration
Impact on Developer Experience (DX)

We'll start by identifying the problem, then examine existing solutions, and finally propose a new approach.

This journey won't just solve a specific issue – it'll give us fresh insights into framework development and evolution.

As developers, we're always pushing our boundaries. That's why we're not just sticking to Laravel – we're exploring solutions from other frameworks to broaden our perspective.

Let's dive in!

🤔 Why Caching Configs Matters?

Before we dive into the object-in-config issue, let's tackle a key question: why does Laravel bother caching configs in the first place?

→ The Config Challenge

Every time someone visits a Laravel site, here's what happens behind the scenes:

Laravel reads all the config files
It processes their contents
Then it merges everything into one big array

Sounds simple, right? But there's a catch.

→ The Performance Hit

Let's break it down with a real example. Imagine your app has 20 config files. For each request, Laravel has to:

Open 20 files
Read 20 files
Close 20 files
Process and merge all that data

That's a lot of work, especially when your site gets busy. Each config file needs its own Input/Output (I/O) operation, and in traditional PHP, every new HTTP request kicks off this whole process again.

→ Caching to the Rescue

Here's how Laravel's config caching solves this:

It combines all configs into one array
Saves this array as a single PHP file
On future requests, it reads just this one file

→ The Payoff

Speed boost: Significantly cuts down load times
Fewer I/O operations: Less strain on your file system
Memory efficiency: Configs load once and stay loaded
Better scalability: Your app can handle more requests

For live websites, these improvements make a big difference in performance and how well your app can scale.

→ The Object Dilemma

Now, using objects in configs can be great. They offer perks like type safety and auto-completion in your code editor. But here's the rub: they don't play nice with Laravel's caching system.

This clash between speeding things up and making configs more powerful is exactly what we're going to tackle in this article.

🤯 The Object Caching Issue in Laravel Configs

The php artisan config:cache command fails to cache objects in configuration files.

For example, let's place several objects in the config/serializer.php config:

<?php

use Symfony\Component\Serializer\Encoder;

return [
    // ...
    'encoders' => [
        new Encoder\JsonEncoder(),
        new Encoder\CsvEncoder(),
        new Encoder\XmlEncoder(),
    ],
    // ...
];

Attempting to cache this configuration results in an error:

/app $ php artisan config:cache

   LogicException

  Your configuration files are not serializable.

  at vendor/laravel/framework/src/Illuminate/Foundation/Console/ConfigCacheCommand.php:73
     69▕             require $configPath;
     70▕         } catch (Throwable $e) {
     71▕             $this->files->delete($configPath);
     72▕
  ➜  73▕             throw new LogicException('Your configuration files are not serializable.', 0, $e);
     74▕         }
     75▕
     76▕         $this->components->info('Configuration cached successfully.');
     77▕     }

  1   bootstrap/cache/config.php:807
      Error::("Call to undefined method Symfony\Component\Serializer\Encoder\JsonEncoder::__set_state()")
      +13 vendor frames

  15  artisan:35
      Illuminate\Foundation\Console\Kernel::handle(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))

Unexpected, right? Let's unpack what's happening.

→ How the Config Module Works in Laravel

All configuration files are located in the /config folder in the root directory of the project.

These files contain settings for various aspects of the framework, such as the database, caching, sessions, and other components.

When the application is initialized, Laravel loads all configuration files from this directory and combines them into a single configuration array.

This array is made available through the global variable $app['config'] in the application container.

Developers can access configurations from anywhere in the application in three ways:

// Using `Facade`
$timezone = Config::get('app.timezone');

// Using helper function
$timezone = config('app.timezone');

// Directly over Container
$timezone = $app['config']->get('app.timezone');

For package developers, configurations can be published to the application's /config directory:

$ php artisan vendor:publish \
  --provider="WayOfDev\Serializer\Bridge\Laravel\Providers\SerializerServiceProvider" \
  --tag="config"

This allows users of package to easily customize its behavior in their applications.

This system provides flexibility in managing application settings, but, as we will see later, it can create problems when trying to cache configurations with objects.

→ Configuration Caching Process

By default, Laravel reads all configuration files from the /config directory on every request.

To optimize this process and improve performance, the framework provides a configuration caching mechanism.

To create a cached version of all configurations, use the command:

php artisan config:cache

This command does the following:

Reads all files from the /config directory
Combines their contents into one large array
Saves this array as a PHP file in /bootstrap/cache/config.php

The resulting cache file looks something like this:

<?php

return array(
    0 => 'hashing',
    9 => 'broadcasting',
    10 => 'view',
    'app' => array(
        'name' => 'laravel',
        'env' => 'local',
        'debug' => true,
    // ...
        'maintenance' => array(
            'driver' => 'file',
        ),
        'providers' => array(
            0 => 'Illuminate\\Auth\\AuthServiceProvider',
            1 => 'Illuminate\\Broadcasting\\BroadcastServiceProvider',
            // ...
        ),
    ),
);

Once this cached file is created, Laravel will use it instead of reading separate configuration files on every request.

This results in significant performance improvements due to:

Significant reduction in the number of I/O operations: instead of reading many files, only one is read.
Reduced processing time: There is no need to parse and merge separate configuration files.
Reducing the load on the file system: especially noticeable with high traffic.

It's important to note that the benefits of configuration caching are most noticeable in traditional PHP applications, where each request starts a new PHP process.

Long-running applications (such as those using RoadRunner) may not get such a significant performance boost from configuration caching, since they already keep the configuration in memory between requests.

However, even for long-running applications, configuration caching can be useful during initial boot or process restart, allowing for faster initialization.

💡 Interesting fact:

The cached config should not be stored in the repository, since it contains values from the .env file.

After caching, the env() function becomes useless.

→ Technical Aspect of the Problem

Now that we understand how configuration caching works in Laravel, let's look at why the problem occurs when trying to use objects instead of the usual arrays.

Root of the Problem: `var_export()`

Laravel serializes configurations using the PHP var_export() function.

In the context of Laravel, the absence of a __set_state() method on objects used in configurations (in my case, Symfony\Component\Serializer\Encoder\JsonEncoder) results in an error when attempting to cache.

Here is the key code snippet from src/Illuminate/Foundation/Console/ConfigCacheCommand.php:

<?php

// ...

$configPath = $this->laravel->getCachedConfigPath();

$this->files->put(
    $configPath, '<?php return '.var_export($config, true).';'.PHP_EOL
);

// ...

The var_export() function works great with arrays and primitive data types, which are used in Laravel configurations by default.

However, there are difficulties in processing objects.

When the var_export() function encounters an object, it attempts to call the static method __set_state() on that object's class.

<?php

class Config {
    public $key = 'value';
}

$object = new Config();

// Tries to call Config::__set_state()
// and throws an error if the method is not defined
echo var_export($object, true);

If the __set_state() method is not implemented in the object class (which is often the case), an error occurs.

Error Breakdown

For example, when trying to cache the configuration of my Laravel Symfony Serializer package, which uses Symfony objects for serialization, the following error occurred:

Error::("Call to undefined method Symfony\Component\Serializer\Encoder\JsonEncoder::__set_state()")

This error can be confusing because the Your configuration files are not serializable message does not directly indicate a problem with the objects.

It is important to note that this problem often does not appear at the development stage, but during deployment to production or staging environments, where the php artisan config:cache command is typically used to optimize performance.

Why is This Important to Solve

While arrays work well for basic configurations, using objects in configurations could provide a number of benefits:

Type safety
Improved IDE support (autocompletion, tooltips)
More structured and object-oriented approach to configuration

Solving these complexities would allow developers to create more flexible and expressive configurations while still maintaining the benefits of Laravel caching.

In the following sections, we'll look at different approaches to solving this problem, which will allow objects to be used in configurations without losing caching capabilities.

💭 Hint from Elliot Derhay

While googling for solutions, I found an article by Elliot Derhay where he encountered a similar problem in the package spatie/laravel-markdown.

He proposed a solution by adding Trait Resumeable to classes used as objects in configurations:

<?php

trait Resumeable
{
    public static function __set_state(array $state_array): static
    {
        $object = new static();

        foreach ($state_array as $prop => $state) {
            if (! property_exists($object, $prop)) continue;
            $object->{$prop} = $state;
        }

        return $object;
    }
}

→ Why is this not a Solution?

While this solution may work in some cases, it has a number of problems in the context of my Symfony Bridge package:

Increasing support complexity: Adding Trait to each class would require changing a lot of code, making future support difficult.
Violation of clean code: Classes will contain logic that is not related to their main purpose, which is contrary to the principles of clean code.
Compatibility Issues: Making changes to a third-party library such as Symfony may cause problems with updates to that library.

The main reason is that we cannot modify other people's packages, and this solution is local, not scalable.

→ Working Around the Problem Instead of Solving It

What surprised me was that Spatie, having a lot of influence in the Laravel Community, decided to simply work around the problem instead of solving it in the Laravel core itself.

Their solution was to use only FQCN (Fully Qualified Class Names) instead of objects in configurations:

<?php

return [
    // ...

    'block_renderers' => [
-       // ['renderer' => new MyCustomCodeRenderer(), 'priority' => 0]
+       // ['renderer' => MyCustomCodeRenderer::class, 'priority' => 0]
    ],

    // ...
];

This approach is not flexible and does not provide for supplying optional parameters to the constructor if such are needed. It only works around the problem, not solves it.

→ Reflections on the Spatie Approach

Given Spatie's many contributions to the Laravel community, their decision leaves room for constructive discussion and perhaps re-evaluation of approaches to solving similar problems in the future.

It would be interesting to hear from Spatie and other leading community members on this issue.

👀 Hexium got Around This Problem in Their Own Way

When I was working on upgrading my package Laravel Symfony Serializer from Laravel 10.x to laravel 11.x, I decided to see what new things others had come up with.

My search led me to another package Hexium Agency's Symfony Serializer for Laravel which also adds Symfony Serializer support to Laravel.

Let's take a look at how they approached the problem with objects in configurations.

→ Analysis of the Hexium Approach

In config file config/symfony-serializer.php of the package we see that they use string aliases instead of objects:

<?php

return [
    'normalizers' => [
        // ...
        [
            'id' => 'serializer.normalizer.datetimezone',
            'priority' => -915,
        ],
        [
            'id' => 'serializer.normalizer.dateinterval',
            'priority' => -915,
        ],
        [
            'id' => 'serializer.normalizer.datetime',
            'priority' => -910,
        ],
        [
            'id' => 'serializer.normalizer.json_serializable',
            'priority' => -950,
        ],
        // ...
    ],
    'encoders' => [
        // ...
        [
            'id' => 'serializer.encoder.xml',
        ],
        [
            'id' => 'serializer.encoder.json',
        ],
        // ...
    ],

    // ...
];

When looking at the Service Provider, it becomes clear that they strictly prescribe the creation of these services:

SymfonySerializerForLaravelServiceProvider.php

<?php

class SymfonySerializerForLaravelServiceProvider extends PackageServiceProvider
{
    // ...

    public function registeringPackage(): void
    {
        // ...

        // Encoders
        $this->app->bind('serializer.encoder.xml', static function () {
            return new XmlEncoder();
        });
        $this->app->tag('serializer.encoder.xml', ['serializer.encoder']);

        $this->app->bind('serializer.encoder.json', static function () {
            return new JsonEncoder(null, null);
        });
        $this->app->tag('serializer.encoder.json', ['serializer.encoder']);

        $this->app->bind('serializer.encoder.yaml', static function () {
            return new YamlEncoder();
        });
        $this->app->tag('serializer.encoder.yaml', ['serializer.encoder']);

        $this->app->bind('serializer.encoder.csv', static function () {
            return new CsvEncoder();
        });
        $this->app->tag('serializer.encoder.csv', ['serializer.encoder']);

        // ...
    }

    // ...
}

→ Workaround Instead of Solution

Having considered the approach of this package, we can highlight the following features:

Pros:

Ability to override settings values using those aliases that are already defined in the package

Cons:

To add new objects to the config, you need to create a binding in the Service Provider
The approach violates the principles of configuration flexibility and expandability
The configuration becomes rigid, requiring changes to the Service Provider to add new settings
Using aliases instead of objects deprives configuration of benefits such as IDE autocompletion and type safety
Package customization involves making changes directly to the code of the Hexium package itself

This approach was most likely caused by the inability to use objects directly in Laravel configuration files.

The authors of the package decided to work around this problem, but at the same time sacrificed flexibility, convenience and extensibility of the configuration.

Thus, this solution cannot be called a complete one, but rather a workaround that has significant limitations.

😬 My intermediate attempt to solve the problem

After analyzing existing solutions such as the Spatie and Hexium approaches, which were essentially workarounds for the problem, I decided to implement my own approach based on the Strategy pattern.

→ Solution Strategy in The Strategy Pattern!

I created interfaces for Registration Strategies encoders and normalizers.

This allowed for flexibility and expandability of the configuration without violating the SOLID principles.

For example, here is the interface for the Encoders Registration Strategy:

<?php

declare(strict_types=1);

namespace WayOfDev\Serializer\Contracts;

use Symfony\Component\Serializer\Encoder\DecoderInterface;
use Symfony\Component\Serializer\Encoder\EncoderInterface;

interface EncoderRegistrationStrategy
{
    /**
     * @return iterable<array{encoder: EncoderInterface|DecoderInterface}>
     */
    public function encoders(): iterable;
}

And its implementation to register default encoders:

<?php

declare(strict_types=1);

namespace WayOfDev\Serializer;

use Symfony\Component\Serializer\Encoder;
use Symfony\Component\Serializer\Encoder\DecoderInterface;
use Symfony\Component\Serializer\Encoder\EncoderInterface;

final class DefaultEncoderRegistrationStrategy implements Contracts\EncoderRegistrationStrategy
{
    /**
     * @return iterable<array{encoder: EncoderInterface|DecoderInterface}>
     */
    public function encoders(): iterable
    {
        yield ['encoder' => new Encoder\JsonEncoder()];
        yield ['encoder' => new Encoder\CsvEncoder()];
        yield ['encoder' => new Encoder\XmlEncoder()];
    }
}

The config file for my laravel-symfony-serializer package config/serializer.php now looked like this:

<?php

use WayOfDev\Serializer\DefaultEncoderRegistrationStrategy;
use WayOfDev\Serializer\DefaultNormalizerRegistrationStrategy;

return [
    // ...

    /*
     * Allows you to specify the strategy class for registering your normalizers.
     * Default is 'WayOfDev\Serializer\DefaultNormalizerRegistrationStrategy'.
     */
    'normalizerRegistrationStrategy' => DefaultNormalizerRegistrationStrategy::class,

    /*
     * Allows you to register your custom encoders.
     * Default encoders are registered in src/DefaultEncoderRegistrationStrategy.php.
     *
     * Default encoders include:
     *      JsonEncoder,
     *      CsvEncoder,
     *      XmlEncoder,
     *      YamlEncoder.
     *
     * You can replace the default encoders with your custom ones by implementing
     * your own registration strategy and defining it here.
     */
    'encoderRegistrationStrategy' => DefaultEncoderRegistrationStrategy::class,

    // ...
];

Registration happens here: SerializerServiceProvider.php:

<?php

// ...

use WayOfDev\Serializer\Contracts\EncoderRegistrationStrategy;
use WayOfDev\Serializer\Contracts\EncoderRegistryInterface;
use WayOfDev\Serializer\Contracts\ConfigRepository;

final class SerializerServiceProvider extends ServiceProvider
{
    // ...

    private function registerEncoderRegistry(): void
    {
        $this->app->singleton(EncoderRegistrationStrategy::class, static function (Application $app): EncoderRegistrationStrategy {
            /** @var Config $config */
            $config = $app->make(ConfigRepository::class);

            $strategyFQCN = $config->encoderRegistrationStrategy();

            return $app->make($strategyFQCN);
        });

        $this->app->singleton(EncoderRegistryInterface::class, static function (Application $app): EncoderRegistryInterface {
            /** @var EncoderRegistrationStrategy $strategy */
            $strategy = $app->get(EncoderRegistrationStrategy::class);

            return new EncoderRegistry($strategy);
        });
    }

    // ...
}

→ What's The Difference?

This approach has a number of advantages compared to the previously discussed options:

Flexibility: Users can easily replace the standard strategy with their own without changing the core code of the package.
Extensibility: Adding new encoders or normalizers does not require changing the core code of the laravel-symfony-serializer package.
Encapsulation: The logic for creating and configuring encoders and normalizers is encapsulated in separate classes, which improves code organization.
Adherence to SOLID principles: This approach better adheres to the open/closed principle, allowing functionality to be extended without changing existing code.

However, this approach also has some disadvantages:

Challenge for the user: To make changes, the user needs to create their registration strategy as a separate class and store it in their project.
More Code: This approach requires writing more code than simply defining the array in a config file.
Potential DX Complication: From a Developer Experience (DX) perspective, this approach may seem more complex to new users of the package.

Although this intermediate approach is not a perfect solution, it provides a more flexible and extensible solution than previous options and better aligns with object-oriented programming principles. However, as we will see later, there is a more complete solution.

🤔 What's Wrong With All These Approaches?

After looking at the various work-arounds around the object problem in Laravel configurations, it becomes clear that each approach has its limitations and does not solve core problem. Let's analyze them in more detail:

→ Using FQCN (Fully Qualified Class Names)

The approach proposed by Spatie and Elliot Derhay in package spatie/laravel-markdown, although it solves the problem of configuration serialization, significantly limits configuration flexibility:

'block_renderers' => [
    ['renderer' => MyCustomCodeRenderer::class, 'priority' => 0]
],

This approach does not allow parameters to be passed to the class constructor, which can be critical for complex objects with custom behavior.

Developers have to find workarounds to initialize objects with the desired parameters, which complicates the code and reduces its readability.

→ Hardcoding of Dependencies in The Service Provider

The Hexium approach, where dependencies are hardcoded in the Service Provider, violates the SOLID (Open/Closed) principle:

$this->app->bind('serializer.encoder.json', static function () {
    return new JsonEncoder(null, null);
});

This approach makes it difficult to extend and modify behavior without changing the package source code.

If a user needs to change the JsonEncoder configuration, they will have to redefine the entire Service Provider, which can lead to code duplication and become more difficult to maintain with package updates.

→ Lack of Dependency Injection Support

All considered approaches do not take into account the possibility of using Dependency Injection in object constructors.

For example, if we have a class with dependencies:

class MyCustomCodeRenderer {
   public function __construct(
       public LoggerInterface $logger,
       public int $priority = 100,
   ){}
}

None of the approaches discussed make it easy to pass LoggerInterface when creating an object via configuration. This forces developers to find workarounds or complicate the application architecture.

→ Lack of a Unified Approach in The Laravel Ecosystem

The lack of a standard solution for working with objects in Laravel configurations results in different packages taking different approaches.

This makes it difficult to understand and integrate different packages in one project.

⚡️ How It Is Implemented in The Spiral Framework

→ About The Spiral Framework

Spiral Framework is a modern PHP framework for developing enterprise applications that supports: high-performance request processing using RoadRunner, an efficient queuing system, Temporal workflows, WebSockets, gRPC and microservice architecture.

It is designed with an emphasis on intuitiveness and ease of use, offering a Developer Experience similar to Laravel and Symfony.

→ Container Auto-Wiring

Spiral attempts to hide container implementation and configuration from your application's domain layer by providing rich auto-wiring functionality that allows you to delegate object creation to the container.

This makes managing dependencies in your application much easier.

When the container attempts to resolve Autowire, it automatically instantiates the class specified in the first argument and passes additional parameters if specified in the second argument.

The key element of this approach is the Spiral\Core\Container\Autowire class.

Let's look at the implementation of the class in more detail:

<?php

namespace Spiral\Core\Container;

// ...

final class Autowire
{
    private ?object $target = null;

    public function __construct(
        private readonly string $alias,
        private readonly array $parameters = []
    ) {
    }

    public static function __set_state(array $anArray): static
    {
        return new self($anArray['alias'], $anArray['parameters']);
    }

    // ...

    public function resolve(FactoryInterface $factory, array $parameters = []): object
    {
        return $this->target ?? $factory->make($this->alias, \array_merge($this->parameters, $parameters));
    }
}

This class allows:

Specify the class or alias of the service that needs to be created ($alias), for Laravel developers this will be equivalent to the $abstract parameter in the app()→make() method
Pass parameters to the constructor of this class ($parameters).
Postpone the creation of the object until the moment when it is really needed (resolve method).

Pay attention to the __set_state method. It solves the problem we had previously when using var_export() to cache configurations.

→ Using Autowire in Configurations

Now let's look at how this can help us solve the problem with objects in Laravel configurations.

Let's remember the example of a class from Spatie, where the constructor had an external dependency:

<?php

class MyCustomCodeRenderer {
   public function __construct(
       public LoggerInterface $logger,
       public int $priority = 100,
   ){}
}

Using the Spiral approach with Autowire, we could configure this class in our config as follows:

return [
    // ...
    'block_renderers' => [
       new Autowire(MyCustomCodeRenderer::class, ['priority' => 50]),
    ],
    // ...
];

This approach has several advantages:

We can use objects in configurations without worrying about serialization issues.
External dependencies (for example, LoggerInterface) will be automatically resolved by the container.
We can override only those parameters that we need (in this case, priority).
The creation of an object is postponed until the moment when it is actually needed.

This approach allows us to achieve a balance between configuration flexibility and performance, solving the problems we encountered previously.

In the next section, we'll look at how we could adapt this approach for use in Laravel.

💡 How can this be solved in Laravel Framework

After analyzing existing approaches and studying the solution described above, we can propose a more elegant solution for Laravel that will allow objects to be used in configurations while maintaining caching capabilities.

→ Making the AutoWire as a Wrapper Class

Inspired by the Spiral Framework solution, we can create an AutoWire class that will serve as a wrapper for objects in configurations. This class will implement the magic method __set_state(), allowing it to be used with var_export().

Here is the concept for implementing the AutoWire class:

<?php

declare(strict_types=1);

namespace Support;

use Illuminate\Contracts\Container\BindingResolutionException;

final readonly class AutoWire
{
    /**
     * Create a new AutoWire instance.
     *
     * @param array<string, mixed> $parameters
     */
    public function __construct(private string $abstract, private array $parameters = [])
    {
    }

    /**
     * Magic method for var_export().
     *
     * @param array{abstract: string, parameters: array<string, mixed>} $properties
     *
     * @return static
     */
    public static function __set_state(array $properties): self
    {
        return new self($properties['abstract'], $properties['parameters']);
    }

    /**
     * Resolve the AutoWire instance using the container.
     *
     * @throws BindingResolutionException
     */
    public function resolve(): mixed
    {
        return app()->make($this->abstract, $this->parameters);
    }
}

This class performs the following functions:

Stores the name of the class ($abstract) and the parameters for creating it ($parameters).
Implements the __set_state() method, which allows you to recreate the object after serialization.
Provides the resolve() method, which uses the Laravel container to lazily load an object.

→ Using AutoWire in Our Config Files

Now we can change our configuration file config/serializer.php using AutoWire:

<?php

use Support\AutoWire;
use Symfony\Component\Serializer\Encoder;
use Symfony\Component\Serializer\Encoder\JsonDecode;

return [
    // ...

    'encoders' => [
        new AutoWire(
            abstract: Encoder\JsonEncoder::class,
            parameters: [
                'defaultContext' => [
                    JsonDecode::ASSOCIATIVE => true,
                ],
            ]
        ),
        new AutoWire(Encoder\CsvEncoder::class),
        Encoder\XmlEncoder::class,
        Encoder\YamlEncoder::class,
    ],

    // ...
];

The Service Provider will now look like this:

<?php

// ...

final class SerializerServiceProvider extends ServiceProvider
{
    // ...

    private function registerEncoderRegistry(): void
    {
        $this->app->singleton(EncoderRegistryInterface::class, static function (Application $app): EncoderRegistryInterface {
            /** @var Config $config */
            $config = $app->make(ConfigRepository::class);

            return new EncoderRegistry(
                collect($config->encoders())->map(static function (string|AutoWire|EncoderInterface $encoder) use ($app) {
                    if ($encoder instanceof EncoderInterface) {
                        return $encoder;
                    }

                    if ($encoder instanceof AutoWire) {
                        return $encoder->resolve();
                    }

                    return $app->make($encoder);
                })->all()
            );
        });
    }

    // ...
}

This approach allows us to:

Use objects in configurations
Pass parameters to object constructors.
Maintain the ability to cache configurations.
Use standard FQCN strings if there is no need for objects

→ Running

After making the changes, we can try running the configuration caching command:

/app $ php artisan config:cache

   INFO  Configuration cached successfully.

As we can see, the command is executed successfully, without errors.

If we look at the contents of the cached configuration file bootstrap/cache/config.php, we see the following:

<?php

declare(strict_types=1);

return [
    // ...
    'serializer' => [
        // ...
        'encoders' => [
            0 => Support\AutoWire::__set_state([
                'abstract' => 'Symfony\\Component\\Serializer\\Encoder\\JsonEncoder',
                'parameters' => [
                    'defaultContext' => [
                        'json_decode_associative' => true,
                    ],
                ],
            ]),
            1 => Support\AutoWire::__set_state([
                'abstract' => 'Symfony\\Component\\Serializer\\Encoder\\CsvEncoder',
                'parameters' => [
                ],
            ]),
            2 => Support\AutoWire::__set_state([
                'abstract' => 'Symfony\\Component\\Serializer\\Encoder\\XmlEncoder',
                'parameters' => [
                ],
            ]),
        ],
    ],
];

→ How Does It Work?

When caching configurations, Laravel uses var_export() to serialize the configuration array.
For AutoWire objects, the __set_state() method is called, which saves information about the class and its parameters.
When loading a cached configuration, AutoWire objects are restored using __set_state().
When a real object is required, the resolve() method is called, which uses the Laravel container to create an object with the required parameters.

When does resolve() run?

The resolve() method is called when the dependency container attempts to instantiate an object. This happens "lazyly", that is, only when the object is actually needed.

This approach allows us to use objects in configurations while still being cacheable. It also provides flexibility in configuring objects by allowing parameters to be passed to their constructors.

🗝️ Going even further, what if we use DTO in the configuration?

Everything we've covered so far could be solved without making any changes to the Laravel core. But what if we go further and think about more radical changes?

→ Simple Example: Authentication Configuration

Have you ever experienced difficulty configuring Laravel? How often do you have to look at the documentation when you need, for example, to configure an authentication driver?

Let's do a thought experiment: look at this piece of the config and try to remember what keys should be in the auth.php config without looking at the documentation:

<?php

return [
    // ...

    'passwords' => [
        'users' => [
            '???' => 'users',
            '???' => env('AUTH_PASSWORD_RESET_TOKEN_TABLE', 'password_reset_tokens'),
            '???' => 60,
            '???' => 60,
        ],
    ],

    // ...
];

I am sure many of you will not be able to remember even the first of the keys. The problem is that arrays do not support autocompletion. This is only possible when using additional paid plugins for the IDE.

Now let's imagine that instead of an array we use an object:

<?php

declare(strict_types=1);

namespace Support\Auth\Config;

use ReflectionClass;
use ReflectionException;

use function array_key_exists;

final readonly class PasswordConfig
{
    /**
     * @param non-empty-string $provider
     * @param non-empty-string $table
     * @param int<0, max> $expire
     * @param int<0, max> $throttle
     */
    public function __construct(
        public string $provider,
        public string $table,
        public int $expire = 60,
        public int $throttle = 60,
    ) {
    }

    /**
     * @param array<string, mixed> $properties
     *
     * @throws ReflectionException
     */
    public static function __set_state(array $properties): self
    {
        $ref = new ReflectionClass(self::class);

        $arguments = [];
        foreach ($ref->getConstructor()?->getParameters() ?? [] as $parameter) {
            $name = $parameter->getName();
            $arguments[$name] = array_key_exists($name, $properties)
                ? $properties[$name]
                : $parameter->getDefaultValue();
        }

        return new self(...$arguments);
    }
}

Let's change the auth.php config itself in empty Laravel Application and see how it will be now:

<?php

use Support\Auth\Config\PasswordConfig;

return [
    // ...

    'passwords' => [
        'users' => new PasswordConfig(
            provider: 'users',
            table: 'password_reset_tokens',
            expire: 60,
            throttle: 60,
        ),
    ],

    // ...
];

Here we are using PHP 8.0 Named Arguments, but even without using them everything has become much simpler and clearer: we just need to look at the parameters of the PasswordConfig constructor. And if we use PHPStorm or similar IDEs, then the tooltips will be automatically available out of the box.

Also, such a class already contains the __set_state function which will allow us to use the existing Laravel php artisan config:cache mechanism.

→ Complex Example: Database Configuration

But let's dig deeper and look at a more complex example - database configuration.

I use this approach in my wayofdev/laravel-cycle-orm-adapter package. The configuration file can be viewed here: config/cycle.php

Let's take a look at the default database.php configuration file in Laravel.

What it looks like now:

<?php

return [
    // ...

    'connections' => [
        'memory' => [
            'driver' => 'sqlite',
            'url' => env('DB_URL'),
            'database' => ':memory:',
            'prefix' => '',
            'foreign_key_constraints' => env('DB_FOREIGN_KEYS', true),
        ],

        'sqlite' => [
            'driver' => 'sqlite',
            'url' => env('DB_URL'),
            'database' => env('DB_DATABASE', database_path('database.sqlite')),
            'prefix' => '',
            'foreign_key_constraints' => env('DB_FOREIGN_KEYS', true),
        ],

        'mysql' => [
            'driver' => 'mysql',
            'url' => env('DB_URL'),
            'host' => env('DB_HOST', '127.0.0.1'),
            'port' => env('DB_PORT', '3306'),
            'database' => env('DB_DATABASE', 'laravel'),
            'username' => env('DB_USERNAME', 'root'),
            'password' => env('DB_PASSWORD', ''),
            'unix_socket' => env('DB_SOCKET', ''),
            'charset' => env('DB_CHARSET', 'utf8mb4'),
            'collation' => env('DB_COLLATION', 'utf8mb4_unicode_ci'),
            'prefix' => '',
            'prefix_indexes' => true,
            'strict' => true,
            'engine' => null,
            'options' => extension_loaded('pdo_mysql') ? array_filter([
                PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
            ]) : [],
        ],

        // ...    
    ],
];

What this might look like if we use a DTO for configuration:

<?php

use Support\Database\Config;

return [
    // ...

    'connections' => [
        'memory' => new Config\SQLiteDriverConfig(
            connection: new Config\SQLite\MemoryConnectionConfig(),
            driver: 'sqlite',
        ),

          'sqlite' => new Config\SQLiteDriverConfig(
              connection: new Config\SQLite\FileConnectionConfig(
                  url: env('DB_URL'),
                  database: env('DB_DATABASE', database_path('database.sqlite'))
              ),
              driver: 'sqlite',
              prefix: '',
              foreign_key_constraints: env('DB_FOREIGN_KEYS', true),
          ),

        'mysql' => new Config\MySQLDriverConfig(
            connection: new Config\MySQL\TcpConnectionConfig(
                url: env('DB_URL'),
                database: env('DB_DATABASE', 'laravel'),
                host: env('DB_HOST', '127.0.0.1'),
                port: env('DB_PORT', 3306),
                username: env('DB_USERNAME', 'root'),
                password: env('DB_PASSWORD', ''),
                unix_socket: env('DB_SOCKET', ''),
            ),
            driver: 'mysql',
            options: extension_loaded('pdo_mysql') ? array_filter([
                PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
            ]) : [],
            charset: env('DB_CHARSET', 'utf8mb4'),
            collation: env('DB_COLLATION', 'utf8mb4_unicode_ci'),
            prefix: '',
            prefix_indexes: true,
            strict: true,
            engine: null,
        ),

        // ...    
    ],
];

This approach provides all the benefits of using DTOs and PHP 8.0 Named Arguments that we touched on earlier.

→ What Conclusions Can We Make?

Using the AutoWire class together with configuration DTOs provides a number of significant advantages:

Improved structure and typing: DTOs provide clear configuration structure, and strong typing helps prevent compile-time errors.
Usability: Named Arguments in PHP 8.0 make configuration more readable and less prone to typing errors.
IDE Support: Object-oriented approach provides better support for autocompletion and tooltips in modern IDEs.
Structure-level validation: DTOs allow you to build basic validation directly into the object structure.
Cache Compatibility: The __set_state() method in DTO and AutoWire provides compatibility with Laravel's configuration caching mechanism.
Improved Documentation: The DTO structure serves as self-documenting code, making configuration easier to understand.
Polymorphism capability: You can use inheritance and interfaces to create more complex configurations.
Combination with AutoWire: Using AutoWire allows you to defer object creation and dependency injection while still maintaining the benefits of DTO.

This approach significantly improves the Developer Experience, making configuration work more intuitive and less error-prone.

😌 Conclusion: New Horizons

Our journey through the labyrinths of Laravel has come to an end, but this is only the beginning. We've gone from discovering a problem with caching configurations with objects to creating a potential solution that could change the way we work with Laravel configuration.

Now I encourage you to join this journey:

🤔 What do you think of the proposed solution using AutoWire and configuration DTOs? Do you see potential problems or improvements?
💡 Do you have experience in solving similar problems in your projects? How have you dealt with the limitations of Laravel configurations?
🔮 Do you think Laravel should evolve in this direction? What other aspects of the framework do you think need improvement?
🌈 What other ideas do you have for improving the Developer Experience in Laravel or other frameworks?

Let's continue this conversation! Share your thoughts in the comments. Your experience and ideas could be the key to the next big thing in the development world.

🚀 Let's continue the journey together!

🐙 Follow my GitHub account: github.com/lotyp
🐦 Follow me on X: х.com/wlotyp
💼 I'm open to new opportunities! Connect with me on LinkedIn: in/wayofdev

Simplifying Local Development with Docker, mkcert, DNSMasq and Traefik.

lotyp — Mon, 10 Jun 2024 22:10:55 +0000

Hello dev.to community!

I've created a project called wayofdev/docker-shared-services that my team and I use to streamline our local development.

It simplifies the setup for Dockerized projects on macOS and Linux, and I’m excited to share it with the community. Let's dive into how it can help you and your team.

🗂️ Table of Contents

Key Features
Problem
The Solution: Docker Shared Services
Requirements
Quick Start Guide (macOS)
Connecting Your Projects to Shared Services
Example: Spin-up Laravel Sail Project
Example: Want to See a Ready-Made Template?
Linux
Conclusion

Key Features 🌟

By implementing this approach, you will have:

Automated Local DNS and SSL Setup: No more manual edits to /etc/hosts or dealing with self-signed certificate warnings. You'll have an automated solution for DNS and SSL.
Consistent Development Environment: All team members will have the same setup, reducing environment-related bugs and making onboarding new developers faster and easier.
Elimination of Port Conflicts: Using Traefik, you can avoid port conflicts entirely, allowing multiple dockerized projects to run concurrently without issues.
User-Friendly Local URLs: Access your projects via custom local domains like project.docker instead of localhost:8000, improving the overall development experience.
Simplified CORS and Cookie Management: With SSL in place for local domains, configuring CORS and Cookies will mirror production settings, reducing debugging time.
Enhanced Testing Environment: Test OAuth, Secure Cookies, and HTTPS APIs locally, ensuring they work exactly as they will in production.
Improved Service Discovery and Routing: Traefik provides automatic service discovery and routing, making it easier to manage and access various services within your Docker network.
Ease of Integration with Existing Projects: Quickly connect your existing Docker projects to the docker-shared-services setup, leveraging DNSMasq and Traefik for better service management.

Problem 🤔

→ Common Challenges in Local Development

Manual DNS Configuration:
Developers often need to update their /etc/hosts file to direct traffic for local domains like yourproject.local or yourproject.domain.local to 127.0.0.1. This is tedious and requires admin access.
Lack of SSL Support:
Local domains often lack SSL, making it hard to test secure connections and leading to issues with OAuth providers, CORS, and cookies.
Port Conflicts:
Forwarding Docker service ports to the host machine can cause conflicts, especially when multiple services use common ports like 80 or 443.
Cumbersome Hostnames:
Using hostnames like localhost:8000 for local projects is not user-friendly and complicates development.
Complex CORS and Cookie Configuration:
Without SSL and proper DNS setup, configuring CORS and Cookies becomes more challenging.
Consistency Across Team Members:
When a team is working on the same project, maintaining consistency in the local development environment across different machines is challenging. Differences in setup can lead to issues that are hard to debug and resolve, slowing down the development process.

→ The Hard Way

Traditionally, setting up a local development environment with SSL involves a series of manual steps:

Generating and trusting self-signed certificates in the system
Editing the /etc/hosts file
Setting up and configuring Dockerized projects with custom ports
Solving CORS and SSL related problems between local services

These steps are time-consuming and prone to errors, leading to a frustrating development experience.

The Solution: Docker Shared Services 🐳

The wayofdev/docker-shared-services simplifies local development by providing a Docker-powered environment that integrates Traefik, mkcert, and DNSMasq. This setup offers:

Automated DNS and SSL support
A consistent development environment across different machines
Simplified service discovery and routing using Traefik
Elimination of port conflicts on the host network
The ability to test your Dockerized projects in an environment that closely mimics real-world scenarios, ensuring that your applications behave as expected before deployment

→ Key Components

Traefik:
Traefik acts as a reverse proxy and load balancer, providing routing for your Docker services. It integrates with Docker via docker-compose labeling functionality to automatically discover and route traffic to your services.
mkcert:
mkcert generates locally-trusted development certificates, enabling SSL support for your local domains.
DNSMasq:
Dnsmasq provides lightweight DNS and DHCP services, allowing you to use custom local domains without editing the /etc/hosts file.

→ Going Further

You can go further and pack this project into an Ansible setup. This way, you can automate the provisioning of macOS or Linux hosts, ensuring that all necessary tools and configurations are in place. This not only saves time but also ensures consistency across different environments.

Requirements 🚩

macOS Monterey+ or Linux
- Tested on Ubuntu 22.04, but should also work on Debian or Arch variants
Docker 26.0 or newer
- How To Install and Use Docker on Ubuntu 22.04
- How To Install Docker Desktop on Mac
Homebrew (macOS only): Install via brew.sh
Installed mkcert binary in system
- See full installation instructions in their official README.md
- Quick installation on macOS: brew install mkcert nss

Quick Start Guide (macOS) 🚀

Install Homebrew (if not installed):
If Homebrew is not already installed, run the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Docker (if not installed):
Set up Docker Desktop via Homebrew:
```
brew install --cask docker
```
Install mkcert and nss:
mkcert is a tool that creates locally-trusted development certificates, and nss provides support for mkcert certificates in Firefox.
```
brew install mkcert nss
```
Create shared project directory:
This repository should be run once per machine, so let's create a shared directory for this project:
```
mkdir -p ~/projects/infra && cd ~/projects/infra
```

Clone this repository:

git clone \
  git@github.com:wayofdev/docker-shared-services.git \
  ~/projects/infra/docker-shared-services && \
cd ~/projects/infra/docker-shared-services

Create .env file:
Generate a default .env file, which contains configuration settings for the project.
```
make env
```
Open this file and read the notes inside to make any necessary changes to fit your setup.
Install root certificate and generate default project certs:
This step installs the root certificate into your system's trust store and generates default SSL certificates for your local domains, which are listed in the .env file, under the variable TLS_DOMAINS.
```
make cert-install
```
Note:

Currently, on macOS, you may need to enter your password several times to allow mkcert to install the root certificate.
This is a one-time operation and details can be found in this upstream GitHub issue.
Run this project:
Start the Docker services defined in the repository.
```
make up
```
Check that all Docker services are running:
Ensure Docker is running and services are up by using the make ps and make logs commands.
```
make ps
make logs
```
Add custom DNS resolver to your system:
This allows macOS to understand that *.docker domains should be resolved by a custom resolver via 127.0.0.1, where our DNSMasq, which runs inside Docker, will handle all DNS requests.
```
sudo sh -c 'echo "nameserver 127.0.0.1" > /etc/resolver/docker'
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder
```
You can check that DNS was added by running:
```
scutil --dns
```
Example output:
```
resolver #8
  domain   : docker
  nameserver[0] : 127.0.0.1
  flags    : Request A records, Request AAAA records
  reach    : 0x00030002 (Reachable,Local Address,Directly Reachable Address)
```
Note:

Instead of creating the /etc/resolver/docker file, you can add 127.0.0.1 to your macOS DNS Servers in your Ethernet or Wi-Fi settings.

Go to System Preferences → Network → Wi-Fi → Details → DNS and add 127.0.0.1 as the first DNS server.

This allows you to do it one time, and if you need to create a new local domain, for example *.mac, in the future, it will be automatically resolved without creating a separate /etc/resolver/mac file.
Ping router.docker to check if DNS is working:
Ensure that the DNS setup is functioning correctly.
```
ping router.docker -c 3
ping any-domain.docker -c 3
```
Access Traefik dashboard:
Open https://router.docker.

You should see the Traefik Dashboard:

→ Outcome

At this point, you should have a working local development environment with DNS and SSL support ready to be used with your projects.

Services will be running under a shared Docker network called network.ss, and all projects or microservices that will share the same Docker network will be visible to Traefik. The local DNS, served by DNSMasq, will be available on *.docker domains.

Connecting Your Projects to Shared Services 🔌

To connect your projects to the shared services, configure your project's docker-compose.yaml file to connect to the shared network and Traefik.

This project comes with an example Portainer service, which also starts by default with the make up command. You can check the docker-compose.yaml to see how Traefik labels and the shared network are used to spin up Portainer on the https://ui.docker host, which supports SSL by default.

→ Sample Configuration

Your project should use the shared Docker network network.ss and Traefik labels to expose services to the outside world.

Change your project's docker-compose.yaml file:

---

services:
  web:
    image: wayofdev/nginx:k8s-alpine-latest
    restart: on-failure
+   networks:
+     - default
+     - shared
    volumes:
      - ./app:/app:rw,cached
+   labels:
+     - traefik.enable=true
+     - traefik.http.routers.api-my-project-secure.rule=Host(`api.my-project.docker`)
+     - traefik.http.routers.api-my-project-secure.entrypoints=websecure
+     - traefik.http.routers.api-my-project-secure.tls=true
+     - traefik.http.services.api-my-project-secure.loadbalancer.server.port=8880
+     - traefik.docker.network=network.ss

networks:
+ shared:
+   external: true
+   name: network.ss
+ default:
+   name: project.my-project

In this configuration, we added the shared network and Traefik labels to the web service. These labels help Traefik route the traffic to the service based on the specified rules.

Generate SSL certs for your project:
Go to the docker-shared-services directory:
```
cd ~/projects/infra/docker-shared-services
```
Edit the .env file to add your custom domain:
```
nano .env
```
It should look something like this:
```
TLS_DOMAINS="ui.docker router.docker *.my-project.docker"
```
Generate SSL certificates:
```
make cert-install restart
```

Example: Spin-up Laravel Sail Project 🚀

Let's walk through an example of setting up a Laravel project using Sail and integrating it with the docker-shared-services.

Create an example Laravel project based on Sail:

curl -s "https://laravel.build/example-app" | bash

Open the docker-compose.yaml file of the example-app project and make adjustments:

services:
  laravel.test:
    build:
      context: ./vendor/laravel/sail/runtimes/8.3
      dockerfile: Dockerfile
      args:
        WWWGROUP: '${WWWGROUP}'
    image: sail-8.3/app
-   extra_hosts:
-     - 'host.docker.internal:host-gateway'
    ports:
-     - '${APP_PORT:-80}:80'
-     - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
    networks:
      - sail
+     - shared
    depends_on:
      - ...
+   labels:
+     - traefik.enable=true
+     - traefik.http.routers.test-laravel-app-secure.rule=Host(`api.laravel-app.docker`)
+     - traefik.http.routers.test-laravel-app-secure.entrypoints=websecure
+     - traefik.http.routers.test-laravel-app-secure.tls=true
+     - traefik.http.services.test-laravel-app-secure.loadbalancer.server.port=80
+     - traefik.docker.network=network.ss

  mailpit:
    image: 'axllent/mailpit:latest'
    networks:
      - sail
+     - shared
    ports:
-     - '${FORWARD_MAILPIT_PORT:-1025}:1025'
-     - '${FORWARD_MAILPIT_DASHBOARD_PORT:-8025}:8025'
+   labels:
+     - traefik.enable=true
+     - traefik.http.routers.mail-laravel-app-secure.rule=Host(`mail.laravel-app.docker`)
+     - traefik.http.routers.mail-laravel-app-secure.entrypoints=websecure
+     - traefik.http.routers.mail-laravel-app-secure.tls=true
+     - traefik.http.services.mail-laravel-app-secure.loadbalancer.server.port=8025
+     - traefik.docker.network=network.ss

networks:
  sail:
    driver: bridge
+ shared:
+   external: true
+   name: network.ss

These changes connect the Laravel app and Mailpit docker services to the shared network and expose them via Traefik.

Run the Laravel project:
Navigate to the example-app directory and start the services using Sail.
```
./vendor/bin/sail up -d
```
Check Traefik routers:
Open https://router.docker/dashboard/#/http/routers and check that there are two routers:
- Host(api.laravel-app.docker) → test-laravel-app-secure@docker
- Host(mail.laravel-app.docker)` → mail-laravel-app-secure@docker
Check the setup:
Ensure that your Laravel application and Mailpit services are running correctly by accessing their respective domains:

  * **Laravel app** — https://api.laravel-app.docker
  * **Mailpit** — https://mail.laravel-app.docker

At this point, your Laravel project is integrated with the wayofdev/docker-shared-services, utilizing DNS and SSL support for local development.

Example: Want to See a Ready-Made Template? 👀

If you come from the PHP or Laravel world, or if you want to see how a complete project can be integrated with docker-shared-services, check out wayofdev/laravel-starter-tpl.

This Dockerized Laravel starter template works seamlessly with wayofdev/docker-shared-services, providing a foundation with integrated DNS and SSL support, and can show you the way to implement patterns, stated in this article, in your projects.

Linux 🐧

Linux Users, you are also covered!

If you're using Ubuntu or another Linux distribution, I've included a Linux Quick Start Guide in the README.md of the wayofdev/docker-shared-services project.

This guide provides step-by-step instructions to help you set up the environment on a Linux system, ensuring you can have the same streamlined development experience as described in the macOS Quick Start Guide provided in this article.

Conclusion ✨

In conclusion, the wayofdev/docker-shared-services project offers a streamlined and automated solution for managing local development environments using Docker, mkcert, DNSMasq, and Traefik.

By integrating these tools into your workflow, you can ensure that your local environment closely mirrors production, leading to more reliable and predictable outcomes when deploying applications.

→ What do you think? Would you approach this differently?

I hope this guide has been helpful in demonstrating the potential benefits of using this approach for your local development needs. If you have any suggestions or a better way of achieving this setup, please feel free to share your thoughts.

Feel free to fork this repository and adjust it to your needs, or use it as a template.

Thank you for reading, and I hope you find this setup as beneficial as I have.

Happy coding!