Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/phpthinktank/blast-orm
Framework agnostic data access and persistence based on Doctrine 2 DBAL.
https://github.com/phpthinktank/blast-orm
Last synced: 23 days ago
JSON representation
Framework agnostic data access and persistence based on Doctrine 2 DBAL.
- Host: GitHub
- URL: https://github.com/phpthinktank/blast-orm
- Owner: phpthinktank
- License: mit
- Created: 2015-11-22T09:35:29.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2016-09-19T14:31:42.000Z (about 8 years ago)
- Last Synced: 2024-08-05T14:15:27.957Z (4 months ago)
- Language: PHP
- Homepage: http://bit.ly/php-orm
- Size: 454 KB
- Stars: 65
- Watchers: 6
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog-1.0.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- ZF-awesome-apps - Blast ORM - Framework agnostic data access and persistence based on Doctrine 2 DBAL. (Table of Contents / Zend Framework 2)
README
# Blast ORM
[![Latest Version on Packagist][ico-version]][link-packagist]
[![Software License][ico-license]](LICENSE.md)
[![Build Status][ico-travis]][link-travis]
[![Total Downloads][ico-downloads]][link-downloads]
[![Coverage Status][ico-coveralls]][link-coveralls]
Framework agnostic data access and persistence based on Doctrine 2 DBAL.
## Features
- Data and relation mapper _since 0.1_
- Decoupled entities as POPO's (Plain-old PHP objects) _since 0.3_
- Auto-Suggesting entity definition as well as configure custom definition _since 0.5_
- Data hydration to entity and vice versa _since 0.5_
- Repository contracted to a single entity class _since 0.5_
- Integration of fields from definition _since 0.5.2_
- Field type aware converting _since 0.5.2_
- Integration of indexes from definition _since 0.6.4_
- entity independent and connection dependent table prefixes _since 0.6.4_
- entity reflection and meta data caching _since 0.6.4_
## Upcoming features
- Unit of Work - Entity-aware transactions
- Identity map - Reduce load by storing entity by primary key
## Install
### Using Composer
Blast ORM is available on [Packagist](https://packagist.org/packages/blast/orm) and can be installed using [Composer](https://getcomposer.org/). This can be done by running the following command or by updating your `composer.json` file.
```bash
composer require blast/orm
```
composer.json
```json
{
"require": {
"blast/orm": "~1.0"
}
}
```
Be sure to also include your Composer autoload file in your project:
```php
= 5.5.9
* PHP 5.6
* PHP 7.0
* HHVM
## Example
An example can be found in this [blog post](http://bit.ly/php-orm).
## Concept
### Entities
An entity object is an in-memory representations of a database entity. Entity object are plain objects (aka POPO).
It is recommended to use accessors (getters) and mutators (setters) for properties on plain objects.
#### Provider
The provider is a link between independent data entity and data access. The provider is also able to hydrate data to
entity object and extract data from entity object.
#### Definition
Definition managing entity meta and schema specific configuration. Definition could be passed to mapper or provider,
instead of an entity.
### Mappers
Each entity does have it's own mapper. A mapper is determined by the entity provider. Mappers mediate between dbal
and entity and provide convenient CRUD (Create, Read, Update, Delete). In addition to CRUD, the mapper is also delivering
convenient methods to to work with relations.
### Query
The query acts as accessor to the persistence layer. The query class is hydrating data on execution and transforms the
result into a single entity class or `\ArrayObject` as fallback, a collection of entity classes as `\SplStack` or as a
raw data array. Furthermore the query is able to receive hydration options to control the result. Create, delete and
update are always returning a numeric value!
### Repository
The repository is mediating between persistence layer and abstract from persistence or data access through mapper or query.
Blast orm is just delivering a `Blast\Orm\RepositoryInterface` for completion!
## Usage
### Connections
Blast ORM is managing all connections with `\Blast\Orm\ConnectionManager`. You are able to create connections directly
or add connections to manager cache and access them later on.
#### Direct access
Create a new connection
```php
add('mysql://root:root@localhost/defaultdb?charset=UTF-8', 'myconnectionname');
```
Get connection, default connection name is always `default`
```php
get();
//get connection by name
$anotherConnection = $connections->get('another');
```
Swap default connection with another connection.
```php
setDefaultConnection('another');
```
### Query
The query object is is providing high level API methods of [doctrine 2 query builder](http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/query-builder.html#security-safely-preventing-sql-injection).
Create query from connection
```php
createQuery();
```
with entity
```php
createQuery(Post::class);
```
with definition
```php
createQuery($definition);
```
Create a new query instance, the query is automatically determining current active connection from connection manager.
```php
setConnection(ConnectionManager::create('mysql://root:root@localhost/acme'));
```
Custom query builder
```php
setBuilder($connection->createQueryBuilder());
```
#### select
Get all posts as collection `\SplStack` containing post as `\ArrayObject`
```php
select()->from('post', 'p')->execute();
//get data from result
$title = $result['title'];
$content = $result['content'];
```
Get post by id as `\ArrayObject`
```php
select()
->from('post', 'p')
->where('id = :id')
->setParameter('id', $id)
->execute();
//loop results and get data
foreach($results as $result){
$title = $result['title'];
$content = $result['content'];
}
```
#### create
Create a new entry and get number of affected rows
```php
insert('post')
->setValue('title', 'New Blog post')
->setValue('content', 'some blog content')
->execute();
```
#### update
Update an entry and get number of affected rows
```php
update('post')
->set('title', 'New Blog post')
->where('id = :id')
->setParameter('id', 1)
->execute();
```
#### delete
Delete entries and get number of affected rows
```php
delete('post')
->where('id = :id')
->setParameter('id', 1)
->execute();
```
#### Advanced execution for select
Execute query and get result as entity
```php
execute(\Blast\Orm\Hydrator\HydratorInterface::HYDRATE_ENTITY);
```
Execute query and get result as collection
```php
execute(\Blast\Orm\Hydrator\HydratorInterface::HYDRATE_COLLECTION);
```
Execute query and get raw result as array
```php
execute(\Blast\Orm\Hydrator\HydratorInterface::HYDRATE_RAW);
```
#### Events
Query is able to execute events for each statement type.
- select
- insert
- update
- delete
##### build.{type}
Fire this event before query executes statement.
```php
getEmitter()->addListener('build.select', function (QueryBuilderEvent $event) {
$event->getBuilder()->setEntity(Post::class);
});
$result = $query->select()->from('post')->where('id = 1')->execute();
```
##### result.{type}
Fire this event after query executes statement and receives result.
```php
getEmitter()->addListener('result.select', function (QueryResultEvent $event, Query $builder) {
$result = $event->getResult();
foreach ($result as $key => $value) {
$result[$key]['contentSize'] = strlen($value['content']);
}
$event->setResult($result);
});
$result = $query->select()->from('post')->where('id = 1')->execute();
```
###### Canceling query execution
Use `setCancel()` method from given event to cancel a query execution.
On build a query statement
```php
getEmitter()->addListener('build.select', function (QueryBuilderEvent $event) {
$event->setCanceled(true);
});
```
On result a query statement
```php
getEmitter()->addListener('result.select', function (QueryResultEvent $event) {
$event->setCanceled(true);
});
```
### Entities
Entity classes are independent of Blast ORM. Entity fields are translated to underscore for database field mapping.
Database fields are translated to camelcase for entity field mapping.
```php
setConfiguration([
'tableName' => 'user_role'
]);
//from mapper
$mapper = new Mapper($definition);
//from query
$query = new Query($connection, $definition);
```
A list of possible configuration
```php
\ArrayObject::class,
'entityCollection' => \SplStack::class,
'events' => [],
'fields' => [],
'indexes' => [],
'primaryKeyName' => ProviderInterface::DEFAULT_PRIMARY_KEY_NAME,
'tableName' => '',
'mapper' => Mapper::class,
'relations' => []
];
$definition->setConfiguration($configuration);
```
A definition could also be declared on an entity as FQCN by property
```php
hasOne($entity, 'otherTable')
];
}
}
```
##### Access definition from provider
Adapters grant access to data and definition, even if your entity class does not have definitions at all.
```php
getTableName();
```
Get primary key name
```php
getPrimaryKeyName();
```
Get entities mapper
```php
getMapper();
```
Get entities relation
```php
getRelations();
```
Hydrate data as array to entity
```php
hydrate(['title' => 'Hello World']);
```
Hydrate data as entity to array
```php
extract();
```
### Mapper
The mapper prepares queries for data persistence and access of a provided entity class. All methods always return a query
instance and need to execute manually. It is also possible to add event listeners for query
#### Create a new mapper for entity
Get entity specific mapper from connection
```php
getMapper($post);
```
Get entity specific mapper from provider
```php
getDefinition()->getMapper();
```
#### find
Fetch one entry by primary key
```php
find(1)->execute();
```
#### select
Custom select query
```php
select()
->where('title = "Hello world"')
->setMaxResults(1)
->execute(EntityHydratorInterface::RESULT_ENTITY);
```
#### delete
`delete` expects an primary key or an array of primary keys.
Delete onw entry
```php
delete(1);
```
Delete many entries
```php
delete([1, 2]);
```
### Relations
Relations provide access to related, parent and child entity from another entity.
#### Passing relations
Pass relations as `array` by computed static relation method in entity class. Relations are automatically mapped to entity.
```php
comments;
}
public static function relation(Post $entity, Mapper $mapper){
return [
$mapper->hasMany($entity, Comments::class)
];
}
}
$post = $mapper->find(1);
$comments = $post->getComments()->execute();
```
You could also extend the relation query with `RelationInterface::getQuery`.
#### HasOne (one-to-one)
One entity is associated with one related entity by a field which associates with primary key in current entity.
- `$entity` - Current entity instance
- `$foreignEntity` - Entity class name, instance or table name
- `$foreignKey` - Field name on related entity. `null` by default. Empty foreign key is determined by current entity table name and primary key name as follows: `{tableName}_{primaryKeyName}`, e.g `user_id`
##### Example
One user has one address.
```php
hasOne($user, Address::class, 'user_id');
```
#### HasMany (one-to-many)
One entity is associated with many related entities by a field which associates with primary key in current entity.
- `$entity` - Current entity instance
- `$foreignEntity` - Entity class name, instance or table name
- `$foreignKey` - Field name on a related entity. `null` by default. Empty foreign key is determined by current entity table name and primary key name as follows: `{tableName}_{primaryKeyName}`, e.g `post_id`
##### Example
One post has many comments
```php
hasMany($post, Comments::class, 'post_id');
```
#### BelongsTo (one-to-one or one-to-many)
BelongsTo is the inverse of a HasOne or a HasMany relation.
One entity is associated with one related entity by a field which associates with primary key in related entity.
- `$entity` - Current entity instance
- `$foreignEntity` - Entity class name, instance or table name
- `$localKey` - Field name on current entity. `null` by default. Empty local key is determined by related entity table name and primary key name as follows: `{tableName}_{primaryKeyName}`, e.g `post_id`
##### Example
One post has one or many comments
```php
belongsTo($comment, Post::class, 'post_id');
```
#### ManyToMany (many-to-many)
Many entities of type _A_ are associated with many related entities of type _B_ by a junction table. The junction table
stores associations from entities of type _A_ to entities of type _B_.
- `$entity`: Current entity instance
- `$foreignEntity`: Entity class name, instance or table name
- `$foreignKey` - Field name on a related entity. `null` by default. Empty foreign key is determined by current primary key name.
- `$localKey`: Field name on current entity. `null` by default. Empty foreign key is determined by related entity primary key name.
- `$junction`: Junction table name. `null` by default. Empty table name is determined by entity table name and foreign entity table name as follows: `{tableName}_{foreignTableName}`, e.g `post_comment`.
- `$junctionLocalKey`: Field name on a related entity. `null` by default. Empty junction local key is determined by current entity table name and primary key name as follows: `{tableName}_{primaryKeyName}`, e.g `post_id`.
- `$junctionForeignKey`: Field name on current entity. `null` by default. Empty junction foreign key is determined by related entity table name and primary key name as follows: `{tableName}_{primaryKeyName}`, e.g `comment_id`.
##### Example
One user has many roles, and one role has many users. Users primary key name is `id`, Roles primary key name is `pk`
(Primary key short name). The junction table `user_role` contains `user_id` and `role_id` columns.
```php
manyToMany($user, Role::class, 'pk', 'id', 'user_role', 'user_id', 'role_id');
```
### Repository
The repository abstracts methods for data persistence and access. All methods execute their queries directly.
Blast ORM provides a repository interface `\Blast\Orm\RepositoryInterface`.
A repository knows it's entity. Therefore we need to pass the entity as class name or instance
Create from interface
```php
createMapper($this->getEntity())->select()->execute(HydratorInterface::HYDRATE_COLLECTION);
}
/**
* Find entity by primary key
*
* @param mixed $primaryKey
* @return \ArrayObject|\stdClass|object
*/
public function find($primaryKey)
{
return $this->createMapper($this->getEntity())->find($primaryKey)->execute(HydratorInterface::HYDRATE_ENTITY);
}
/**
* Save new or existing entity data
*
* @param object|array $data
* @return int|bool
*/
public function save($data)
{
return $this->createMapper($data)->save($data)->execute();
}
}
```
Create repository by abstract
```php
setEntity(Post::class);
}
}
```
Create repository instance
```php
find(1);
```
#### all
Fetch all entries and return as collection `Blast\Orm\Data\DataObject`
```php
all();
foreach($posts as $post){
//do something
}
```
#### save
Save is determining if the entity is new and executes `Blast\Orm\Mapper::update` or if it is new `Blast\Orm\Mapper::create`.
```php
save($post);
```
## Further development
Please visit our [milestones](https://github.com/phpthinktank/blast-orm/milestones)
## Change log
Please see [CHANGELOG](ChangeLog-0.1.md) for more information what has changed recently.
## Testing
``` bash
$ composer test
```
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Security
If you discover any security related issues, please email instead of using the issue tracker.
## Credits
- [Marco Bunge][link-author]
- [All contributors][link-contributors]
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
[ico-version]: https://img.shields.io/packagist/v/blast/orm.svg?style=flat-square
[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square
[ico-travis]: https://img.shields.io/travis/phpthinktank/blast-orm/master.svg?style=flat-square
[ico-downloads]: https://img.shields.io/packagist/dt/blast/orm.svg?style=flat-square
[ico-coveralls]: https://img.shields.io/coveralls/phpthinktank/blast-orm/master.svg?style=flat-square)](https://coveralls.io/github/phpthinktank/blast-orm?branch=master
[link-packagist]: https://packagist.org/packages/blast/orm
[link-travis]: https://travis-ci.org/phpthinktank/blast-orm
[link-downloads]: https://packagist.org/packages/blast/orm
[link-author]: https://github.com/mbunge
[link-contributors]: ../../contributors
[link-coveralls]: https://coveralls.io/github/phpthinktank/blast-orm