Create a new Record using the newRecord() method. You can assign data using
properties, or pass an array of initial data to populate into the Record.
<?php
$thread = $atlas->newRecord(ThreadMapper::CLASS,
[
'title'=>'New Thread Title',
]
);
You can assign a value via a property, which maps to a column name.
<?php
$date = new \DateTime();
$thread->date_added = $date->format('Y-m-d H:i:s');
You can insert a single Record back to the database by using the Atlas::insert()
method. This will use the appropriate Mapper for the Record to perform the
write within a transaction, and capture any exceptions that occur along the way.
<?php
$success = $atlas->insert($thread);
if ($success) {
echo "Wrote the Record back to the database.";
} else {
echo "Did not write the Record: " . $atlas->getException();
}
Inserting a Record with an auto-incrementing primary key will automatically modify the Record to set the last-inserted ID.
Inserting a Record will automatically set the foreign key fields on the native Record, and on all the loaded relationships for that Record.
In the following example, assume a Thread Record has a manyToOne relationship
with an Author Record using the author_id column. The relationship is named
author. (See the section on relationships for more information.)
<?php
$author = $atlas->fetchRecord(AuthorMapper::CLASS, 4);
$thread = $atlas->newRecord(ThreadMapper::CLASS,
[
'title'=>'New Thread Title',
'author'=>$author
]
);
// If the insert is successful, the `author_id` column will automatically be
// set to the Author Record's primary key value. In this case, 4.
$success = $atlas->insert($thread);
echo $thread->author_id; // 4
Note: If the Author Record is new, Atlas will NOT automatically insert the new Author and set the foreign key on the new Author Record via the
insert()method. This can, however, be achieved using thepersist()method. This is discussed later in this chapter.
The following will fail.
<?php
$author = $atlas->newRecord(AuthorMapper::CLASS,
[
'first_name'=>'Sterling',
'last_name'=>'Archer'
]
);
$thread = $atlas->newRecord(ThreadMapper::CLASS,
[
'title'=>'New Thread Title',
'author'=>$author
]
);
// Insert will not create the related Author Record. Use persist() instead.
$success = $atlas->insert($thread);
Updating an existing record works the same as insert().
<?php
// fetch an existing record by primary key
$thread = $atlas->fetchRecord(ThreadMapper::CLASS, 3);
// Modify the title
$thread->title = 'This title is better than the last one';
// Save the record back to the database.
$success = $atlas->update($thread);
if ($success) {
echo "Wrote the Record back to the database.";
} else {
echo "Did not write the Record: " . $atlas->getException();
}
As with insert(), foreign keys are also updated, but only for existing related
records.
<?php
$thread = $atlas->fetchRecord(ThreadMapper::CLASS, 3);
$author = $atlas->fetchRecord(AuthorMapper::CLASS, 4);
// Modify the author
$thread->author = $author;
// Save the record back to the database.
$success = $atlas->update($thread);
if ($success) {
echo "Wrote the Record back to the database.";
} else {
echo "Did not write the Record: " . $atlas->getException();
}
Deleting a record works the same as inserting or updating.
<?php
$thread = $atlas->fetchRecord(ThreadMapper::CLASS, 3);
$success = $atlas->delete($thread);
if ($success) {
echo "Removed record from the database.";
} else {
echo "Did not remove the Record: " . $atlas->getException();
}
If you like, you can persist a Record and all of its loaded relationships (and
all of their loaded relationships, etc.) back to the database using the Atlas
persist() method. This is good for straightforward relationship structures
where the order of write operations does not need to be closely managed.
The persist() method will:
<?php
$success = $atlas->persist($record);
if ($success) {
echo "Wrote the Record and all of its relateds back to the database.";
} else {
echo "Did not write the Record: " . $atlas->getException();
}
As with insert and update, this will automatically set the foreign key fields on the native Record, and on all the loaded relationships for that Record.
If a related field is not loaded, it cannot be persisted automatically.
Note that whether or not the Row for the Record is inserted/updated/deleted, the
persist() method will still recursively traverse all the related fields and
persist them as well.
The delete() method will not attempt to cascade deletion or nullification
across relateds at the ORM level. Your database may have cascading set up at the
database level; Atlas has no control over this.
You may also mark records for deletion and they will be removed from the database
after a transaction is completed via persist().
<?php
$thread = $atlas->fetchRecord(ThreadMapper::CLASS, 3);
// Mark the record for deletion
$thread->markForDeletion();
$atlas->persist($thread);
You can also mark several related Records for deletion and when the native Record is persisted, they will be deleted from the database.
<?php
// Assume a oneToMany relationship between a thread and its comments
// Select the thread and related comments
$thread = $atlas->fetchRecord(ThreadMapper::CLASS, 3,
[
'comments'
]
);
// Mark each related comment for deletion
foreach ($thread->comments as $comment) {
$comment->markForDeletion();
}
// Persist the thread and the comments are also deleted
$atlas->persist($thread);