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.

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.

Check out "Package builder" >

Found a typo? Something is wrong in this documentation? Just fork and edit it!