clancats/container

dev-master 2017-05-10 20:25 UTC

README

687474703a2f2f636c616e636174732e696f2f6173736574732f6d656469612f696d672f6c6f676f2f636f6e7461696e65722e706e67

ClanCats Container

A PHP Service Container featuring a simple meta language with fast and compilable dependency injection.

Build Status Packagist Packagist GitHub release

Requires PHP >= 7.0

Features:

  • Singleton and prototype service resolvers.
  • A container builder allowing to compile your service definitions.
  • Container files featuring a meta language to define your services.
  • Composer integration, allowing you to import default service definitions from your dependencies.
  • Lazy service providers for big and dynamic class graphs.

Cons:

  • Container allows only named services.
  • Currently no auto wiring.
  • Obviously no IDE Support for container files.

Why should I use this?

Don't, at least not at this stage. The container is not battle tested and is only in use on some small production systems. At this point, I still might change the public API or brake functionality. Feel free to try this out on small side projects. Obviously, I really appreciate everyone who wants to sacrifice their time to contribute.

Performance

This package might seem very heavy for a service container, but after a short warmup the compiled container is blazing fast and has almost no overhead (3 Classes). Binding and resolving services dynamically is slower but still won't impact performance in real world application.

Installation

The container follows PSR-4 autoloading and can be installed using composer:

$ composer require clancats/container

Documentation

The full documentation can be found on http://clancats.io/container

Quick Start

Following is just a really rough example, a much more detailed and explained guide can be found here: Getting Started

Setup

Our target directy structure will look like this:

app.php
app.container
composer.json
src/
  Human.php
  SpaceShip.php

Services

To demenstrate how to use this service container we need to create two classes a SpaceShip and a Human.

Create a new php file src/Human.php:

class Human
{
    public $name;

    public function setName(string $name) {
        $this->name = $name;
    }
}

Create another php file src/SpaceShip.php:

class SpaceShip
{
    protected $captain; // every ship needs a captain!

    public function __construct(Human $captain) {
        $this->captain = $captain;
    }

    public function ayeAye() {
        return 'aye aye captain ' . $this->captain->name;
    }
}

Container file

A container file allows you to bind your services & parameters using a simple meta language.

Note: This feature is entirely optional if you prefer binding your services in PHP itself read:

Create a new file called app.container in your applications root folder.

@malcolm: Human
    - setName: 'Reynolds'

@firefly: SpaceShip(@malcolm)

Container factory

Now we need to parse the container file and compile it as a new class. For this task we create the app.php file.

$factory = new \ClanCats\Container\ContainerFactory(__DIR__ . '/cache');

$container = $factory->create('AppContainer', function($builder)
{
    // create a new container namespace
    $namespace = new \ClanCats\Container\ContainerNamespace();

    // forward the parsed data to the container builder
    $builder->addArray($namespace->parse(__DIR__ . '/app.container'));
});

The variable $container contains now a class instance named AppContainer.

echo $container->get('firefly')->ayeAye() // "aye aye captain Reynolds"

Credits

License

The MIT License (MIT). Please see License File for more information.