PHPackages                             decodelabs/kingdom - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. decodelabs/kingdom

ActiveLibrary

decodelabs/kingdom
==================

Service container and management system

v0.2.0(8mo ago)04.2k120MITPHPPHP ^8.4CI passing

Since Aug 20Pushed 5mo agoCompare

[ Source](https://github.com/decodelabs/kingdom)[ Packagist](https://packagist.org/packages/decodelabs/kingdom)[ RSS](/packages/decodelabs-kingdom/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelog (3)Dependencies (3)Versions (5)Used By (20)

Kingdom
=======

[](#kingdom)

[![PHP from Packagist](https://camo.githubusercontent.com/321919ab2f434dee1dd9fd1ab741170bf4193e741ec6a06afb6db37c85574414/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6465636f64656c6162732f6b696e67646f6d3f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/kingdom)[![Latest Version](https://camo.githubusercontent.com/f4b40c732122ba9c7dd3f1ead2a9f1ce06cc767baf15bf094d1d0a6ad7a562c7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6465636f64656c6162732f6b696e67646f6d2e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/kingdom)[![Total Downloads](https://camo.githubusercontent.com/089fd00b1902975bdc526147bd339f1867f7dcad88ed957b4c6db23ee84a22fe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6465636f64656c6162732f6b696e67646f6d2e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/kingdom)[![GitHub Workflow Status](https://camo.githubusercontent.com/94f77b3cf52082f8eeb5232ccab6814a16758e7570d7d15d01ea4e520977bdce/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6465636f64656c6162732f6b696e67646f6d2f696e746567726174652e796d6c3f6272616e63683d646576656c6f70)](https://github.com/decodelabs/kingdom/actions/workflows/integrate.yml)[![PHPStan](https://camo.githubusercontent.com/e25c14ce011edabdd0fbd2e10415b41cc5d66ed11ef3e5b7edd074c5bdd35a2d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d656e61626c65642d3434434331312e7376673f6c6f6e6743616368653d74727565267374796c653d666c6174)](https://github.com/phpstan/phpstan)[![License](https://camo.githubusercontent.com/1ec505f62b54ead27680f0cde87713324e6355f0f0329b33487a97b8880ec6f9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6465636f64656c6162732f6b696e67646f6d3f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/kingdom)

### Service container management system

[](#service-container-management-system)

Kingdom provides a set of simple but powerful interfaces for building structures that can *contain* your whole application logic and services.

---

Installation
------------

[](#installation)

This package requires PHP 8.4 or higher.

Install via Composer:

```
composer require decodelabs/kingdom
```

Usage
-----

[](#usage)

Kingdom works in tandem with [Monarch](https://github.com/decodelabs/monarch) to give developers an easy way to manage dependency injection, application containment, service access and more.

An implementation of the `Kingdom` interface can be considered the *root* of your application in which all other services are contained. A project can have multiple `Kingdom` instances which are in turn controlled by the static `Monarch` class. Only one `Kingdom` instance can be considered active at a time.

You can think of `Monarch` and `Kingdom` in a similar way to how you would think of a monarch and a kingdom in real life - the monarch rules over the kingdom and the kingdom has a boundary around it, isolating it from the outside world.

You shouldn't need to interact with the monarch for many things as the kingdom should be able to provide most of the resources that are needed; only bother the monarch when you have to!

### Container

[](#container)

The heart of a `Kingdom` is its container. Instead of dealing directly with PSR-11 containers which only provide a rudimentary access scheme, `Kingdom` uses an adapter system that allows implementations to create a richer and more powerful service access mechanism.

[Pandora](https://github.com/decodelabs/pandora) implements both the PSR-11 interface *and* Kingdom's `ContainerAdapter` interface, allowing it to function directly as a service container for Kingdom without any additional configuration.

If you are building your application on top of [Fabric](https://github.com/decodelabs/fabric), a `Kingdom` implementation is provided for you using `Pandora` as the container by default.

See the [ContainerAdapter](./src/Kingdom/ContainerAdapter.php) interface for more information on the methods available.

### Services

[](#services)

Items held within the container can implement the `Service` interface to set them apart from other items in the container. The interface requires the implementation of a method to provide an instance of the service based on the contents on the container. A default implementation is provided in the `ServiceTrait` trait.

Services can be accessed in a `Kingdom` instance using the `getService` method.

```
use DecodeLabs\Kingdom\Service;
use DecodeLabs\Kingdom\ServiceTrait;

class MyService implements Service
{
    use ServiceTrait;
}

$service = $myKingdom->getService(MyService::class);
```

However, because a `Kingdom` is intended to be isolated and managed by the `Monarch` package, it is recommended to use the `Monarch::getService` method instead, which will delegate to the active `Kingdom` instance.

```
use DecodeLabs\Monarch;

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

The active `Kingdom` instance should be registered with `Monarch` during your bootstrap process. If you use [Genesis](https://github.com/decodelabs/genesis) for your bootstrapping, this will be taken care of for you, otherwise:

```
use DecodeLabs\Monarch;

Monarch::setKingdom($myKingdom);
```

### Runtime

[](#runtime)

Once a `Kingdom` has been initialized, it's main purpose is to run the application. This is determined by an instance of the `Runtime` interface, which acts like a kernel for your application.

There are default implementations of HTTP and CLI runtimes provided by [Harvest](https://github.com/decodelabs/harvest) and [Clip](https://github.com/decodelabs/clip) respectively.

Once bootstrapped, run your application:

```
$myKingdom->run();
```

Past this point, the container and service structure should be used to auto-wire the loading process with automatic dependency injection when constructing objects and services.

This can generally be handled in your own libraries by using [Slingshot](https://github.com/decodelabs/slingshot), or in a pinch, using `Monarch::getService()`.

### Fabric

[](#fabric)

When using `Kingdom` in a [Fabric](https://github.com/decodelabs/fabric) application, you can use your `Kingdom` implementation as the place to set up your application's container and services.

```
namespace My\Namespace;

use DecodeLabs\Fabric\Kingdom as FabricKingdom;
use DecodeLabs\Harvest\Profile as HttpProfile;
use DecodeLabs\Harvest\Middleware\Cors;

class Kingdom extends FabricKingdom
{
    public protected(set) string $name = 'DecodeLabs Playground';

    public function initialize(): void
    {
        parent::initialize();

        Monarch::getPaths()->alias('@public', '@run/public');
        Monarch::getPaths()->alias('@components', '@run/src/@components');

        $this->container->prepare(
            HttpProfile::class,
            fn (HttpProfile $profile) => $profile->add(Cors::class, allow: ['*'])
        );

        $this->container->setFactory(
            SomeOtherThing::class,
            fn () => new SomeOtherThing()
        );

        // ...etc
    }
}
```

Licensing
---------

[](#licensing)

Kingdom is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance66

Regular maintenance activity

Popularity21

Limited adoption so far

Community21

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 95.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~10 days

Total

3

Last Release

251d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8a241d64d12b3b5ee94197862ec1ec30b82ed2efa34a0cd7f4c3565a021daddd?d=identicon)[betterthanclay](/maintainers/betterthanclay)

---

Top Contributors

[![betterthanclay](https://avatars.githubusercontent.com/u/1273586?v=4)](https://github.com/betterthanclay "betterthanclay (21 commits)")[![szepeviktor](https://avatars.githubusercontent.com/u/952007?v=4)](https://github.com/szepeviktor "szepeviktor (1 commits)")

### Embed Badge

![Health badge](/badges/decodelabs-kingdom/health.svg)

```
[![Health](https://phpackages.com/badges/decodelabs-kingdom/health.svg)](https://phpackages.com/packages/decodelabs-kingdom)
```

###  Alternatives

[api-platform/state

API Platform state interfaces

223.4M57](/packages/api-platform-state)[internal/dload

Downloads binaries.

98142.7k10](/packages/internal-dload)[symfony/json-streamer

Provides powerful methods to read/write data structures from/into JSON streams.

14440.0k8](/packages/symfony-json-streamer)[rubix/server

Deploy your Rubix ML models to production with scalable stand-alone inference servers.

632.3k](/packages/rubix-server)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)