Download the PHP package blast/orm without Composer

Blast ORM

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 and can be installed using Composer. This can be done by running the following command or by updating your composer.json file.

composer.json

Be sure to also include your Composer autoload file in your project:

Downloading .zip file

This project is also available for download as a .zip file on GitHub. Visit the releases page, select the version you want, and click the "Source code (zip)" download button.

Requirements

The following versions of PHP are supported by this version.

• PHP >= 5.5.9
• PHP 5.6
• PHP 7.0
• HHVM

Example

An example can be found in this blog post.

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

Stored and named connections

Connection manager

The connection manager stores all connection in it's own cache by name.

In some cases you would like to use a new connection manager instance, e.g. in a separate container.

Work with connections

Add a connection. If second parameter name is not set, name is default.

Get connection, default connection name is always default

Swap default connection with another connection.

Query

The query object is is providing high level API methods of doctrine 2 query builder.

Create query from connection

with entity

with definition

Create a new query instance, the query is automatically determining current active connection from connection manager.

or create a new query with a custom connection

or create a new query for an entity

Custom connection for the query

Custom query builder

select

Get all posts as collection \SplStack containing post as \ArrayObject

Get post by id as \ArrayObject

create

Create a new entry and get number of affected rows

update

Update an entry and get number of affected rows

delete

Delete entries and get number of affected rows

Advanced execution for select

Execute query and get result as entity

Execute query and get result as collection

Execute query and get raw result as array

Events

Query is able to execute events for each statement type.

• select
• insert
• update
• delete

build.{type}

Fire this event before query executes statement.

result.{type}

Fire this event after query executes statement and receives result.

Canceling query execution

Use setCancel() method from given event to cancel a query execution.

On build a query statement

On result a query statement

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.

Definition

In addition to auto-suggest definition from provider, it is also possible to use definition instead of entity.

A list of possible configuration

A definition could also be declared on an entity as FQCN by property

or by method.

Mention you could also pass an definition object instead of a FQCN.

Provider

Providers are used to determine the entity definition and hydrate data to entity and vice versa. You could pass an object, class name or table name to provider.

If the entity class does not have a definition. the definition is determined automatically by the provider. Definitions are represented by static entity methods and / or properties.

Use providers to access tables without creating a entity class. This is useful for accessing junction tables or temporary tables.

Add definition to entity as public static property or method. Method name refers to configuration key, mentioned above.

Table name

Return table name as string

• Default: class name without namespace, camelcase converts to underscores e.g. App\Entities\Post will have post as table name.
• Static method: or YourEntity::table()
• Static property: YourEntity::$table

Primary key name

Return primary key name as string

• Default: id
• Static method: Entity::primaryKeyName()
• Static property: YourEntity::$primaryKeyName

Mapper

Return mapper class name as string or a instance of Blast\Orm\MapperInterface

• Default: An instance of Blast\Orm\Mapper
• Static method: Entity::mapper()
• Static property: YourEntity::$mapper

Relations

Return relations as array containing instance of Blast\Orm\Relations\RelationInterface.

• Default: []
• Static method: Entity::relations()

Access definition from provider

Adapters grant access to data and definition, even if your entity class does not have definitions at all.

Get table name

Get primary key name

Get entities mapper

Get entities relation

Hydrate data as array to entity

Hydrate data as entity to array

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

Get entity specific mapper from provider

find

Fetch one entry by primary key

select

Custom select query

delete

delete expects an primary key or an array of primary keys.

Delete onw entry

Delete many entries

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.

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.

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

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

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.

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

Create repository by abstract

Create repository instance

find

Fetch one entry by primary key

all

Fetch all entries and return as collection Blast\Orm\Data\DataObject

save

Save is determining if the entity is new and executes Blast\Orm\Mapper::update or if it is new Blast\Orm\Mapper::create.

Further development

Please visit our milestones

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Marco Bunge
• All contributors

License

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