decodelabs/genesis

Universal bootstrapping framework

v0.9.0 2024-08-21 22:11 UTC

README

PHP from Packagist Latest Version Total Downloads GitHub Workflow Status PHPStan License

Universal bootstrapping framework for PHP applications

Genesis provides everything you need to bootstrap your application at runtime. Take the guesswork out of how best to structure the lowest level code in your framework and app.

Get news and updates on the DecodeLabs blog.

Installation

Install via Composer:

composer require decodelabs/genesis

Usage

Importing

Genesis uses Veneer to provide a unified frontage under DecodeLabs\Genesis. You can access all the primary functionality via this static frontage without compromising testing and dependency injection.

Hub

Genesis requires consumers of the library to implement a number of interfaces to represent important parts of the bootstrap process. With these classes in place, it is then able to provide a unified, dependable bootstrap process for all environments.

Most important is the Hub interface:

namespace DecodeLabs\Genesis;

use DecodeLabs\Genesis\Loader\Stack as StackLoader;
use DecodeLabs\Genesis\Environment\Config as EnvConfig;
use DecodeLabs\Genesis\Build\Manifest as BuildManifest;

interface Hub
{
    public function getApplicationPath(): string;
    public function getLocalDataPath(): string;
    public function getSharedDataPath(): string;
    public function getApplicationName(): string;
    public function initializeLoaders(StackLoader $loader): void;
    public function loadBuild(): Build;
    public function loadEnvironmentConfig(): EnvConfig;
    public function initializePlatform(): void;
    public function loadKernel(): Kernel;
    public function getBuildManifest(): ?BuildManifest;
}

The hub provides access to all of the critical information and structures needed to get the app running. Once instantiated, the hub can be accessed via the Genesis Veneer frontage:

$appPath = Genesis::$hub->getApplicationPath();

Kernel

The Kernel is the executor of your app - the Hub sets it up and then the Kernel runs it.

interface Kernel
{
    public function initialize(): void;
    public function getMode(): string;

    public function run(): void;
    public function shutdown(): void;
}

Like the Hub, the Kernel can be accessed like so:

$runMode = Genesis::$kernel->getMode();

Build and environment

During the setup phase, the Hub will provide information and configuration for the Environment and Build objects:

if(Genesis::$environment->isDevelopment()) {
    // Do fun dev stuff
}

$envName = Genesis::$environment->getName();
$rootPath = Genesis::$build->getPath();

if(Genesis::$build->isCompiled()) {
    // We've compiled a build
}

// Get time of build to use in URLs as a cache buster
$cacheBuster = Genesis::$build->getCacheBuster();

Running the app

With the necessary interfaces in place, your entry file just requires the following:

// Composer autoload
require_once 'path/to/vendor/autoload.php';

use DecodeLabs\Genesis;
use My\Hub;

Genesis::run(Hub::class, [
    // any options your custom hub needs
]);

Compiled builds

Genesis supports an advanced build compilation process which can be used for isolating active runtime code from the source of your application. This is especially useful for legacy frameworks that can't easily be deployed using a third party automated deployment system.

Compiled builds are a complex topic due to the necessity of locating the correct build folder before loading any other code and needing to seamlessly deploy updates without unwittingly mixing different versions of libraries during execution.

Full details of how to work with compiled builds can be found here.

Licensing

Genesis is licensed under the MIT License. See LICENSE for the full license text.