README

A single shared source of truth for your PHP apps

Monarch provides a single shared source of truth for your PHP applications. It allow commonly referenced paths and items to be centralised into a predictable location, making it easier to manage accessing that data from code that needs to maintain minimal coupling to the rest of the application.

It acts as the top level oversight for your entire application space and acts as an orchestrator for your application's container and services within.

Monarch works in tandem with Kingdom - it manages the active Kingdom instance that in turn contains all of your application's services.

Installation

Install via Composer:

composer require decodelabs/monarch

Usage

Monarch should be populated in your bootstrap otherwise it will use reasonable defaults where possible. If you use Genesis to bootstrap your application, Monarch will be automatically populated for you.

For example:

use DecodeLabs\Monarch;
$paths = Monarch::getPaths();

$paths->root = '/var/www/my-cool-app';
$paths->run = '/var/www/my-cool-app/dist';
$paths->localData = '/var/www/my-cool-app/data/local';
$paths->sharedData = '/var/www/my-cool-app/data/shared';

Monarch::setKingdom(new MyKingdom());

Path aliasing

Monarch allows you to define aliases for commonly used paths. This is useful for avoiding hardcoded paths in your codebase. @root and @run are automatically defined for you, but you can define your own aliases as needed.

$paths->alias('@components', '@root/components');
$paths->alias('@assets', '@root/assets');

You can then use these aliases in your code:

$path = $paths->resolve('@components/MyComponent.php');
// /var/www/my-cool-app/components/MyComponent.php

Services

Monarch provides a simple way to access Kingdomservices from your application. Services must implement the Kingdom Service interface and may provide the ability to self-instantiate.

$service = Monarch::getService(MyService::class);

This method is a simple wrapper around the getService() method of the active Kingdom instance. It will only work if you supply an instance of the Kingdom interface in your bootstrap.

While this method is useful for quick access to services, it is not recommended for regular use as it is essentially an implementation of the Service Locator pattern. It works, but is inflexible and can lead to tight coupling between your code and the container.

Instead, the Kingdom instance provided to Monarch is also made available to Slingshot which can then be used to automatically inject services into your code.

Many common DecodeLabs libraries use Slingshot in their architecture and allow arbitrary constructor parameters to be handled seamlessly.

Licensing

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

decodelabs / monarch

Maintainers

Details