Autoconfig extensions

Autoconfig is a feature of ICanBoogie that automatically generates a single configuration file from various sources to bootstrap the application. Extensions can participate in that process to provide additional features.

Creating an extension

An Autoconfig extension is created by extending the ExtensionAbstract class and implementing the alter_schema(), synthesize(), and render() methods. Most likely, the extension will require a new property in the autoconfig fragments, it needs to be specified with the alter_schema() method so that the schema can be validated. Autoconfig is very strict with its schema.

The following example is an excerpt of the extension used by icanboogie/module to alter the autoconfig with the configuration files defined by the application's modules. The extension also adds an autoconfig property that can be used to specify the custom modules used by the application.

<?php

namespace ICanBoogie\Module\Autoconfig;

use ICanBoogie\Autoconfig\Autoconfig;
use ICanBoogie\Autoconfig\ExtensionAbstract;

/**
 * Autoconfig extension to handle modules, their config and locale messages.
 */
class ModuleExtension extends ExtensionAbstract
{
    const TYPE_MODULE = "icanboogie-module";
    const OPTION_MODULES_PATH = 'modules-path';

    /**
     * @var array
     */
    private $modules_directories;

    /**
     * @inheritdoc
     */
    public function alter_schema(callable $set_property)
    {
        $set_property(self::OPTION_MODULES_PATH, [

            'type' => "string",
            'description' => "(root-only) Path to application's custom modules.",
            'required' => false,

        ]);
    }

    /**
     * @inheritdoc
     */
    public function synthesize(array &$autoconfig)
    {
        $modules_directories = $this->modules_directories = $this->collect_modules_directories();

        foreach ($modules_directories as $pathname)
        {
            if (is_dir("$pathname/config"))
            {
                $autoconfig[Autoconfig::CONFIG_PATH][] = [

                    $this->findShortestPathCode("$pathname/config"),
                    Autoconfig::CONFIG_WEIGHT_MODULE

                ];
            }

            // …
        }
    }

    /**
     * @inheritdoc
     */
    public function render()
    {
        return $this->render_array_entry(
            ModuleAutoconfig::MODULES,
            $this->modules_directories,
            function ($directory) 
            {
                return $this->findShortestPathCode($directory);
            }
        );
    }

    /**
     * @return array
     */
    private function collect_modules_directories()
    {
        // …
    }
}

Registering an extension

Once your extension is created you need to register it using the composer.json file of your application or package.

The following example demonstrates how to register a ModuleExtension, using the extra section:

    "extra": {
        "icanboogie": {
            "autoconfig-extension": "ICanBoogie\\Module\\Autoconfig\\ModuleExtension",
        }
    }

tl;dr

With Autoconfig extensions, packages can participate in the Autoconfig process to provide additional features.