snicco / kernel
The core of the snicco framework
Requires
- php: ^7.4|^8.0
- psr/container: ^1.1
- snicco/str-arr: ^2.0
- webimpress/safe-writer: ^2.2
- webmozart/assert: ^1.10
Requires (Dev)
- phpunit/phpunit: ^9.5.13
- snicco/pimple-bridge: ^2.0
Conflicts
- snicco/better-wp-api: <2.0.0-beta.9
- snicco/better-wp-cache: <2.0.0-beta.9
- snicco/better-wp-cache-bundle: <2.0.0-beta.9
- snicco/better-wp-cli: <2.0.0-beta.9
- snicco/better-wp-cli-testing: <2.0.0-beta.9
- snicco/better-wp-hooks: <2.0.0-beta.9
- snicco/better-wp-hooks-bundle: <2.0.0-beta.9
- snicco/better-wp-mail: <2.0.0-beta.9
- snicco/better-wp-mail-bundle: <2.0.0-beta.9
- snicco/better-wp-mail-testing: <2.0.0-beta.9
- snicco/better-wpdb: <2.0.0-beta.9
- snicco/better-wpdb-bundle: <2.0.0-beta.9
- snicco/blade-bridge: <2.0.0-beta.9
- snicco/blade-bundle: <2.0.0-beta.9
- snicco/content-negotiation-middleware: <2.0.0-beta.9
- snicco/debug-bundle: <2.0.0-beta.9
- snicco/default-headers-middleware: <2.0.0-beta.9
- snicco/eloquent: <2.0.0-beta.9
- snicco/encryption-bundle: <2.0.0-beta.9
- snicco/event-dispatcher: <2.0.0-beta.9
- snicco/event-dispatcher-testing: <2.0.0-beta.9
- snicco/guests-only-middleware: <1.0.0
- snicco/http-routing: <2.0.0-beta.9
- snicco/http-routing-bundle: <2.0.0-beta.9
- snicco/http-routing-testing: <2.0.0-beta.9
- snicco/https-only-middleware: <2.0.0-beta.9
- snicco/illuminate-container-bridge: <2.0.0-beta.9
- snicco/kernel-testing: <2.0.0-beta.9
- snicco/method-override-middleware: <2.0.0-beta.9
- snicco/minimal-logger: <2.0.0-beta.9
- snicco/must-match-route-middleware: <2.0.0-beta.9
- snicco/no-robots-middleware: <2.0.0-beta.9
- snicco/open-redirect-protection-middleware: <2.0.0-beta.9
- snicco/payload-middleware: <2.0.0-beta.9
- snicco/pimple-bridge: <2.0.0-beta.9
- snicco/psr7-error-handler: <2.0.0-beta.9
- snicco/redirect-middleware: <2.0.0-beta.9
- snicco/session: <2.0.0-beta.9
- snicco/session-bundle: <2.0.0-beta.9
- snicco/session-psr16-bridge: <2.0.0-beta.9
- snicco/session-testing: <2.0.0-beta.9
- snicco/session-wp-bridge: <2.0.0-beta.9
- snicco/share-cookies-middleware: <2.0.0-beta.9
- snicco/signed-url: <2.0.0-beta.9
- snicco/signed-url-psr15-bridge: <2.0.0-beta.9
- snicco/signed-url-psr16-bridge: <2.0.0-beta.9
- snicco/signed-url-testing: <2.0.0-beta.9
- snicco/signed-url-wp-bridge: <2.0.0-beta.9
- snicco/templating: <2.0.0-beta.9
- snicco/templating-bundle: <2.0.0-beta.9
- snicco/testable-clock: <2.0.0-beta.9
- snicco/testing-bundle: <2.0.0-beta.9
- snicco/trailing-slash-middleware: <2.0.0-beta.9
- snicco/wp-auth-only-middleware: <2.0.0-beta.9
- snicco/wp-capability-middleware: <2.0.0-beta.9
- snicco/wp-capapility-middleware: <1.0.0
- snicco/wp-guests-only-middleware: <2.0.0-beta.9
- snicco/wp-nonce-middleware: <2.0.0-beta.9
- dev-master
- v2.0.0-beta.9
- v2.0.0-beta.8
- v2.0.0-beta.7
- v2.0.0-beta.6
- v2.0.0-beta.5
- v2.0.0-beta.4
- v2.0.0-beta.3
- v2.0.0-beta.2
- v2.0.0-beta.1
- v1.10.1
- v1.10.0
- v1.9.1
- v1.9.0
- v1.8.1
- v1.8.0
- v1.7.0
- v1.6.2
- v1.6.1
- v1.6.0
- v1.5.0
- v1.4.2
- v1.4.1
- v1.4.0
- v1.3.0
- v1.2.1
- v1.2.0
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.2
- v1.0.1
- v1.0.0
- dev-beta
This package is auto-updated.
Last update: 2024-11-07 14:45:38 UTC
README
The Kernel component of the Snicco project helps to bootstrap an application that uses a plugin architecture.
Table of contents
Installation
composer require snicco/kernel
Definitions
Kernel
The Kernel
class helps to load and cache configuration files, define services in a
dependency-injection container and bootstrap an application in a controlled manner using any number
of bootstrappers and bundles.
Bootstrappers
A bootstrapper can be any class that implements the Bootstrapper
interface:
A bootstrapper is a class responsible for "bootstrapping" one cohesive part of an application.
"Bootstrapping" could mean, for example: registering definitions in a dependency injection container or creating event listeners.
Bootstrappers are the central place to configure the application.
interface Bootstrapper { public function shouldRun(Environment $env): bool; public function configure(WritableConfig $config, Kernel $kernel): void; public function register(Kernel $kernel): void; public function bootstrap(Kernel $kernel): void; }
Bundles
A bundle can be any class that implements the Bundle
interface. The Bundle
interface extends the Bootstrapper
interface.
interface Bundle extends Bootstrapper { public function alias(): string; }
The difference between a bundle and a bootstrapper is that a bundle is meant to be publicly distributed, while a bootstrapper is internal to a specific application.
Bundles are aware of other bundles that are used by the same Kernel
instance.
Environment
A Kernel
always needs an environment to run in.
The following environments are possible:
- production
- staging
- development
- testing
- debug (in combination with any non production env.)
use Snicco\Component\Kernel\ValueObject\Environment; $environment = Environment::prod() $environment = Environment::testing() $environment = Environment::staging() $environment = Environment::dev() $environment = Environment::fromString(getenv('APP_ENV'));
Directories
A Kernel
always needs a Directories
value object that
defines the location of:
- the base directory of the application.
- the config directory of the application.
- the log directory of the application.
- the cache directory of the application.
use Snicco\Component\Kernel\ValueObject\Directories; $directories = new Directories( __DIR__, // base directory, __DIR__ .'/config', // config directory __DIR__. '/var/cache', // cache directory __DIR__ . '/var/log' // log directory ) // This is equivalent to the above: $directories = Directories::fromDefaults(__DIR__);
Dependency injection container
The Kernel
needs an instance of DIContainer
, which is an abstract class
that extends the
PSR-11 container interface.
There are currently two implementations of this interface:
snicco/pimple-bridge
, usingpimple/pimple
snicco/illuminate-container-bridge
, usingilluminate/container
You can also provide your own implementation and test it using the test cases
in snicco/kernel-testing
.
The DIContainer
class is an abstraction meant to be used inside bundles.
Since bundles are distributed packages, they can't rely on a specific dependency-injection container. However, the
PSR-11 container interface only defines how to fetch services from the container, not how to define them, which is
why the DIContainer
abstraction is used.
Configuration files
Every .php
file inside the config directory will be used to create
a Config
instance once the kernel is booted.
The following configuration inside your config directory:
// config/routing.php return [ 'route_directories' => [ /* */ ] 'features' => [ 'feature-a' => true, ] ]
would be loaded into the config instance like so:
$config->get('routing'); $config->get('routing.route_directories'); $config->get('routing.features.feature-a');
The kernel.php
configuration file is reserved since this is where bundles
and bootstrappers
are defined:
// config/kernel.php use Snicco\Component\Kernel\ValueObject\Environment; return [ 'bundles' => [ // These bundles will be used in all environments Environment::ALL => [ RoutingBundle::class ], // These bundles will only be used if the kernel environment is dev. Environment::DEV => [ ProfilingBundle::class ], ], // Bootstrappers are always used in all environments. 'bootstrappers' => [ BootstrapperA::class ] ]
Usage
Creating a kernel
use Snicco\Component\Kernel\Kernel; $container = /* */ $env = /* */ $directories = /* */ $kernel = new Kernel( $container, $directories, $env );
Booting a kernel
There is a difference in what happens when the kernel is booted based on the current environment and whether the configuration is already cached.
$kernel = /* */ $kernel->boot();
Booting an "uncached" kernel:
- All configuration files inside the config directory will be loaded from disk to create an instance
of
WritableConfig
. - The bundles and bootstrappers are read from the
kernel.php
configuration file. - The
shouldRun()
method is called for all bundles. - The
shouldRun()
method is called for all bootstrappers. - The
configure()
method is called for all bundles. - The
configure()
method is called for all bootstrappers. - The
WritableConfig
is combined into one file and written to the cache directory (if the current environment is production/staging). - The
register()
method is called for all bundles. - The
register()
method is called for all bootstrappers. - The
boot()
method is called for all bundles that are defined in thekernel.php
configuration file. - The
boot()
method is called for all bootstrappers that are defined in thekernel.php
configuration file. - The
DIContainer
is locked and no further modifications can be made.
Booting a "cached" kernel:
- The cached configuration file is loaded from disk and a
ReadOnlyConfig
is created. - The bundles and bootstrappers are read from the
ReadOnlyConfig
. - The
shouldRun()
method is called for all bundles. - The
shouldRun()
method is called for all bootstrappers. - The
register()
method is called for all bundles. - The
register()
method is called for all bootstrappers. - The
boot()
method is called for all bundles. - The
boot()
method is called for all bootstrappers. - The
DIContainer
is locked and no further modifications can be made.
-
The
configure()
method should be used to extend the loaded configuration with default values and to validate the configuration for the specific bundle. Theconfigure()
method is only called if the configuration is not cached yet. -
The
register()
method should only be used to bind service definitions into theDIContainer
. -
The
boot()
method should be used to fetch services from theDIContainer
and to configure them (if necessary). The container is already locked at this point and further modifications of service definitions are not possible. Attempting to modify the container from inside theboot()
method of a bundle or bootstrapper will throw aContainerIsLocked
exception.
Each of these methods is always called first on all bundles, then on all bootstrappers.
This allows bootstrappers to customize behaviour of bundles (if desired).
Lifecycle hooks
There are two extension points in the booting process of the kernel.
- After the configuration was loaded from disk (only if the configuration is not cached already). This is the last opportunity to modify the configuration before its cached.
- After all bundles and bootstrappers have been registered, but before they are booted. This is the last opportunity to change service definitions before the container is locked.
use Snicco\Component\Kernel\Configuration\WritableConfig;use Snicco\Component\Kernel\Kernel; $kernel = /* */ $kernel->afterConfigurationLoaded(function (WritableConfig $config) { if( $some_condition ) { $config->set('routing.features.feature-a', true); } }); $kernel->afterRegister(function (Kernel $kernel) { if($some_condition) { $kernel->container()->instance(LoggerInterface::class, new TestLogger()); } }); $kernel->boot();
Using the booted kernel
After the container is booted, services provided by all bundles can be safely fetched.
An example:
use Nyholm\Psr7Server\ServerRequestCreator; $kernel->boot(); $server_request_creator = $kernel->container()->make(ServerRequestCreator::class); $http_kernel = $kernel->container()->make(HttpKernel::class); $response = $http_kernel->handle($server_request_creator->fromGlobals());
Contributing
This repository is a read-only split of the development repo of the Snicco project.
This is how you can contribute.
Reporting issues and sending pull requests
Please report issues in the Snicco monorepo.
Security
If you discover a security vulnerability, please follow our disclosure procedure.