README

The Object-relational mapping (ORM) module for the Sledgehammer Framework.

Features

Full AutoCompletion support
POCO support. The Repository can load Plain Old Class Objects (POCO's)
Detect relations from the database
An optional ActiveRecord frontend
Linq style filtering support
Support for complex property mapping. A column "city" can be mapped to property "address->city"
1 database record maps to only 1 instance. via an IdentityMap
Relations are objects, To set the "customer_id" you'll set the "customer" property to a customer object.
Cascading save(). A save will update & insert all connected records.
Support for multiple backends: PDO (MySQL, SQLite), Webservices (Twitter, etc)
Clean queries. (No "1 = 1" where statements, etc)

Usage

use Sledgehammer\Orm\Repository;
// inside your bootstrap.php
$repo = Repository::instance();
$repo->registerBackend(new DatabaseRepositoryBackend("default")); // Extract models from the "default" database connection.

// Somewhere in your application
$repo = Repository::instance();
$customer = $repo->getCustomer($_GET['id']);
$customer->name = $_POST['name'];
$repo->saveCustomer($customer);

// When the Customer class extends Sledgehammer\ActiveRecord the familiar API is also available
$customer = Customer::one($_GET['id']);
$customer->name = $_POST['name'];
$customer->save();

// Linq style filtering
$selection = $repo->allCustomers()->where(array('name' => 'James Bond'))->where(function ($c) { return $c->isSpecialAgent(); });
$list = Customer::all()->select('name', 'id'); // Results in: array($id1 => $name1, $id2 => $name2, ...)

Relations and Placeholders

The relations of objects are loaded on demand via placeholder classes. Just use the object as if all the relations are already loaded:

$customer->orders[0]->product->title;

Works and provides autocompletion all the way.

A downside to the placeholder technique is that:

if ($customer->orders[0]->id === $order->id) { ... } // Always works

if ($customer->orders[0] === $order) { ...} // WRONG. Doesn't work reliably

This is because $order might still be a BelongsToHolder object that will be replaced when used (calling a function, getting or setting a property) Sidenote: A BelongsToHolder often knows the id value and reading $order->id won't trigger a replacement/query.

Update a relation

You wont find any "customer_id" properties in the objects, to change the "customer_id" you'll need to use a customer object.

$order->customer = $repo->getCustomer(1);
$repo->saveOrder($order);

Don't do this

$order->customer->id = 1; // WRONG
$repo->saveOrder($order);  // Throws Exception

This is because you're changing the customer object which the repository tries to save before the order and id changes aren't allowed.

Dictionary

Backend: A data retrieval and storing mechanism. Model: A configuration to map backend data to instances. Instance: An object that is created by the Repository from backend data based on a Model.

sledgehammer / orm

Maintainers

Details