The Container

What is the Container?

FOF 3 is built around the concept of a dependency injection container, a.k.a. the Container. Each component has its own unique container instance for each section (frontend or backend) of the application.

FOF's Container is based on an extended version of Pimple 3. We chose to ship it in FOF rather than require you to install it through Composer since FOF is designed to be mass-distributed with user-installable components and we all know that Composer doesn't work well with shared hosts and end users who have no idea what SSH is.

The Container is responsible for giving you access to an array of FOF services. Each service is accessible as both an array element and an object property of the Container. For example both $container['input'] and $container->input refer to the same FOF30\Input\Input object. Type hints –compatible with phpStorm, Eclipse and NetBeans– are provided for accessing the services as properties but not for accessing the services.

The services currently provided are:

• appConfig. The configuration read from the fof.xml file

• blade. The Blade template engine compiler so that you can extend it.

• db. The database object. It works similar as JFactory::getDbo but you can configure and use a different database connection for your component – very useful if your component needs to talk to a non-Joomla! database!

• dispatcher. The component dispatcher.

• factory. The MVC object factory, used to create Controllers, Models, Views and so on. This is how FOF allows you to implement different levels of "magic" behaviour. You can specify a custom factory class in the factoryClass configuration parameter of the Container.

• filesystem. A simple interface to the most commonly used Joomla! filesystem API calls.

• input. The input object of your component which can diverge from Joomla!'s input.

• mediaVersion. A version query string parameter added to the URL of all media (CSS, JS, LESS) files loaded through the View. This includes media files included by XML forms.

• params. A service to get and set the component's parameters. More Details

• platform. Abstraction of core Joomla! API calls. This allows you to use FOF with different versions of Joomla! and even with Joomla! Framework applications. You can specify a custom platform class in the platformClass configuration parameter of the Container.

• renderer. The view renderer, used to output common HTML and render XML forms.

• saveScaffolding. Set to 1 to enable saving Scaffolding-generated XML forms and language strings. Set to 0 (default) to disable it.

• scaffolding. Set to 1 to enable Scaffolding. Set to 0 (default) to disable it.

• session. The JSession object, easily accessible.

• template. The view template helper, for internal use by FOF.

• transparentAuth. The transparent authentication object, used to configure transparent authentication for your component (allows you to implement a RESTful JSON API without much code)

• toolbar. The toolbar renderer for your component.

  Remember: the Container is the gateway to your component. As a rule of thumb, if you need to do something with your component always go through the Container.

Getting access to the Container

You can get access to your component's static container object instance with this simple snippet of code:

$container = FOF30\Container\Container::getInstance('com_foobar');

Even though this static method allows you to define values to pass directly to the container we strongly advise against it when you want to get the static container object instance of your component. Instead, use the fof.xml file to configure your component's Container. This way other Joomla! extensions –modules, plugins, other components– will be able to use a properly configured Container for your component without having to rely on passing the "right" values. Reduce, reuse, recycle: it's not just for garbage!

HMVC

The Container can also be used to implement HMVC (Hierarchical MVC). HMVC allows you to display a component's view from another extension, be it the same or a different component, a module, a plugin, you name it. It is a very powerful feature which promotes code reuse, i.e. DRY (Don't Repeat Yourself) code.

When dealing with HMVC you need to explictly state two important things to FOF when getting the Container:

• You want a temporary container instance
• You want to override the input variables

So, you need to do this:

FOF30\Container\Container::getInstance('com_foobar', array(
    'tempInstance' => true,
    'input' => array(
        'view' => 'foo',
        'task' => 'bar',
        'something' => 123
    )
))->dispatcher->dispatch();

Attention It is very important to use the 'tempInstance' => true array item. This tells FOF to create a new Container with a custom input object containing the values you've set up in the input array. If you forget to do that you'll get the default container of your component which is NOT what you want in HMVC!

The ->dispatcher->dispatch() part tells the container to give us the component's Dispatcher and dispatch the component. This returns the rendered HTML to the browser. If you want to do more advanced output and error handling use something like this:

try
{
    // Capture the output instead of pushing it to the browser
    @ob_start();
    
    // Render the other component's view
    FOF30\Container\Container::getInstance('com_foobar', array(
        'tempInstance' => true,
        'input' => array(
            'view' => 'foo',
            'task' => 'bar',
            'something' => 123
        )
    ))->dispatcher->dispatch();
    
    // Get the output...
    $content = ob_get_contents();
    // ...and close the output buffer
    ob_end_clean();
}
catch (\Exception $e)
{
    // Whoops! The component blew up. Close the output buffer...
    ob_end_clean();
    // ...and indicate that we have no content.
    $content = '';
    
    // Maybe do some more error handling here :)
}

// Display the content
echo $content;

Attention! It is perfectly possible that calling a component through HMVC will result in a redirection. In this case your page will immediately redirect.