Basic Saving

Examples of simple use cases for writing data.

Basic Updates

In addition to basic saving of entities and collections demonstrated below, more complex requirements can be catered for using custom queries.

If you have loaded an entity using Objectiphy, and made some changes to its property values which you want to save, you can do so by calling the saveEntity method (which returns the number of records affected by the save):

$person = $repository->find(123);
$person->lastName = 'McBoatface';
$recordsAffected = $repository->saveEntity($person);

By default, Objectiphy keeps track of changes to the entity and only saves the things that have changed. If it cannot determine whether a field has changed (eg. if the cache is cleared, or you load and populate the entity outside of Objectiphy), it will save it. If you set the DISABLE_ENTITY_CACHE config option to true, this tracking will be disabled - meaning all properties will be saved.

If your entity has child objects, they will usually be saved when the parent entity is saved. If you don't want that to happen, you can either change the default behaviour via the SAVE_CHILDREN_BY_DEFAULT config option, or pass false to the second argument when calling the saveEntity method (this can provide performance improvements, as there will be no need to check whether any child objects need updating):

$person = $repository->find(123);
$person->user->username = 'Something'; //Will not be saved
$person->lastName = 'McBoatface';
$repository->saveEntity($person, false);

Basic Inserts

Similarly, you can insert a new entity by calling the same method:

$person = new Person();
$person->firstName = 'Slartibartfast';
$repository->saveEntity($person);

return $person->id;

If the entity has a primary key (which you can specify by setting isPrimaryKey to true on the column mapping), and is set to auto-increment in the database, Objectiphy will run an insert query and populate the primary key with the value assigned by the database.

If you want to generate your own primary key value, rather than auto-increment, you can either set the autoIncrement attribute to false on the column mapping (this is the recommended approach as you can just set it and forget it), or set the third parameter to true when you call the saveEntity method. In that case, Objectiphy will perform an INSERT ... ON DUPLICATE KEY UPDATE ... query - which means that the entity will be inserted if it does not exist, or updated if it does:

$person = new Person();
$person->employeeNumber = 'A1234'; //Primary key
$person->lastName = 'Skywalker';
$repository->saveEntity($person, true, true);

Saving Relationships

If you add a new child object to an existing entity, calling saveEntity will typically insert the record for the new child object (as well as updating any other changed fields on the parent entity):

$person = $repository->find(123);
$person->user = new User();
$person->user->username = 'User123';
$repository->saveEntity($person);

return $person->user->id; //Newly inserted user

There may be times when you want to associate an existing child object to a parent entity. If you have an instance of the child object to hand, you can just assign it to the property on the parent entity and save the parent entity. However, if you do not have an instance of the child object, just its primary key value, you can save the relationship without needing to load the child object from the database by creating an object reference:

$person = $repository->find(123);
$user = $repository->getObjectReference(User::class, 321);
$person->user = $user;
$repository->saveEntity($person);

//User with primary key 321 is now associated with $person

You can delete a relationship simply by setting the property value to null and calling saveEntity:

$person = $repository->find(123);
$person->user = null;
$repository->saveEntity($person);

The same principle applies when dealing with one-to-many associations - you can add or remove objects or object references and save the parent entity.

Counting Records Affected

Where child objects are involved, saving an entity can result in records being both inserted and updated, or both updated and deleted. In this case, you can get the individual count of inserts, updates, and deletes, by passing variables by reference to the relevant arguments of the saveEntity method:

$person = $repository->find(123);
$person->user = null;
$person->lastName = 'Smith';
$insertCount = 0;
$updateCount = 0;
$deleteCount = 0;
$totalCount = $repository->saveEntity(
    $person, 
    true, 
    false, 
    null, 
    $insertCount,
    $updateCount, 
    $deleteCount
);

//$insertCount = 0
//$updateCount = 1
//$deleteCount = 1
//$totalCount = 2

Note that these counts relate to database records, not entities. So in the above example, we are assuming that orphan removal is applied to the relationship between Person and User, and having set the user to null, this will have caused one update (the user_id on the person table updated to null), and one delete (the orphaned user record being deleted).

Transactions

Inserts and updates are wrapped in transactions, so if you try to insert a parent entity, and there is a problem inserting one of the child entities, the whole operation will be aborted. Of course this will only work if the tables support transactions (so it will not work for MyISAM tables, for example).

You can also manage transactions yourself, for cases where you want to perform several operations in a single transaction. To do this, call beginTransaction on the repository, followed by either commit or rollback. If you have started your own transaction with beginTransaction, Objectiphy will not start any transactions of its own, and will not commit your transaction, so you are in complete control.

Advanced Saving

You can perform more advanced save operations (eg. updating certain properties on multiple records that match certain criteria) using queries that you create with the query builder.