DataMapper ORM

Cloning and Copies

You can clone an object to make it safe for manipulating. You can even clone an object in the middle of a query to run two different queries with similar settings!

If you have an object that you want to duplicate in the database, creating a copy makes that very easy.

Get Clone

Get Clone returns a clone of the object.

Note:  PHP's clone function is only capable of performing a shallow clone of objects. DataMapper's clone process has been improved over the default to be slightly less shallow, so related objects of a clone are also clones rather than references.

// Get a user
$u = new User();
$u->get_by_id($id);

$clone = $u->get_clone();

Looking at the above, both the $clone and $u objects are identical except you can modify the data of one, without affecting the data stored in the other. Saving the objects will of course update the same record in the database.

Get Copy

Get Copy returns a copy of the object. This is essentially a clone of the object but with the ID cleared. It can allow you to quickly save a new record of an existing similar item. For example:

// Let's save a new hosting plan
$p = new Plan();

$p->name = 'The 100GB Plan';
$p->storage = 1000;
$p->bandwidth = 2000;
$p->databases = 5;
$p->domains = 5;
$p->emails = 50;

$p->save();

// Now, lets make a copy of that saved plan and base a new one off of it
$p = $p->get_copy();

// Change only what we need to
$p->name = 'The Big 150GB Plan';
$p->storage = 1500;
$p->bandwidth = 2500;

// And now save a new record
$p->save();

Database Object Cloning

Unless you've changed $db_params to be FALSE, you do not need to worry about this!

If you have $db_params set to FALSE, then the $db object is shared across all objects by default.

However, you can force the clone or copy to have an independent copy of the database object by passing TRUE to either method.

Example:

$u = new User();
$u->where_related('group', 'name', 'Administrators');

$u2 = $u->get_clone(TRUE); // force a clone of the DB object
$u2->where('id <', 3);

$u->get(); // contains all Admins
$u2->get(); // contains only the Admins whose ID is less than 3