Getting started

Getting started

Concepts

Repository

Sledgehammer ORM uses the Repository pattern to perform crud operations.

The Repository object is also performs the role of DataMapper and IdentityMapper

RepositoryBackend

The repository doesn't generate any SQL statements, this is the responsibility of the RepositoryBackend which doesn't even have to be a database. The built-in DatabaseRepositoryBackend support MySQL & SQLite databases.

ModelConfig

A modelconfig describes the mapping between properties and relations in the backend and object structure.

Setup

$repo = Sledgehammer\getRepository();
$backend = new DatabaseRepositoryBackend('default');
$repo->registerBackend(backend);

This will examine the database, generate ModelConfigs and generate classes where no matching classname is detected.

Retrieving data

These example use "Customer" as example , replace this with your model name.

Retrieving an object by id

$customer1 = $repo->getCustomer(1);

Now you can use the $customer1 and all its related data.

foreach($customer1->orders as $order) {
}

The orders will be lazy loaded on access. Until then the $customer1->orders will be a Placeholder object.

Objects are reused, the same instance is used everywhere.

$customer1 === $customer->orders[0]->customer; // true

Beware! when related record isn't in memory a Placeholder object is placed.

$order1 = $repo->getOrder(1); 
$order1->customer === $repo->getCustomer(1); // Can be true or false
$order1->customer->id === $repo->getCustomer(1)->id; // Always true

$order1->customer could be a BelongsToPlaceholder which will be swapped on access.

Retrieving an object by criteria

$me = $repo->oneCustomer(['email' => 'me@example.com']);

$login = $repo->oneCustomer(['AND', 'email' => 'me@example.com', 'password' => sha1('secret')]);

Retrieving collection by criteria

$customers = $repo->allCustomers();

This code doesn't execute a query directly, but builds a query object.

$customers = $repo->allCustomers();
$selection = $customers->where(['country.id' => 'NL'])->orderBy('lastname');

You can create new query objects by using the Collection

Reminder! The collection does not have a fluent interface the methods return a new collection and keep the original collection intact.

Saving data

Creating a new record:

$customer = $repo->createCustomer();
$customer->firstname = 'Bruce';
$customer->lastname = 'Wayne';
$repo->saveCustomer($customer);

Invoking save on an instance will also save all related records. This allows you to create a Unity of work

$order = $repo->createOrder();
$order->content = "Batmobile";
$order->customer = $repo->createCustomer(['firstname' => 'Bruce', 'lastname' => 'Wayne']);
$repo->saveCustomer($order);

ActiveRecord

The Sledgehammer ORM has an optional ActiveRecord superclass.

Usage

$newCustomer = Customer::create();

$customer1 = Customer::one(1);
$customer1->save();

$premiumCustomers = Customer::all()->where(['isPremium' => true]);

Events

The class then has Backbone-style events via Observable:

$customer->on('saved', function ($customer) {
    Logger::append('Customer has been saved');
}); 
$customer->on('change:isPremium', function ($customer, $newValue, $oldValue) {
    if ($newValue)
       $customer->credits += 100;
    }
});