Aura for PHP

2.2.12. Migrating

This document helps to upgrade users moving from 3.x to 4.x. Below you can also (still) find the upgrade guide for people upgrading from 2.x to 3.x.

2.2.12.1. Migrating from 3.x to 4.x

Aura.Di 4.x is largely similar to 3.x, but there are some backwards-compatibility breaks, as well as some new features.

2.2.12.1.1. Dropped PHP 7.1 and lower, no HHVM

Make sure you use the correct PHP version. This library uses the object type-hint and therefore requires PHP 7.2+. The support for HHVM is dropped.

2.2.12.1.2. Type-hinting

All classes are now using type hinting for method arguments and return types, including the void return type. This means if you have extended or implemented one of the library classes in your code, you will have to update the signatures of your extended/implemented methods to match the new signatures.

For most users this involves only updating classes implementing the ContainerConfigInterface.

2.2.12.1.3. InjectionFactory::newInstance()

Aura\Di\Injection\InjectionFactory::newInstance() now requires an instance of Aura\Di\Resolver\Blueprint to be passed as the parameter, instead of the former classname, parameter array and setter array.

2.2.12.1.4. Container Interop

From version 4.x the library will implement the official container standard interface (PSR 11) instead of the container-interop interface.

2.2.12.1.5. Dropped features

LazyRequire and LazyInclude could be constructed with a lazy object instead of a filename. This was probably only used for testing purposes (it was not included in any docs) but is included here in case someone is actually using this.

2.2.12.2. Migrating from 2.x to 3.x

Aura.Di 3.x is largely similar to 2.x, but there are some backwards-compatibility breaks, as well as some new features.

2.2.12.2.1. BC Breaks

2.2.12.2.1.1. Instantiation

The way the container is instantiated has been changed from this ...

use Aura\Di\Container;
use Aura\Di\Factory;
use Aura\Di\ContainerBuilder;

$di = new Container(new Factory);

// or

$container_builder = new ContainerBuilder();
$di = $container_builder->newInstance(
    array(),
    array(),
    $auto_resolve = false
);

... to this:

use Aura\Di\ContainerBuilder;

$container_builder = new ContainerBuilder();

// use the builder to create and configure a container
// using an array of ContainerConfig classes
$di = $container_builder->newConfiguredInstance([
    'Aura\Cli\_Config\Common',
    'Aura\Router\_Config\Common',
    'Aura\Web\_Config\Common',
]);

2.2.12.2.1.2. setter vs setters

Use of $di->setter in 2.x is now $di->setters in 3.x. Please note there is an additional s in the end.

2.2.12.2.1.3. Automatic Locking

The container now calls lock() automatically when you call get() or newInstance(), so make sure everything is lazy-loaded, or else you will run into something like cannot modify container when locked.

2.2.12.2.1.4. Config vs ContainerConfig

Aura\Di\Config in 2.x is now Aura\Di\ContainerConfig in 3.x.

2.2.12.2.2. Features

2.2.12.2.2.1. lazyGetCall()

Example taken from Radar:

$di->params['Radar\Adr\Handler\RoutingHandler']['matcher'] = $di->lazyGetCall('radar/adr:router', 'getMatcher');

Here the value assigned to matcher is taken from the RouterContainer getMatcher() method.

2.2.12.2.2.2. Instance Factories

An instance factory creates multiple instances of the same class; refer the docs for more information.