aura / project-kernel
The shared kernel files for an Aura project.
Installs: 70 917
Dependents: 3
Suggesters: 0
Security: 0
Stars: 9
Watchers: 5
Forks: 10
Open Issues: 1
Requires (Dev)
- phpunit/phpunit: ^8.5
This package is auto-updated.
Last update: 2024-09-28 02:48:02 UTC
README
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:
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.