eMapper
==============
**The Extensible Data Mapper library for PHP**
<br/>
**Author**: Emmanuel Antico
<br/>
**Version**: 3.2.0
<br/>
Changelog
------------------
<br/>
2014-08-28 - Version 3.2.0
* Added: Associations.
<br/>
Dependencies
--------------
<br/>
- PHP >= 5.4
- [eMapper-annotations](https://github.com/emaphp/eMapper-annotations "") package
- [eMacros](https://github.com/emaphp/eMacros "") package
<br/>
Installation
--------------
<br/>
**Installation through Composer**
<br/>
```javascript
{
"require": {
"emapper/emapper" : "3.2"
}
}
```
<br/>
About
------------
<br/>
*eMapper* is a PHP library aimed to provide a simple, powerful and highly customizable data mapping tool. It comes with some interesting features like:
- **Customized mapping**: Results can be mapped to a desired type through mapping expressions.
- **Indexation and Grouping**: Lists can be indexed or grouped together by a column value.
- **Custom types**: Developers can design their own types and custom type handlers.
- **Cache providers**: Obtained data can be stored in cache using APC or Memcache.
- **Dynamic SQL**: Queries can contain Dynamic SQL clauses writted in *eMacros*.
- **Entity Managers**: Managers provide a set of small ORM features which are common in similar frameworks.
<br/>
Introduction
-----------
<br/>
>Step 1: Pick an engine
eMapper supports SQLite, PostgreSQL and MySQL (or MariaDB if you prefer). Creating a connection requires creating an instance of the corresponding driver.
```php
//MYSQL
use eMapper\Engine\MySQL\MySQLDriver;
$driver = new MySQLDriver('database', 'localhost', 'user', 'passw');
//...
//SQLite
use eMapper\Engine\SQLite\SQLiteDriver;
$driver = new SQLiteDriver('database.sqlite');
//...
//PostgreSQL
use eMapper\Engine\PostgreSQL\PostgreSQLDriver;
$driver = new PostgreSQLDriver('host=localhost port=5432 dbname=database user=postgres password=123456');
```
<br/>
>Step 2: The Data Mapper
Now that the connection driver is ready we create an intance of the *Mapper* class.
```php
use eMapper\Mapper;
$mapper = new Mapper($driver);
```
<br/>
>Step 3: Have fun
eMapper is not ORM-oriented but type-oriented. Everything revolves around queries and *mapping expressions*. The following examples try to give you an idea of how the data mapping engine works.
```php
//by default, results are mapped to an array of arrays
$users = $mapper->query("SELECT * FROM users");
foreach ($users as $user) {
echo $user['name'];
//...
}
//to indicate the desired type we overload the mapper instance by calling the type method
$username = $mapper->type('string')->query("SELECT name FROM users WHERE id = 100");
//queries can receive a variable number of arguments
$users = $mapper->query("SELECT * FROM users WHERE surname = %{s} AND id > %{i}", "Doe", 1000);
//'arr' (or 'array') returns a row as an associative array
$user = $mapper->type('arr')->query("SELECT * FROM users WHERE name = %{s}", 'emaphp');
//using 'obj' as mapping expression will convert a row to an instance of stdClass
$user = $mapper->type('obj')->query("SELECT * FROM users WHERE id = %{i}", 42);
//close connection
$mapper->close();
```
<br/>
Mapping 101
-----------
<br/>
#####Simple types
```php
//mapping to an integer ('i', 'int', 'integer')
$total = $mapper->type('i')->query("SELECT COUNT(*) FROM users WHERE sex = %{s}", 'F');
//mapping to a boolean ('b', 'bool', 'boolean')
$suscribed = $mapper->type('b')->query("SELECT is_suscribed FROM users WHERE id = %{i}", 99);
//mapping to a float ('f', 'float', 'real', 'double')
$price = $mapper->type('f')->query("SELECT MAX(price) FROM products WHERE refurbished = {b}", false);
//mapping to a string ('s', 'str', 'string')
$body = $mapper->type('s')->query("SELECT message FROM posts WHERE slug = %{s}", 'emapper_rocks');
//dates ('DateTime', 'dt', 'timestamp', 'datetime')
$lastLogin = $mapper->type('dt')->query("SELECT last_login FROM users WHERE id = %{i}", 1984);
//finally, you can tell the exact column to fetch by providing a second argument
$code = $mapper->type('s', 'serial')->query("SELECT * FROM products WHERE id = %{i}", 101);
```
<br/>
#####Arrays
```php
//by default, an array contains both numeric and associative indexes
$movie = $mapper->type('array')->query("SELECT * FROM movies WHERE id = %{i}", 55);
//but you can change this by adding a second argument
use eMapper\Result\ArrayType;
//numeric only
$movie = $mapper->type('array', ArrayType::NUM)->query("SELECT * FROM movies WHERE id = %{i}", 56);
//associative only
$movie = $mapper->type('array', ArrayType::ASSOC)->query("SELECT * FROM movies WHERE id = %{i}", 57);
```
<br/>
#####Objects
```php
//mapping to a stdClass instance ('obj', 'object')
$book = $mapper->type('obj')->query("SELECT * FROM books WHERE isbn = %{s}", "9789507315428");
//using a custom class
$book = $mapper->type('obj:Acme\Library\Book')->query("SELECT * FROM books WHERE isbn = %{s}", "9788437604183");
```
*Note*: One important thing to remember when mapping to a structure is that values contained in columns declared using the DATE or DATETIME types are converted to instances of [DateTime](http://ar2.php.net/manual/en/class.datetime.php "").
<br/>
Lists
-----------
<br/>
#####Simple types
```php
//just add brackets at the end of the expression and you're done
$id_list = $mapper->type('int[]')->query("SELECT id FROM users");
$prices = $mapper->type('float[]')->query("SELECT price FROM products");
$isbn_list = $mapper->type('string[]')->query("SELECT isbn FROM books");
$creation_dates = $mapper->type('dt[]')->query("SELECT created_at FROM posts");
//again, a second argument could be provided to define which column to fetch
$refurbished = $mapper->type('bool[]', 'refurbished')->query("SELECT * FROM products");
```
<br/>
#####Arrays and Objects
```php
//same rule applies to arrays and objects
$users = $mapper->type('obj[]')->query("SELECT * FROM users");
//an array type could also be provided when mapping to lists
use eMapper\Result\ArrayType;
$users = $mapper->type('arr[]', ArrayType::ASSOC)->query("SELECT * FROM users");
```
<br/>
Indexes and Groups
-----------------------
<br/>
#####Indexes
```php
//the index column goes between brackets
$books = $mapper->type('array[id]')->query("SELECT * FROM books");
//a default type could be added right next to it
$products = $mapper->type('arr[id:string]')->query("SELECT * FROM products");
//make sure the column is present in the result (this won't work)
$books = $mapper->type('obj[isbn]')->query("SELECT id, name, price FROM books");
//when mapping to arrays, the index should be represented appropriately
use eMapper\Result\ArrayType;
//use first column as index
$products = $mapper->type('arr[0]', ArrayType::NUM)->query("SELECT * FROM products");
```
<br/>
#####Groups
```php
//group by a known column
$products = $mapper->type('arr<category>')->query("SELECT * FROM products");
//a type could also be specified
$books = $mapper->type('obj<publisher:string>')->query("SELECT * FROM books");
//both expressions can be mixed to obtain interesting results
$products = $mapper->type('obj<category>[id:int]')->query("SELECT * FROM products");
```
<br/>
#####Callbacks
```php
//lists could also be indexed using a closure
$products = $mapper->type('array[]')
->index_callback(function ($product) {
//return a custom made index
return $product['code'] . '_' . $product['id'];
})
->query("SELECT * FROM products");
// a group callback does what you expect
//it can also be combined with indexes if needed
$products = $mapper->type('obj[id]')
->group_callback(function ($product) {
return substr($product->category, 0, 3);
})
->query("SELECT * FROM products");
```
<br/>
Queries
-------
<br/>
#####Query arguments
```php
//arguments the easy way (type identifier between braces)
$products = $mapper->type('obj[]')->query("SELECT * FROM products WHERE price < %{f} AND category = %{s}", 699.99, 'Laptops');
//argument by position (and optional type)
$products = $mapper->type('obj[]')->query("SELECT * FROM products WHERE category = %{1} AND price < %{0:f}", 699.99, 'Laptops');
```
<br/>
#####Arrays/Objects as argument
```php
//array as parameter
$parameter = ['password' => sha1('qwerty'), 'modified_at' => new \DateTime];
$mapper->query("UPDATE users SET password = #{password}, modified_at = #{modified_at:dt} WHERE name = %{1:string}", $parameter, 'emaphp');
//syntax works with objects as well
use Acme\CMS\Comment;
$comment = new Comment();
$comment->setUserId(100);
$comment->setBody("Hello World");
$mapper->query("INSERT INTO comments (user_id, body) VALUES (#{userId}, #{body});", $comment);
```
*Note*: The syntax for array/object attributes work as long as you provide the array/object as the first argument.
<br/>
Named Queries
-------------
<br/>
#####Statements
```php
//declaring a statement
$mapper->stmt("findUserByPk", "SELECT * FROM users WHERE user_id = %{i}");
//statements are invoked with the execute method
$mapper->type('obj[]')->execute('findUserByPk', 100);
```
<br/>
#####Configuration
```php
//the stmt method supports a third argument with the predefined configuration for that query
use eMapper\SQL\Statement;
//declare statement
$mapper->stmt('findProductsByCategory',
"SELECT * FROM products WHERE category = %{s}",
Statement::type('obj[]'));
//get products as an object list
$products = $mapper->execute('findProductsByCategory', 'Audio');
//override default configuration and return result as an indexed list of arrays
$products = $mapper->type('array[id]')->execute('findProductsByCategory', 'Smartphones');
```
<br/>
#####Namespaces
```php
//namespaces provide a more organized way of declaring statements
use eMapper\SQL\SQLNamespace;
use eMapper\SQL\Statement;
class UsersNamespace extends SQLNamespace {
public function __construct() {
//set namespace id through parent constructor
parent::__construct('users');
$this->stmt('findByPk',
"SELECT * FROM users WHERE id = %{i}",
Statement::type('obj'));
$this->stmt('findByName',
"SELECT * FROM users WHERE name = %{s}",
Statement::type('obj'));
$this->stmt('findRecent'
"SELECT * FROM users WHERE created_at >= subdate(NOW(), INTERVAL 3 DAY)",
Statement::type('obj[id:int]'));
}
}
//add namespace
$mapper->addNamespace(new UsersNamespace());
//namespace id must be specified as a prefix
$user = $mapper->execute('users.findByPK', 4);
```
<br/>
Stored procedures
-----------------
<br/>
#####Invoking stored procedures
The *Mapper* class uses [method overloading](http://php.net//manual/en/language.oop5.overloading.php "") to translate an invokation to an non-existant method into a stored procedure call.
```php
//MySQL: CALL Users_Clean()
//PostgreSQL: SELECT Users_Clean()
$mapper->Users_Clean();
//if database prefix is set it is used as a prefix
$mapper->setPrefix('COM_');
//MySQL: CALL COM_Users_Clean()
//PostgreSQL: SELECT COM_Users_Clean()
$mapper->Users_Clean();
```
<br/>
#####Mapping values
```php
//simple values con be obtained like usual
$total = $mapper->type('i')->Users_CountActive();
//engines may differ in how to treat a structured value
$user = $mapper->type('obj')->Users_FindByPK(3); //works in MySQL only
//PostgreSQL needs an additional configuration value
//SQL: SELECT * FROM Users_FindByPK(3)
$user = $mapper->type('obj')->option('proc.as_table', true)->Users_FindByPK(3);
```
<br/>
Entity Managers
---------------
<br/>
#####Entities and Annotations
Writing all your queries can turn very frustating real soon. Luckily, eMapper provides a small set of ORM features that can save you a lot of time. Entity managers are objects that behave like DAOs ([Data Access Object](http://en.wikipedia.org/wiki/Data_access_object "")) for a specified class. The first step to create an entity manager is designing an entity class. The following example shows an entity class named *Product*. The *Product* class obtains its values from the *pŕoducts* table, indicated by the *@Entity* annotation. This class defines 5 attributes, and each one defines its type through the *@Type* annotation. If the attribute name differs from the column name we can specify a *@Column* annotation indicating the real one. As a general rule, all entities must define a primary key attribute. The *Product* class sets its **id** attribute as primary key using the *@Id* annotation.
```php
namespace Acme\Factory;
/**
* @Entity products
*/
class Product {
/**
* @Id
* @Type integer
*/
private $id;
/**
* @Type string
* @Column pcod
*/
private $code;
/**
* @Type string
*/
private $description;
/**
* @Type string
*/
private $category;
/**
* @Type float
*/
private $price;
public function getId() {
return $this->id;
}
public function setCode($code) {
$this->code = $code;
}
public function getCode() {
return $this->code;
}
public function setDescription($description) {
$this->description = $description;
}
public function getDescription() {
return $this->description;
}
public function setCategory($category) {
$this->category = $category;
}
public function getCategory(){
return $this->category;
}
public function setPrice($price) {
$this->price = $price;
}
public function getPrice() {
return $this->price;
}
}
```
Managers are created through the *buildManager* method in the *Mapper* class. This method expects the entity class full name. Managers are capable of getting results using filters without having to write SQL manually.
```php
//create a products manager
$products = $mapper->buildManager('Acme\\Factory\\Product');
//get by id
$product = $products->findByPk(4);
//obtain a product by code
use eMapper\Query\Attr;
$product = $products->get(Attr::code()->eq('XXX098'));
//get a list of products by a given category
$list = $products->find(Attr::category()->eq('Laptops'));
//define a filter (category = 'E-Books' AND price < 799.99)
$list = $products
->filter(Attr::category()->eq('E-Books'), Attr::price()->lt(799.99))
->find();
//OR condition (category = 'E-Books' OR price < 799.99)
use eMapper\Query\Q;
$list = $products
->filter(Q::where(Attr::category()->eq('E-Books'), Attr::price()->lt(799.99)))
->find();
//exclude (category <> 'Fitness')
$list = $products
->exclude(Attr::category()->eq('Fitness'))
->find();
//reverse condition (description NOT LIKE '%Apple%')
$list = $products
->filter(Attr::description()->contains('Apple', false))
->find();
```
<br/>
#####Manager utilities
```php
use eMapper\Query\Attr;
//getting all products indexed by id
$list = $products->index(Attr::id())->find();
//or grouped by category
$list = $products->group(Attr::category())->find();
//callbacks work as well
$list = $products
->index_callback(function ($product) {
return $product->getId() . substr($product->getCode(), 0, 5);
})
->find();
//order and limit clauses
$list = $products
->order_by(Attr::id())
->limit(15)
->find();
//setting the order type
$list = $products
->order_by(Attr::id('ASC'), Attr::category())
->limit(10, 20)
->find();
//count products of a given category
$total = $products
->filter(Attr::category()->eq('Audio'))
->count();
//average price
$avg = $products
->exclude(Attr::category()->eq('Laptops'))
->avg(Attr::price());
//max price (returns as integer)
$max = $products
->filter(Attr::code()->startswith('SONY'))
->max(Attr::price(), 'int');
```
<br/>
#####Storing objects
```php
use Acme\Factory\Product;
//create manager
$products = $mapper->buildManager('Acme\Factory\Product');
$product = new Product;
$product->setCode('ACM001');
$product->setDescription('Test product');
$product->setCategory('Explosives');
$product->setPrice(149.90);
//save object
$products->save($product);
//if the entity already has an id 'save' produces an UPDATE query
$product = $products->get(Attr::code()->eq('ACM001'));
$product->setPrice(129.90);
$products->save($product);
```
<br/>
#####Deleting objects
```php
//create manager
$products = $mapper->buildManager('Acme\Factory\Product');
//delete expects an entity as parameter
$product = $products->findByPk(20);
$products->delete($product);
//reduced version
$products->deleteWhere(Attr::id()->eq(20));
//for security reasions, truncating a table requires a special method
$products->truncate();
```
<br/>
Entity Namespaces
-----------------
<br/>
#####Introduction
Entity namespaces are classes that generate statements from an entity class automatically. These classes receive their respective ids from the *@DefaultNamespace* annotation in the entity class declaration. When not specified, the namespace takes the value indicated by the *@Entity* annotation.
```php
namespace Acme\Factory;
/**
* @Entity products
* @DefaultNamespace products
*/
class Product {
/**
* @Id
* @Type integer
*/
private $id;
/**
* @Unique
* @Type string
*/
private $code;
/**
* @Type string
*/
private $description;
/**
* @Type string
*/
private $category;
/**
* @Type float
*/
private $price;
//...
}
```
<br/>
#####Adding a entity namespace
```php
//add an entity namespace
use eMapper\SQL\EntityNamespace;
$mapper->addEntityNamespace(new EntityNamespace('Acme\Factory\Product'));
//find by primary key
$product = $mapper->execute('products.findByPk', 2);
//find all
$products = $mapper->execute('products.findAll');
//find by
$products = $mapper->execute('products.findByCategory', 'Laptops');
//override mapping expression
$products = $mapper->type('obj:Acme\Factory\Product[id]')->execute('descriptionIsNull');
```
<br/>
#####Statement list
<table>
<thead>
<tr>
<th>Statement ID</th>
<th>Example</th>
<th>Returned Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>findByPk</td>
<td><em>products.findByPk</em></td>
<td>Instance (NULL if not found)</td>
</tr>
<tr>
<td>findAll</td>
<td><em>products.findAll</em></td>
<td>List</td>
</tr>
<tr>
<td>findBy{PROPERTY}</td>
<td><em>products.findByCode</em></td>
<td>Instance if property is @Id or @Unique, a list otherwise</td>
</tr>
<tr>
<td>{PROPERTY}[Not]Equals</td>
<td><em>products.codeEquals</em><br/><em>products.priceNotEquals</em></td>
<td>Instance if property is @Id or @Unique, a list otherwise</td>
</tr>
<tr>
<td>{PROPERTY}[Not][I]Contains</td>
<td><em>products.categoryContains</em><br/><em>products.descriptionNotContains</em><br/><em>products.categoryIContains</em></td>
<td>List</td>
</tr>
<tr>
<td>{PROPERTY}[Not][I]StartsWith</td>
<td><em>products.categoryStartsWith</em><br/><em>products.descriptionNotStartsWith</em><br/><em>products.categoryIStartsWith</em></td>
<td>List</td>
</tr>
<tr>
<td>{PROPERTY}[Not][I]EndsWith</td>
<td><em>products.categoryEndsWith</em><br/><em>products.descriptionNotEndsWith</em><br/><em>products.categoryIEndsWith</em></td>
<td>List</td>
</tr>
<tr>
<td>{PROPERTY}[Not]In</td>
<td><em>products.idIn</em><br/><em>products.idNotIn</em></td>
<td>List</td>
</tr>
<tbody>
<td>{PROPERTY}[Not]GreaterThan[Equal]</td>
<td><em>products.idGreaterThan</em><br/><em>products.priceGreaterThanEqual</em><br/><em>products.priceNotGreaterThan</em></td>
<td>List</td>
</tbody>
<tbody>
<td>{PROPERTY}[Not]LessThan[Equal]</td>
<td><em>products.idLessThan</em><br/><em>products.priceLessThanEqual</em><br/><em>products.priceNotLessThan</em></td>
<td>List</td>
</tbody>
<tbody>
<td>{PROPERTY}[Not]IsNull</td>
<td><em>products.descriptionIsNull</em><br/><em>products.descriptionIsNotNull</em></td>
<td>List</td>
</tbody>
<tbody>
<td>{PROPERTY}[Not]Between</td>
<td><em>products.priceBetween</em><br/><em>products.priceNotBetween</em></td>
<td>List</td>
</tbody>
<tbody>
<td>{PROPERTY}[Not][I]Matches</td>
<td><em>products.categoryMatches</em><br/><em>products.codeNotMatches</em><br/><em>products.descriptionIMatches</em></td>
<td>List</td>
</tbody>
</table>
<br/>
Associations
-----------
<br/>
#####Introduction
Associations provide an easy way to fetch data related to an entity. As expected, they also need to be declared using a special set of annotations. Their types include *one-to-one*, *one-to-many*, *many-to-one* and *many-to-many*.
<br/>
#####One-To-One
The next example shows 2 entities (*Profile* and *User*) and how to declare a One-To-One association to obtain a *User* entity from a fetched profile.
```php
namespace Acme;
/**
* @Entity profiles
*/
class Profile {
/**
* @Id
* @Type integer
*/
private $id;
/**
* @Column user_id
*/
private $userId;
/**
* @Column firstname
*/
private $firstName;
/**
* @Type string
*/
private $surname;
/**
* @OneToOne User
* @Attr(userId)
*/
private $user;
//...
}
```
In this example, the *Product* class declares a **user** property which defines a one-to-one association with the *User* class. The *@Attr* annotation specifies which property is used to perform the required join.
```php
namespace Acme;
/**
* @Entity users
*/
class User {
/**
* @Id
* @Type integer
*/
private $id;
/**
* @Column username
*/
private $name;
/**
* @OneToOne Profile
* @Attr userId
* @Lazy
*/
private $profile;
//...
}
```
The *User* class defines the **profile** property as a one-to-one associaton with the *Profile* class. Notice that this time the *@Attr* annotation defines the property name as a value, not as an argument. Also, this association is declared as **lazy**, which means that is not evaluated right away. The following example shows how to obtain a *Profile* instance and its associated user.
```php
//obtain the profile with ID = 100
$manager = $mapper->buildManager('Acme\Profile');
$profile = $manager->findByPk(100); // returns a Profile instance
$user = $profile->getUser(); // returns the associated User instance
```
Lazy associations returns an instance of *eMapper\AssociationManager*. This means that invoking the *getProfile* method will return a manager instance. In order to get the referred value we append a call to the *fetch* method.
```php
//obtain the user with ID = 100
$manager = $mapper->buildManager('Acme\User');
$user = $manager->findByPk(100);
$profile = $user->getProfile(); // returns an AssociationManager instance
$profile = $user->getProfile()->fetch(); // fetch() returns the desired result
```
Associations also provide a mechanism to query for related attributes. Suppose we want to obtain a profile by its user name. We can do this by using a special syntax that specifies the association property and the comparison attribute separated by a doble underscore.
```php
use eMapper\Query\Attr;
//build manager
$manager = $mapper->buildManager('Acme\Profile');
//users.name = 'jdoe'
$profile = $manager->get(Attr::user__name()->eq('jdoe'));
```
<br/>
#####One-To-Many and Many-To-One
Suppose we need to design a pet shop database to store data from a list of clients and their respective pets. The first step after creating the database will be implementing the *Client* and *Pet* entity classes. The *Client* class has a one-to-many association to the *Pet* class provided through the **pets** property. The required attribute (**clientId**) is specified as a value of the *@Attr* annotation.This annotation references to the attribute in the *Pet* class that stores the client identifier.
```php
namespace Acme;
/**
* @Entity clients
*/
class Client {
/**
* @Id
*/
private $id;
/**
* @Type string
*/
private $name;
/**
* @Type string
*/
private $surname;
/**
* @OneToMany Pet
* @Attr clientId
*/
private $pets;
}
```
This small example obtains all clients that have dogs.
```php
use eMapper\Query\Attr;
$manager = $mapper->buildManager('Acme\Client');
//get all clients that have dogs
$clients = $manager->find(Attr::pets__type()->eq('Dog'));
```
From the point of view of the *Pet* class this is a many-to-one association. The **owner** association is resolved through the **clientId** attribute of the current class, meaning that in this case it has to be specified as an argument of the *@Attr* annotation.
```php
namespace Acme;
/**
* @Entity pets
*/
class Pet {
/**
* @Id
*/
private $id;
/**
* @Column client_id
*/
private $clientId;
/**
* @Type string
*/
private $name;
/**
* @Type string
*/
private $type;
/**
* @Column birth_date
* @Type string
*/
private $birthDate;
/**
* @ManyToOne Client
* @Attr(clientId)
*/
private $owner;
//...
}
```
This small example obtains all pets for a given client.
```php
use eMapper\Query\Attr;
$manager = $mapper->buildManager('Acme\Pet');
//get all pets of Joe Doe
$pets = $manager->find(Attr::owner__name()->eq('Joe'),
Attr::owner__surname()->eq('Doe'));
```
<br/>
#####Many-To-Many
Many-To-Many associations are kind of special as they need to provide the name of the join table that resolves the association. Suppose that we want to add a **favorites** association from the *User* class to the *Product* class.
```php
namespace Acme;
/**
* @Entity users
*/
class User {
/**
* @Id
*/
private $id;
/**
* @Column username
*/
private $name;
/**
* @Type string
*/
private $mail;
/**
* @ManyToMany Product
* @JoinWith(favorites) prod_id
* @Column usr_id
* @Lazy
*/
private $favorites;
}
```
The *@JoinWith* annotation must provide the join table name as argument and the column that references the associated entity as value. In this case, this association is resolved using the *favorites* table and the product identifier is stored using the *prod_id* column. The *@Column* annotation must then declare which column in the *favorites* table identifies the current entity. The following code shows an example on how to query for a user favorited products.
```php
use eMapper\Query\Attr;
$manager = $mapper->buildManager('Acme\User');
//get all users that like Android
$users = $manager->find(Attr::favorites__description()->contains('Android'));
```
<br/>
#####Recursive associations
There are some scenarios in which an entity is associated to itself in more than one way. In this example we'll introduce the *Category* entity class to explore in detail this type of associations.
```php
namespace Acme;
/**
* @Entity categories
*/
class Category {
/**
* @Id
*/
private $id;
/**
* @Type string
*/
private $name;
/**
* @Type integer
*/
private $parentId;
/**
* @ManyToOne Category
* @Attr(parentId)
*/
private $parent;
/**
* @OneToMany Category
* @Attr parentId
*/
private $subcategories;
//...
}
```
The *Category* class its related to itself through the **parent** and **subcategories** associations. Both of them need to specify the *parentId* attribute as the join attribute. Obtaining all subcategories
of a given category can be resolved in the following way.
```php
use eMapper\Query\Attr;
$manager = $mapper->buildManager('Acme\Category');
//get all subcategories of 'Technology'
$categories = $mapper->find(Attr::parent__name()->eq('Technology'));
```
<br/>
Dynamic SQL
-----------
<br/>
#####Introduction
Queries could also contain logic expressions which are evaluated againts current arguments. These expressions (or S-expressions) are written in [eMacros](https://github.com/emaphp/eMacros ""), a language based on lisphp. Dynamic expressions are included between the delimiters [? and ?]. The next example shows a query that sets the condition dynamically according to the argument type.
```sql
SELECT * FROM users WHERE [? (if (int? (%0)) 'id = %{i}' 'name = %{s}') ?]
```
```php
//add named query
$mapper->stmt('findUser', "SELECT * FROM users WHERE [? (if (int? (%0)) 'id = %{i}' 'name = %{s}') ?]");
//find by id
$user = $mapper->type('obj')->execute('findUser', 99);
//find by name
$user = $mapper->type('obj')->execute('findUser', 'emaphp');
```
<br/>
#####eMacros 101
Just to give you a basic approach of how S-expressions work here's a list of small examples. Refer to eMacros documentation for more.
```lisp
; simple math
(+ 4 10) ; 14
(- 10 4) ; 6
(* 5 3 2) ; 30
; sum first two arguments
(+ (%0) (%1))
; concat
(. "Hello" " " "World!")
; is int?
(int? 6) ; true
; is string?
(string? true) ; false
; cast to float
(as-float "65.32")
; get property value
(#description)
; get configuration value
(@default_order)
; if then else
(if (null? (#id)) "No id found!" (#id)) ; returns id when not null
```
<br/>
#####Configuration values
This example adds an ORDER clause if the configuration key 'order' is set.
```sql
SELECT * FROM users [? (if (@order?) (. 'ORDER BY ' (@order))) ?]
```
```php
//add named query
$mapper->stmt('obtainUsers', "SELECT * FROM users [? (if (@order?) (. 'ORDER BY ' (@order))) ?]");
//get all users
$mapper->type('obj[]')->execute('obtainUsers');
//the option method creates an instance with an additional configuration value
//get ordered users
$mapper->type('obj[]')->option('order', 'last_login')->execute('obtainUsers');
```
<br/>
#####Typed expressions
A value returned by a dynamic SQL expression can be associated to a type by adding the type identifier right after the first delimiter. This example simulates a search using the LIKE operator with the value returned by a dynamic expression that returns a string.
```sql
SELECT * FROM users WHERE name LIKE [?string (. '%' (%0) '%') ?]
```
```php
//add named query
$mapper->stmt('searchUsers', "SELECT * FROM users WHERE name LIKE [?string (. '%' (%0) '%') ?]");
//search by name
$users = $mapper->map('obj[]')->execute('searchUsers', 'ema');
```
<br/>
Dynamic Attributes
------------------
<br/>
#####Introduction
While associations are pretty useful by themselves you may want to go a step further. A dynamic attibute is a property that is the result of a query or calculation. This means that attributes could either be associated to a macro or a custom user query.
<br/>
#####Querys
This example introduces a new entity class named *Sale*. A sale is obviously related to a product. Let's say that we want to obtain that product using the corresponding column. In order to do this, we add a **product** property which includes a special *@Query* annotation. This annotation expects a string containing the query that solves this association. Notice that *Sale* must define a **productId** property in order to store the value sent to the query.
```php
namespace Acme\Factory;
/**
* @Entity sales
*/
class Sale {
/**
* @Id
*/
private $id;
/**
* @Column product_id
*/
private $productId;
/**
* @Query "SELECT * FROM products WHERE id = #{productId}"
* @Type obj:Acme\Factory\Product
*/
private $product;
//...
}
```
When used along with *@Query*, the *@Type* annotation specifies the mapping expression to use.
<br/>
#####Adding parameters
The *@Parameter* annotation can be used to define a list of arguments for a dynamic attribute. These arguments can be either a property of the current entity or a constant value. A special annotation *@Self* indicates that the current instance is used as first argument. Knowing this we can redefine the product property in two ways.
```php
/**
* @Query "SELECT * FROM products WHERE id = #{productId}"
* @Self
* @Type obj:Acme\Factory\Product
*/
private $product; //Here @Self is not required because the default
//behaviour already uses the entity as unique argument
/**
* @Query "SELECT * FROM products WHERE id = %{i}"
* @Parameter(productId)
* @Type obj:Acme\Factory\Product
*/
private $product; //Here productId is the only argument for this query
//This requires a modification in the query argument expression
```
In other words, *@Self* must be added if the specified query receives the current instance and an additional value as arguments. The next example adds a **relatedProducts** property in the *Product* class that includes 2 arguments: the current partial instance and a integer value that sets the amount of objects to return.
```php
namespace Acme\Factory;
class Product {
//...
/**
* @Query "SELECT * FROM products WHERE category = #{category} LIMIT %{i}"
* @Self
* @Parameter 10
* @Type obj::Acme\Factory\Product[id]
*/
private $relatedProducts;
}
```
<br/>
#####Statements
Named queries could also be called from a dynamic attribute by adding the *@StatementId* annotation.
```php
namespace Acme\Factory;
/**
* @Entity sales
*/
class Sale {
/**
* @Id
*/
private $id;
/**
* @Column product_id
*/
private $productId;
/**
* @StatementId products.findByPk
* @Parameter(productId)
* @Type obj:Acme\Factory\Product
*/
private $product;
//...
}
```
<br/>
#####Stored procedures
Procedures are defined through the *@Procedure* annotation. There's not much to say about them except that they ignore the *@Self* annotation for obvious reasons.
```php
/**
* @Entity products
*/
class Product {
/**
* @Id
*/
private $id;
/**
* @Type string
*/
private $category;
/**
* @Procedure Products_AvgPriceByCategory
* @Parameter(category)
* @Type float
*/
private $averagePrice;
//...
}
```
<br/>
#####Macros
*@Eval* evaluates a macro against current entity. Examples of usage of these type of attributes are getting a person's fullname or calculating his age.
```php
/**
* @Entity people
*/
class Person {
/**
* @Id
*/
private $id;
/**
* @Type string
*/
private $name;
/**
* @Column surname
*/
private $lastname;
/**
* @Column birth_date
* @Type dt
*/
private $birthDate;
/**
* @Eval (. (#name) ' ' (#lastname))
*/
private $fullname; //build person's full name
/**
* @Eval (as-int (diff-format (#birthDate) (now) "%y"))
*/
private $age; //calculate person's age
//...
}
```
<br/>
#####Conditional attributes
The *@If* and *@IfNot* annotations are used to define conditional attributes. These attributes are evaluated if the given expression evaluates to true with @If and false with *@IfNot*. Conditions must be expressed alaso as macros.
```php
/**
* @Entity users
*/
class User {
/**
* @Id
*/
private $id;
/**
* @Type string
*/
private $type;
/**
* @If (== (#type) 'member')
* @StatementId "users.loginHistory"
* @Parameter(id)
*/
private $loginHistory; //get login history if user is a member
/**
* @IfNot (or (== (#type) 'member') (== (#type) 'guest'))
* @StatementId 'admin.findNotifications'
* @Parameter(id)
*/
private $abuseNotifications; //get admin notifications if not a member nor guest
}
```
<br/>
#####Options
The *@Option* annotation set a custom option value for the current attribute. An option must define its name by setting it between parentheses just before the value.
```php
/**
* @Entity users
*/
class User {
/**
* @Id
*/
private $id;
/**
* @Query "SELECT * FROM contacts WHERE user_id = %{i} [? (. 'ORDER BY ' (@order)) ?]"
* @Parameter(id)
* @Option(order) 'contact_type'
*/
private $contacts;
//...
}
```
<br/>
Cache
-----
<br/>
#####Introduction
Currently, eMapper supports APC, Memcache and Memcached. Before setting a cache provider make sure the required extension is correctly installed.
<br/>
#####Providers
```php
//APC
use eMapper\Cache\APCProvider;
$provider = new APCProvider;
$mapper->setCacheProvider($provider);
//Memcache
use eMapper\Cache\MemcacheProvider;
$provider = new MemcacheProvider('localhost', 11211);
$mapper->setCacheProvider($provider);
//Memcached
use eMapper\Cache\MemcachedProvider;
$provider = new MemcachedProvider('mem');
$mapper->setProvider($provider);
```
<br/>
#####Storing values
```php
//get users and store values with the key 'USERS_ALL' (time to live: 60 sec)
//if the key is found in cache no query takes place (write once, run forever)
$users = $mapper->cache('USERS_ALL', 60)->query("SELECT * FROM users");
//cache keys also receive query arguments
//store values with the key 'USER_6'
$user = $mapper->type('obj')->cache('USER_%{i}', 120)->query("SELECT * FROM users WHERE id = %{i}", 6);
```
<br/>
Custom types
------------
<br/>
#####Introduction
Type handlers are classes that manage how a value is stored and retrieved from a column. To introduce how a type handler works we'll introduce a custom type called *RGBColor*.
```php
namespace Acme;
//the RGBColor class is a three component class that
//stores the amount of red, green and blue in a color
class RGBColor {
public $red;
public $green;
public $blue;
public function __construct($red, $green, $blue) {
$this->red = $red;
$this->green = $green;
$this->blue = $blue;
}
}
```
<br/>
#####Type handlers
A type handler extends the *eMapper\Type\TypeHandler* class and implements the *setParameter* and *getValue* methods.
```php
namespace Acme;
use eMapper\Type\TypeHandler;
class RGBColorTypeHandler extends TypeHandler {
/**
* Converts a RGBColor instance to a string expression
*/
public function setParameter($color) {
$red = ($color->red < 16) ? '0' . dechex($color->red) : dechex($color->red % 256);
$green = ($color->green < 16) ? '0' . dechex($color->green % 256) : dechex($color->green);
$blue = ($color->blue < 15) ? '0' . dechex($color->blue) : dechex($color->blue % 256);
return $red . $green . $blue;
}
/**
* Generates a new RGBColor instance from a string value
*/
public function getValue($value) {
return new RGBColor(hexdec(substr($value, 0, 2)),
hexdec(substr($value, 2, 2)),
hexdec(substr($value, 4, 2)));
}
}
```
<br/>
#####Types and aliases
```php
//add type
use Acme\RGBColorTypeHandler;
$mapper->addType('Acme\RGBColor', new RGBColorTypeHandler());
//mapping to RGBColor
$color = $mapper->type('Acme\RGBColor')->query("SELECT color FROM palette WHERE id = 1");
//using an alias
$mapper->addType('Acme\RGBColor', new RGBColorTypeHandler(), 'rgb');
//mapping to RGBColor using the previously defined alias
$color = $mapper->type('rgb')->query("SELECT color FROM palette WHERE id = 1");
```
<br/>
#####Using custom types
```php
/**
* @Entity vehicles
*/
class Car {
/**
* @Id
* @Type integer
*/
private $id;
/**
* @Type string
*/
private $manufacturer;
/**
* @Type rgb
*/
private $color;
//...
}
```
<br/>
License
--------------
<br/>
This code is licensed under the BSD 2-Clause license.
|
Download
