www.aleph1.co.uk Git - yaffs-website/blob - vendor/container-interop/container-interop/docs/ContainerInterface.md

   1 Container interface
   2 ===================
   3
   4 This document describes a common interface for dependency injection containers.
   5
   6 The goal set by `ContainerInterface` is to standardize how frameworks and libraries make use of a
   7 container to obtain objects and parameters (called *entries* in the rest of this document).
   8
   9 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
  10 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
  11 interpreted as described in [RFC 2119][].
  12
  13 The word `implementor` in this document is to be interpreted as someone
  14 implementing the `ContainerInterface` in a dependency injection-related library or framework.
  15 Users of dependency injections containers (DIC) are referred to as `user`.
  16
  17 [RFC 2119]: http://tools.ietf.org/html/rfc2119
  18
  19 1. Specification
  20 -----------------
  21
  22 ### 1.1 Basics
  23
  24 - The `Interop\Container\ContainerInterface` exposes two methods : `get` and `has`.
  25
  26 - `get` takes one mandatory parameter: an entry identifier. It MUST be a string.
  27   A call to `get` can return anything (a *mixed* value), or throws an exception if the identifier
  28   is not known to the container. Two successive calls to `get` with the same
  29   identifier SHOULD return the same value. However, depending on the `implementor`
  30   design and/or `user` configuration, different values might be returned, so
  31   `user` SHOULD NOT rely on getting the same value on 2 successive calls.
  32   While `ContainerInterface` only defines one mandatory parameter in `get()`, implementations
  33   MAY accept additional optional parameters.
  34
  35 - `has` takes one unique parameter: an entry identifier. It MUST return `true`
  36   if an entry identifier is known to the container and `false` if it is not.
  37   `has($id)` returning true does not mean that `get($id)` will not throw an exception.
  38   It does however mean that `get($id)` will not throw a `NotFoundException`.
  39
  40 ### 1.2 Exceptions
  41
  42 Exceptions directly thrown by the container MUST implement the
  43 [`Interop\Container\Exception\ContainerException`](../src/Interop/Container/Exception/ContainerException.php).
  44
  45 A call to the `get` method with a non-existing id SHOULD throw a
  46 [`Interop\Container\Exception\NotFoundException`](../src/Interop/Container/Exception/NotFoundException.php).
  47
  48 ### 1.3 Additional features
  49
  50 This section describes additional features that MAY be added to a container. Containers are not
  51 required to implement these features to respect the ContainerInterface.
  52
  53 #### 1.3.1 Delegate lookup feature
  54
  55 The goal of the *delegate lookup* feature is to allow several containers to share entries.
  56 Containers implementing this feature can perform dependency lookups in other containers.
  57
  58 Containers implementing this feature will offer a greater lever of interoperability
  59 with other containers. Implementation of this feature is therefore RECOMMENDED.
  60
  61 A container implementing this feature:
  62
  63 - MUST implement the `ContainerInterface`
  64 - MUST provide a way to register a delegate container (using a constructor parameter, or a setter,
  65   or any possible way). The delegate container MUST implement the `ContainerInterface`.
  66
  67 When a container is configured to use a delegate container for dependencies:
  68
  69 - Calls to the `get` method should only return an entry if the entry is part of the container.
  70   If the entry is not part of the container, an exception should be thrown
  71   (as requested by the `ContainerInterface`).
  72 - Calls to the `has` method should only return `true` if the entry is part of the container.
  73   If the entry is not part of the container, `false` should be returned.
  74 - If the fetched entry has dependencies, **instead** of performing
  75   the dependency lookup in the container, the lookup is performed on the *delegate container*.
  76
  77 Important! By default, the lookup SHOULD be performed on the delegate container **only**, not on the container itself.
  78
  79 It is however allowed for containers to provide exception cases for special entries, and a way to lookup
  80 into the same container (or another container) instead of the delegate container.
  81
  82 2. Package
  83 ----------
  84
  85 The interfaces and classes described as well as relevant exception are provided as part of the
  86 [container-interop/container-interop](https://packagist.org/packages/container-interop/container-interop) package.
  87
  88 3. `Interop\Container\ContainerInterface`
  89 -----------------------------------------
  90
  91 ```php
  92 <?php
  93 namespace Interop\Container;
  94
  95 use Interop\Container\Exception\ContainerException;
  96 use Interop\Container\Exception\NotFoundException;
  97
  98 /**
  99  * Describes the interface of a container that exposes methods to read its entries.
 100  */
 101 interface ContainerInterface
 102 {
 103     /**
 104      * Finds an entry of the container by its identifier and returns it.
 105      *
 106      * @param string $id Identifier of the entry to look for.
 107      *
 108      * @throws NotFoundException  No entry was found for this identifier.
 109      * @throws ContainerException Error while retrieving the entry.
 110      *
 111      * @return mixed Entry.
 112      */
 113     public function get($id);
 114
 115     /**
 116      * Returns true if the container can return an entry for the given identifier.
 117      * Returns false otherwise.
 118      *
 119      * `has($id)` returning true does not mean that `get($id)` will not throw an exception.
 120      * It does however mean that `get($id)` will not throw a `NotFoundException`.
 121      *
 122      * @param string $id Identifier of the entry to look for.
 123      *
 124      * @return boolean
 125      */
 126     public function has($id);
 127 }
 128 ```
 129
 130 4. `Interop\Container\Exception\ContainerException`
 131 ---------------------------------------------------
 132
 133 ```php
 134 <?php
 135 namespace Interop\Container\Exception;
 136
 137 /**
 138  * Base interface representing a generic exception in a container.
 139  */
 140 interface ContainerException
 141 {
 142 }
 143 ```
 144
 145 5. `Interop\Container\Exception\NotFoundException`
 146 ---------------------------------------------------
 147
 148 ```php
 149 <?php
 150 namespace Interop\Container\Exception;
 151
 152 /**
 153  * No entry was found in the container.
 154  */
 155 interface NotFoundException extends ContainerException
 156 {
 157 }
 158 ```