|
| 1 | +# CakePHP Datasource Library |
| 2 | + |
| 3 | +This library contains interfaces for implementing Repositories and Entities using any data source, |
| 4 | +a class for managing connections to any datasource and traits to help you implement quickly the |
| 5 | +interfaces provided by this package. |
| 6 | + |
| 7 | +## Repositories |
| 8 | + |
| 9 | +A repository is a class capable of interfacing with a data source by using operations such as |
| 10 | +`find`, `save` and `delete` by using intermediate query objects for expressing commands to |
| 11 | +the data store and returning Entities as the single result unit of such system. |
| 12 | + |
| 13 | +In the case of a Relational database, a Repository would be a `Table`, which can be return single |
| 14 | +or multiple `Entity` objects by using a `Query`. |
| 15 | + |
| 16 | +This library exposes the following interfaces for creating a system that implements the |
| 17 | +repository pattern and is compatible with the CakePHP framework: |
| 18 | + |
| 19 | +* `RepositoryIntercace` - Describes the methods for a base repository class. |
| 20 | +* `EntityInterface` - Describes the methods for a single result object. |
| 21 | +* `ResultSetInterface` - Represents the idea of a collection of Entities as a result of a query. |
| 22 | + |
| 23 | +Additionally, this package provides a few traits and classes you can use in your own implementations: |
| 24 | + |
| 25 | +* `EntityTrait` - Contains the default implementation for the `EntityInterface`. |
| 26 | +* `QueryTrait` - Exposes the methos for creating a query object capable of returning decoratable collections. |
| 27 | +* `ResultSetDecorator` - Decorates any traversable object so it complies with `ResultSetInterface`. |
| 28 | + |
| 29 | + |
| 30 | +## Connections |
| 31 | + |
| 32 | +This library also contains a couple utility classes meant to create and manage connection objects. Connections |
| 33 | +are typically used in repositories for interfacing with the actual data source system. |
| 34 | + |
| 35 | +The `ConnectionManager` class acts as a registry to access database connections your application has. It provides |
| 36 | +a place that other objects can get references to existing connections. Creating connections with the `ConnectionManager` |
| 37 | +is easy: |
| 38 | + |
| 39 | +```php |
| 40 | +use Cake\Datasource\ConnectionManager; |
| 41 | + |
| 42 | +ConnectionManager::config('master', [ |
| 43 | + 'className' => 'MyApp\Connections\CustomConnection', |
| 44 | + 'param1' => 'value', |
| 45 | + 'param2' => 'another value' |
| 46 | +]); |
| 47 | + |
| 48 | +ConnectionManager::config('slave', [ |
| 49 | + 'className' => 'MyApp\Connections\CustomConnection', |
| 50 | + 'param1' => 'different value', |
| 51 | + 'param2' => 'another value' |
| 52 | +]); |
| 53 | +``` |
| 54 | + |
| 55 | +When requested, the `ConnectionManager` will instantiate `MyApp\Connections\CustomConnection` by passing |
| 56 | +`param1` and `param2` inside an array as the first argument of the constructor. |
| 57 | + |
| 58 | +Once configured connections can be fetched using `ConnectionManager::get()`. This method will |
| 59 | +construct and load a connection if it has not been built before, or return the existing known connection: |
| 60 | + |
| 61 | +```php |
| 62 | +use Cake\Datasource\ConnectionManager; |
| 63 | +$conn = ConnectionManager::get('master'); |
| 64 | +``` |
| 65 | + |
| 66 | +It is also possible to store connection objects by passing the instance directly to the manager: |
| 67 | + |
| 68 | +```php |
| 69 | +use Cake\Datasource\ConnectionManager; |
| 70 | +$conn = ConnectionManager::config('other', $connectionInstance); |
| 71 | +``` |
| 72 | + |
| 73 | +## Documentation |
| 74 | + |
| 75 | +Please make sure you check the [official API documentation](http://api.cakephp.org/3.0/namespace-Cake.Datasource.html) |
| 76 | + |
| 77 | + |
0 commit comments