DataMapper


Save

There are a number of ways to run Save and its effect will be different depending on the condition of the object you run it on, and whether you pass in a parameter.

Save on a New Object

Running Save on a new object, one without an ID, will see a new record created for it its relevant Database table. After saving, it will automatically populate itself with its new data, such as its ID and any changes its properties had after validation (such as an encrypted password).

// Create new User
$u = new User();

// Enter values into required fields
$u->username = "foo";
$u->password = "bar";
$u->email = "foo@bar.com";

// Save new user
$u->save();

The new user foo will now have an ID and an encrypted password (as well as a salt for use later on when he logs in).

Save on an Existing Object

Running Save on an existing object will update its corresponding record in the database.

// Get user foo
$u = new User();
$u->where('username', 'foo')->get();

// Change the email
$u->email = "baz@qux.com";

// Save changes to existing user
$u->save();

As the only change is the email, the email will be updated.

Save a Relationship

It's easy to save the relationships your objects have with each other, and there are a few ways of doing it.

Note:  When saving a relationship on an object, the object itself is also saved.

Save a Single Relation

To save a relation, you pass the object you want to relate to, into your current object.

// Get user foo
$u = new User();
$u->where('username', 'foo')->get();

// Get country object for Australia
$c = new Country();
$c->where('name', 'Australia')->get();

// Relate user foo to country Australia
$u->save($c);

Save Multiple Relations

To save multiple relations, you pass an object's all property or an array of objects.

// Get user foo
$u = new User();
$u->where('username', 'foo')->get();

// Get country object for Australia
$c = new Country();
$c->where('name', 'Australia')->get();

// Get a number of books from the year 2000
$b = new Book();
$b->where('year', 2000)->get();

// Get a movie with ID of 5
$m = new Movie();
$m->where('id', 5)->get();

// Relate user foo to all the books
$u->save($b->all);

// Or we could pass everything in one go (it's ok to have a mix of single objects and all lists from objects)
$u->save(array($c, $b->all, $m));

Save a New object and its Relations in a single call

It is important to note that you can save both an object's data and relationships with a single save call. For example, you could save a new object and its relationships all in one go like this:

// Create new User
$u = new User();

// Enter values into required fields
$u->username = "foo";
$u->password = "bar";
$u->email = "foo@bar.com";

// Get country object for Australia
$c = new Country();
$c->where('name', 'Australia')->get();

// Save new user and also save a relationship to the country
$u->save($c);

Save an Existing object and its Relations in a single call

In the same way, you can update an existing records data as well as its relationships with a single save call.

// Get user foo
$u = new User();
$u->where('username', 'foo')->get();

// Change the email
$u->email = "baz@qux.com";

// Get country object for United States
$c = new Country();
$c->where('name', 'United States')->get();

// Update email and update the relationship to country United States
$u->save($c);