Aura.Project_Kernel

This kernel package exists as a base for Aura.Cli_Kernel, Aura.Web_Kernel, and other future kernel types.

Foreword

Requirements

This kernel requires PHP 7.2 or later; we recommend using the latest available version of PHP as a matter of principle. If you are interested in using this package for older PHP versions, use version 2.x for PHP 5.3+.

Unlike Aura library packages, this kernel package has userland dependencies, which themselves may have other dependencies:

• aura/di
• psr/log

Installation

This kernel is installable and autoloadable via Composer with the following require element in your composer.json file:

"require": {
    "aura/project-kernel": "dev-develop-2"
}

Alternatively, download or clone this repository, then require or include its autoload.php file.

Tests

This kernel has 100% code coverage with PHPUnit. To run the unit tests at the command line, issue composer install and then composer test at the package root. This requires Composer to be available as composer.

PSR Compliance

This kernel attempts to comply with PSR-1, PSR-2, and PSR-4. If you notice compliance oversights, please send a patch via pull request.

Community

To ask questions, provide feedback, or otherwise communicate with the Aura community, please join our Google Group, follow @auraphp on Twitter, or chat with us on #auraphp on Freenode.

Services

This package defines the following services in the Container:

• aura/project-kernel:logger: an instance of Psr\Log\NullLogger

Note that service definitions set at the kernel level may be reset at the project level.

Configuration

Although configuration is a project-level concern, each Aura kernel and project handles it in the same way. Thus, we provide config documentation here to reduce repetition.

N.b.: The examples throughout this document are for Aura\Web_Project; replace that with Aura\Cli_Project or Aura\Framework_Project as needed.

Setting The Config Mode

Set the configuration mode using $_ENV['AURA_CONFIG_MODE'], either via a server variable or the project-level config/_env.php file. Each Aura project comes with dev (local development), test (shared testing/staging), and prod (production) modes pre-defined.

Config File Location

Project-level configuration files are located in the project-level config/ directory. Each configuration file is a class that extends Aura\Di\Config, and represents a configuration mode. Each configuration class has two methods:

• define(), which allows you to define params, setters, and services in the project Container; and

• modify(), which allows you to pull objects out of the Container for programmatic modification. (This happens after the Container is locked, so you cannot add new services or change params and setters here.)

The two-stage configuration system loads all the configuration classes in order by library, kernel, and project, then runs all the define() methods, locks the container, and finally runs all the modify() methods.

Mapping Config Modes To Classes

The config modes are mapped to their related config class files via the project-level composer.json file in the extra:aura:config block. The entry key is the config mode, and the entry value is the class to use for that mode.

{
    "autoload": {
        "psr-0": {
            "": "src/"
        },
        "psr-4": {
            "Aura\\Web_Project\\_Config\\": "config/"
        }
    },
    "extra": {
        "aura": {
            "type": "project",
            "config": {
                "common": "Aura\\Web_Project\\_Config\\Common",
                "dev": "Aura\\Web_Project\\_Config\\Dev",
                "test": "Aura\\Web_Project\\_Config\\Test",
                "prod": "Aura\\Web_Project\\_Config\\Prod"
            }
        }
    }
}

Config classes are autoloaded via a PSR-4 entry for that project namespace.

The "common" config class is always loaded regardless of the actual config mode. For example, if the config mode is dev, first the Common class is loaded, and then the Dev class.

Changing Config Settings

First, open the config file for the related config mode. To change configuration params, setters, and services, edit the define() method. To programmatically change a service after all definitions are complete, edit the modify() method.

Adding A Config Mode

If you want to add a new configuration mode, say qa, you need to do three things.

First, create a config class for it in config/:

<?php
namespace Aura\Web_Project\_Config;

use Aura\Di\Config;
use Aura\Di\Container;

class Qa extends Config
{
    public function define(Container $di)
    {
        // define params, setters, and services here
    }

    public function modify(Container $di)
    {
        // modify existing services here
    }
}
?>

Next, edit the project-level composer.json file to add the new config mode with its related class:

{
    "extra": {
        "aura": {
            "type": "project",
            "config": {
                "common": "Aura\\Web_Project\\_Config\\Common",
                "dev": "Aura\\Web_Project\\_Config\\Dev",
                "test": "Aura\\Web_Project\\_Config\\Test",
                "prod": "Aura\\Web_Project\\_Config\\Prod",
                "qa": "Aura\\Web_Project\\_Config\\Qa"
            }
        }
    }
}

Finally, run composer update so that Composer makes the necessary changes to the autoloader system.