Managing instances programmatically
As an application developer, you will use the Mouf user interface to edit instances in your application. However, as a package developer, you will need to edit/create instances programmatically. For instance, you may want to provide an install process that creates instances (or a user interface in Mouf that creates/modifies instances...).
For this you will need to access the MoufContainer
. MoufContainer
is the class used to add/edit instances of your application.
MoufContainer
is compatible with ContainerInterop,
the DIC compatibility standard. In particular, it implements the ContainerInterface
and the delegate lookup feature.Getting a MoufContainer instance
Getting the default container of your Mouf application
The first thing you want to do is to get an instance of MoufContainer
.
If you are in the context of your application, use:
$moufContainer = MoufManager::getMoufManager()->getContainer();
If you are in the context of Mouf (if you are developing a controller that extends the Mouf interface), use:
$moufContainer = MoufManager::getHiddenMoufManager()->getContainer();
Mouf is developed using Mouf (yes, this is recursive). If you use the
MoufManager::getMoufManager()->getContainer()
method inside the Mouf context, you will get the instances used
by Mouf, not your instances.
Creating a new container
Sometimes, you don't want to access the default container that comes with your Mouf application. Instead, you might want create a new container.
A valid MoufContainer comes in 2 parts:
- a configuration file (that contains the list of instances) This file is usually called
instances.php
- a class that extends
Mouf\MoufContainer
To build the container, you use:
use Mouf\MoufContainer;
// createContainer takes 3 arguments:
// - the path to the configuration file
// - the name of the class to be generated
// - (optional): the path to the class
$container = MoufContainer::createContainer('path/to/instances.php', 'MyProject\\Container', 'src/MyProject/Container/php');
// A call to "write" will generate both files.
$container->write();
Once the container has been generated, you can get an instance of the container by simply calling:
$container = new MyProject\Container();
You can optionally pass a delegate lookup container as an argument to the container:
$container = new MyProject\Container($rootContainer);
Creating a new instance
In order to create a new instance, use the createInstance
method:
// Creates an anonymous instance for class MyNamespace\MyClass
$instanceDescriptor = $moufContainer->createInstance("MyNamespace\\MyClass");
// Let's give the instance a name:
$instanceDescriptor->setName('myInstance');
// Finally, save the instance:
$moufContainer->write();
As you noticed, the createInstance
method returns an "instance descriptor". This is an object that
describes the instance.
Each time you modify an instance or create a new instance, changes will only be saved once you call
the $moufContainer->write()
method.
Getting an instance descriptor from the MoufManager
Use the getInstanceDescriptor()
method to retrieve an instance descriptor.
$instanceDescriptor = $moufContainer->getInstanceDescriptor('myInstance');
Setting a property in an instance
Injecting a primitive type
// Filling a constructor argument
$instanceDescriptor->getConstructorArgumentProperty('parameterName')->setValue('aValue');
// Filling a setter
$instanceDescriptor->getSetterProperty('setterName')->setValue('aValue');
// Filling a public field
$instanceDescriptor->getPublicFieldProperty('myField')->setValue('aValue');
Injecting another instance
If you want to inject another instance, pass an instance descriptor to the setValue
method.
For instance:
$anotherInstanceDescriptor = $moufContainer->getInstanceDescriptor('anotherInstance');
$instanceDescriptor->getConstructorArgumentProperty('parameterName')->setValue(anotherInstanceDescriptor);
Injecting a constant in a property
define('MY_CONSTANT', 42);
$instanceDescriptor->getConstructorArgumentProperty('parameterName')
->setOrigin("constant")
->setValue("MY_CONSTANT");
Injecting PHP code in a property
PHP code is passed to the setValue
method. It must contain a return
statement.
$instanceDescriptor->getConstructorArgumentProperty('parameterName')
->setOrigin("php")
->setValue("return [ 42 => 'aValue' ]");
Creating an instance defined by PHP code
You can also declare an instance completely from PHP code.
// Creates an anonymous instance by PHP code
$instanceDescriptor = $moufContainer->createInstanceByCode();
// Let's give the instance a name:
$instanceDescriptor->setName('myInstance');
// Sets the PHP code (as a string). It must contain a `return` statement.
$instanceDescriptor->setCode('return MyObject::getInstance();');
// Finally, save the instance:
$moufContainer->write();
Utility functions
Fairly often, when you write install scripts, you will need to get an instance by its name, or create that instance of that instance does not exist yet.
There is an utility function that help you do this:
use Mouf\Actions\InstallUtils;
$instanceDescriptor = InstallUtils::getOrCreateInstance($instanceName, $className, $moufContainer);
Exporting instances
When you write complex install scripts with dozens of instances, it can be quite tedious to write the install script by yourself. Hopefully, Mouf comes with Package builder: a tool that can help you export a set of instances and build the PHP code that generates the instances for you.
Found a typo? Something is wrong in this documentation? Just fork and edit it!