Compile the container

[mnapoli]

3rd try at compiling the container (after #133 and #149).

This will bring massive performance improvements in production. To learn more I have included below the TODO list the updated documentation for the "Performances" section.

TODO :

• compile most definitions:
  • values
  • string expressions
  • environment variables
  • aliases
  • arrays
  • array extensions
  • objects
  • lazy objects
  • sub-definitions
• cover with tests definitions that are not compiled yet:
  • factories
  • decorators
  • wildcards
• get()
  • basic implementation
  • don't skip singleton entries (already resolved)
  • circular dependencies
• has()
• make()
• injectOn()
• call()
• delegate containers
• all integration tests should cover the compiled container too
• test the compiler
• handle set() of already compiled entries
• define the file name to store the compiled container (will allow to use several containers in the same process)
• remove the cache completely (will be unnecessary)
• benchmarks
• documentation
• changelog

---

Compiling the container

PHP-DI performs two tasks that can be expensive:

• reading definitions from your configuration, from autowiring or from annotations
• resolving those definitions to create your services

In order to avoid those two tasks, the container can be compiled into PHP code optimized especially for your configuration and your classes.

Setup

Compiling the container is as easy as calling the compile() method on the container builder:

$containerBuilder = new \DI\ContainerBuilder();
$containerBuilder->compile(__DIR__ . '/var/cache/CompiledContainer.php');

// […]

$container = $containerBuilder->build();

The compile() method takes a single argument: the name of a file in which to store the container.

Please note that the file name will also be the name of the generated PHP class. Because of that the filename you specify must also be a valid class name. For example:

• var/cache/CompiledContainer.php: valid
• var/cache/compiled-container.php: invalid since compiled-container is not a valid PHP class name

Deployment in production

When a container is configured to be compiled, it will be compiled once and never be regenerated again. That allows for maximum performances in production.

When you deploy new versions of your code to production you must delete the generated file to ensure that the container is re-compiled.

If your production handles a lot of traffic you may also want to generate the compiled container before the new version of your code goes live. That phase is known as the "warmup" phase. To do this, simply create the container (call $containerBuilder->build()) during your deployment step and the compiled container will be created.

Development environment

Do not compile the container in a development environment, else all the changes you make to the definitions (annotations, configuration files, etc.) will not be taken into account. Here is an example of what you can do:

$containerBuilder = new \DI\ContainerBuilder();
if (/* is production */) {
    $containerBuilder->compile(__DIR__ . '/var/cache/CompiledContainer.php');
}

As a side note, do not confuse "development environment" with your automated tests. You are encouraged to run your automated tests (PHPUnit, Behat, etc.) on a system as close to your production setup (which means with the container compiled).

Optimizing for compilation

As you can read in the "How it works" section, PHP-DI will take all the definitions it can find and compile them. That means that definitions like autowired classes that are not listed in the configuration cannot be compiled since PHP-DI doesn't know about them.

If you want to optimize performances to a maximum in exchange for more verbosity, you can let PHP-DI know about all the autowired classes by listing them in definition files:

return [
    // ... (your definitions)

    UserController::class => autowire(),
    BlogController::class => autowire(),
    ProductController::class => autowire(),
    // ...
];

You do not need to configure them (autowiring will still take care of that) but at least now PHP-DI will know about those classes and will compile their definitions.

Currently PHP-DI does not traverse directories to find autowired or annotated classes automatically. It also does not resolve wildcard definitions when it is compiled.

Please note that the following definitions are not compiled (yet):

• factory definitions
• decorator definitions
• wildcard definitions

Those definitions will still work perfectly, they will simply not get a performance boost when using a compiled container.

How it works

PHP-DI will read definitions from your configuration. When the container is compiled, PHP code will be generated based on those definitions.

For example let's take the definition for creating an object:

return [
    'Logger' => DI\create()
        ->constructor('/tmp/app.log')
        ->method('setLevel', 'warning'),
];

This definition will be compiled to PHP code similar to this:

$object = new Logger('/tmp/app.log');
$object->setLevel('warning');
return $object;

All the compiled definitions will be dumped into a PHP class (the compiled container) which will be written to a file (for example CompiledContainer.php).

At runtime, the container builder will see that the file CompiledContainer.php exists and will load it (instead of loading the definition files). That PHP file may contain a lot of code but PHP's opcode cache will cache that class in memory (remember to use opcache in production). When a definition needs to be resolved, PHP-DI will simply execute the compiled code and return the created instance.

[sagikazarmark]

Nice!

When does the actual compilation happen? When you call build or compile?

I am asking because I want to create Docker images with compiled containers and I don't want to compile them runtime.

[mnapoli]

@sagikazarmark when ->build() is called

[mnapoli]

@sagikazarmark By the way I'll probably be tagging an alpha release today, testing this new version (which comes with a big refactoring) would be most welcome :)

[sagikazarmark]

Will do here: https://github.com/nofw/nofw

[sagikazarmark]

BTW this is how I built the cache so far, I guess compilation will be less hacky: https://github.com/nofw/nofw/blob/master/bin/cache#L9

[mnapoli]

Yes I hope this will be useful for you! I've tagged a new alpha, you can test it right away (feel free to open issues if necessary): https://github.com/PHP-DI/PHP-DI/releases/tag/6.0.0-alpha2

The documentation: https://github.com/PHP-DI/PHP-DI/blob/master/doc/performances.md

[juliangut]

@mnapoli I've an issue with the nomenclature of compile. IMHO the name misleads as compile is an action (verb) while the method does not really compile anything but sets the compiled file path (and name). Thus I'd suggest to rename it to setCompilationPath instead (more on this below)

Another problem I see as per documentation:

Please note that the file name will also be the name of the generated PHP class. Because of that the filename you specify must also be a valid class name

Wouldn't it be better just to use a single file name (CompiledContainer.php is just perfect) and let the user set the path only? (this plays better with my previous suggestion of setCompilationPath)

[sagikazarmark]

Hm, I kinda agree with the compile name thing.

Not sure about the path one.

[mnapoli]

@juliangut & @sagikazarmark thanks I've opened #506

Sorry for not answering sooner, I was at a conference these last days.