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. [Utility & Helpers](/categories/utility)
4. /
5. decodelabs/kingdom

ActiveLibrary[Utility & Helpers](/categories/utility)

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

Service container and management system

v0.2.0(9mo ago)05.5k120MITPHPPHP ^8.4CI passing

Since Aug 20Pushed 1mo agoCompare

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

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

43

—

FairBetter than 89% of packages

Maintenance75

Regular maintenance activity

Popularity22

Limited adoption so far

Community21

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.3% 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

297d 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 (26 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

[symfony/dependency-injection

Allows you to standardize and centralize the way objects are constructed in your application

4.2k455.6M9.6k](/packages/symfony-dependency-injection)[illuminate/contracts

The Illuminate Contracts package.

706130.3M13.3k](/packages/illuminate-contracts)[illuminate/container

The Illuminate Container package.

31182.0M2.4k](/packages/illuminate-container)[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

564576.7k53](/packages/ecotone-ecotone)[symfony/type-info

Extracts PHP types information.

20069.8M270](/packages/symfony-type-info)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k43](/packages/civicrm-civicrm-core)

PHPackages © 2026

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