ORM Methods¶
MoodleORM has twelve (12) public methods that will help you to work with complex data.
The main public methods are:
* export_data()
* save() and,
* commit()
export_data() Method¶
The export_data()
method allows you to extract an array of the data that was read from the database,
into a format that is perfectly compatible with the ORM’s save()
method.
Note
The export_data()
will only return data if the ORM’s save()
method was not previously invoked, and the ORM’s registry is clean.
The format of the data is fairly straightforward. Each data stucture has a repositoryname
index, which must
match the name of the table in the classmap array. The data
index contains the fields as defined in the
table schema and in the corresponding properties of the Moodle entity. Finally, the array must either contain an
entityid
index, that holds the id of the existing entity, or an entityuuid
index if the entity is to be
inserted into the database. In order to avoid collisions, it is recommended to use the
bin2hex(random_bytes(20))
PHP functions to generate the UUID. If a new entity has a newly created parent
entity, it will also be necessary to create a parentuuid
index and insert the corresponding UUID at this
index of the array. Here is an example of a new entity that must be created:
$simulationid = $course->cmid;
$uuid = bin2hex(random_bytes(20));
$data[] = [
'repositoryname' => 'simulation_wave',
'entityuuid' => $uuid,
'parentuuid' => null,
'data' => [
'name' => 'Wave 2',
'description' => 'Second wave.',
'simulationid' => $simulationid,
],
];
An example of the array’s structure when extracting the data from the database would be something like the following example:
$data[] = [
'entityid' => 4,
'repositoryname' => 'simulation_wave',
'data' => [
'name' => 'Wave 2',
'description' => 'Second wave.',
'simulationid' => 1,
],
];
Updating is a question of modifying elements of an entity in the array. Deleting is simply a question of removing the appropriate element from the array.
save() Method¶
Once the data array is set, it will be necessary to invoke the save()
method, in order for the ORM to start
tracking changes in the entities. Its Unit of Work will start building a registry of “dirty” entities, that will
then be used to define the elements of the transaction that will be sent to the database when invoking its
commit()
method.
commit() Method¶
The commit()
method will clean the dirty registry of entities by running an SQL transaction, with all of the
required queries, in order to save the new data to the database.
Note
The commit()
method will automatically be invoked by the ORM’s destructor method if it falls out of scope of the current PHP script.
Other ORM Methods¶
The ORM comes with the following helper methods:
get_maintable_settings()
, which gives access to the main read-only table’s data, based on the givenid
,
get_classmap()
, which makes it possible to get the ORM’s currently used classmap,
get_registry()
, which will return an array containing all of the data, including Moodle entities, that were initially read from the database,
get_dirty()
, which will return an array of all of the keys of the new data that require a CRUD action in order to save them to the database,
get_stage()
, which will return an array of all of the data, including Moodle entities, that were included in the commit (database transaction),
is_committed()
, which will return true if a database transaction was attempted, and false if no persistence action was taken, and
is_dirty()
, which will return true if thesave()
method was invoked with new data.
There are also two helper methods for adding or removing foreign key constraints on the foreign keys. These methods are:
try_add_cascade_delete_check()
, and
try_remove_cascade_delete_check()
.
Note
For a working example on how to start building a Moodle Form with MoodleORM on the back end (without the templates, the CSS, or the JS), please see the ‘dist’ folder included with each release of MoodleORM.