core\persistent Class Reference

Inheritance diagram for core\persistent:

Public Member Functions
	__construct ($id=0, stdClass $record=null)
	Create an instance of this class.
	create ()
	Insert a record in the DB.
	delete ()
	Delete an entry from the database.
	from_record (stdClass $record)
	Populate this class with data from a DB record.
	get ($property)
	Data getter.
	get_errors ()
	Returns the validation errors.
	is_valid ()
	Returns whether or not the model is valid.
	read ()
	Load the data from the DB.
	save ()
	Saves the record to the database.
	set ($property, $value)
	Data setter.
	set_many (array $values)
	Data setter for multiple properties.
	to_record ()
	Create a DB record from this class.
	update ()
	Update the existing record in the DB.
	validate ()
	Validates the data.

Static Public Member Functions
static	count_records (array $conditions=array())
	Count a list of records.
static	count_records_select ($select, $params=null)
	Count a list of records.
static	extract_record ($row, $prefix=null)
	Extract a record from a row of data.
static	get_formatted_properties ()
	Gets all the formatted properties.
static	get_record (array $filters=[], int $strictness=IGNORE_MISSING)
	Load a single record.
static	get_records ($filters=array(), $sort='', $order='ASC', $skip=0, $limit=0)
	Load a list of records.
static	get_records_select ($select, $params=null, $sort='', $fields=' *', $limitfrom=0, $limitnum=0)
	Load a list of records based on a select query.
static	get_sql_fields ($alias, $prefix=null)
	Return the list of fields for use in a SELECT clause.
static	has_property ($property)
	Returns whether or not a property was defined.
static	is_property_required ($property)
	Returns whether or not a property is required.
static	properties_definition ()
	Get the properties definition of this model.
static	properties_filter (stdClass $record)
	For a given record, return an array containing only those properties that are defined by the persistent.
static	record_exists ($id)
	Check if a record exists by ID.
static	record_exists_select ($select, array $params=null)
	Check if a records exists.

Public Attributes
string const	TABLE = null
	The table name.

Protected Member Functions
	after_create ()
	Hook to execute after a create.
	after_delete ($result)
	Hook to execute after a delete.
	after_update ($result)
	Hook to execute after an update.
	before_create ()
	Hook to execute before a create.
	before_delete ()
	Hook to execute before a delete.
	before_update ()
	Hook to execute before an update.
	before_validate ()
	Hook to execute before the validation.
	raw_get ($property)
	Internal Data getter.
	raw_set ($property, $value)
	Data setter.
	verify_protected_methods ()
	This function is used to verify that custom getters and setters are declared as protected.

Static Protected Member Functions
static	define_properties ()
	Return the custom definition of the properties of this model.
static	get_property_default_value ($property)
	Gets the default value for a property.
static	get_property_error_message ($property)
	Gets the error message for a property.

Constructor & Destructor Documentation

__construct()

core\persistent::__construct	(		$id = 0,
		stdClass	$record = null )

Create an instance of this class.

Parameters

int	$id	If set, this is the id of an existing record, used to load the data.
stdClass	$record	If set will be passed to self::from_record().

Reimplemented in tool_dataprivacy\purpose.

Member Function Documentation

after_create()

core\persistent::after_create ( )

protected

Hook to execute after a create.

This is only intended to be used by child classes, do not put any logic here!

Return values

void

Reimplemented in core_reportbuilder\local\models\audience, core_reportbuilder\local\models\column, core_reportbuilder\local\models\filter, core_reportbuilder\local\models\report, core_reportbuilder\local\models\schedule, quizaccess_seb\seb_quiz_settings, tool_dataprivacy\contextlevel, tool_dataprivacy\purpose, and tool_dataprivacy\purpose_override.

after_delete()

core\persistent::after_delete ( $result )

protected

Hook to execute after a delete.

This is only intended to be used by child classes, do not put any logic here!

Parameters

bool

$result

Whether or not the delete was successful.

Return values

void

Reimplemented in core_competency\competency, core_competency\course_competency, core_competency\course_module_competency, core_competency\plan_competency, core_competency\template_competency, core_reportbuilder\local\models\audience, core_reportbuilder\local\models\column, core_reportbuilder\local\models\filter, core_reportbuilder\local\models\report, core_reportbuilder\local\models\schedule, and tool_policy\policy_version.

after_update()

core\persistent::after_update ( $result )

protected

Hook to execute after an update.

This is only intended to be used by child classes, do not put any logic here!

Parameters

bool

$result

Whether or not the update was successful.

Return values

void

Reimplemented in core_competency\competency, core_competency\template, core_reportbuilder\local\models\audience, core_reportbuilder\local\models\column, core_reportbuilder\local\models\filter, core_reportbuilder\local\models\report, core_reportbuilder\local\models\schedule, quizaccess_seb\seb_quiz_settings, tool_dataprivacy\contextlevel, tool_dataprivacy\purpose, tool_dataprivacy\purpose_override, and tool_policy\policy_version.

before_create()

core\persistent::before_create ( )

protected

Hook to execute before a create.

Please note that at this stage the data has already been validated and therefore any new data being set will not be validated before it is sent to the database.

This is only intended to be used by child classes, do not put any logic here!

Return values

void

Reimplemented in quizaccess_seb\seb_quiz_settings, and quizaccess_seb\template.

before_delete()

core\persistent::before_delete ( )

protected

Hook to execute before a delete.

This is only intended to be used by child classes, do not put any logic here!

Return values

void

Reimplemented in core_reportbuilder\local\models\report, mod_bigbluebuttonbn\recording, quizaccess_seb\seb_quiz_settings, tool_dataprivacy\contextlevel, tool_dataprivacy\purpose, and tool_dataprivacy\purpose_override.

before_update()

core\persistent::before_update ( )

protected

Hook to execute before an update.

Please note that at this stage the data has already been validated and therefore any new data being set will not be validated before it is sent to the database.

This is only intended to be used by child classes, do not put any logic here!

Return values

void

Reimplemented in mod_bigbluebuttonbn\recording, quizaccess_seb\seb_quiz_settings, and quizaccess_seb\template.

before_validate()

core\persistent::before_validate ( )

protected

Hook to execute before the validation.

This hook will not affect the validation results in any way but is useful to internally set properties which will need to be validated.

This is only intended to be used by child classes, do not put any logic here!

Return values

void

Reimplemented in core\oauth2\issuer, core_competency\competency, core_competency\competency_framework, core_competency\course_competency, core_competency\course_module_competency, core_competency\plan, core_competency\plan_competency, core_competency\template, core_competency\template_competency, and quizaccess_seb\seb_quiz_settings.

count_records()

static core\persistent::count_records ( array $conditions = array() )

static

Count a list of records.

Parameters

array

$conditions

An array of conditions.

Return values

int

count_records_select()

static core\persistent::count_records_select ( $select, $params = null )

static

Count a list of records.

Parameters

string	$select
array	$params

Return values

int

create()

core\persistent::create ( )

final

Insert a record in the DB.

Return values

static

define_properties()

static core\persistent::define_properties ( )

staticprotected

Return the custom definition of the properties of this model.

Each property MUST be listed here.

The result of this method is cached internally for the whole request.

The 'default' value can be a Closure when its value may change during a single request. For example if the default value is based on a $CFG property, then it should be wrapped in a closure to avoid running into scenarios where the true value of $CFG is not reflected in the definition. Do not abuse closures as they obviously add some overhead.

Examples:

array( 'property_name' => array( 'default' => 'Default value', // When not set, the property is considered as required. 'message' => new lang_string(...), // Defaults to invalid data error message. 'null' => NULL_ALLOWED, // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOW_ALLOWED or NULL_ALLOWED. 'type' => PARAM_TYPE, // Mandatory. 'choices' => array(1, 2, 3) // An array of accepted values. ) )

array( 'dynamic_property_name' => array( 'default' => function() { return $CFG->something; }, 'type' => PARAM_INT, ) )

Return values

array

Where keys are the property names.

Reimplemented in auth_oauth2\linked_login, core\oauth2\access_token, core\oauth2\endpoint, core\oauth2\issuer, core\oauth2\system_account, core\oauth2\user_field_mapping, core_badges\oauth2\badge_backpack_oauth2, core_competency\competency, core_competency\competency_framework, core_competency\course_competency, core_competency\course_competency_settings, core_competency\course_module_competency, core_competency\evidence, core_competency\plan, core_competency\plan_competency, core_competency\related_competency, core_competency\template, core_competency\template_cohort, core_competency\template_competency, core_competency\user_competency, core_competency\user_competency_course, core_competency\user_competency_plan, core_competency\user_evidence, core_competency\user_evidence_competency, core_customfield\category, core_customfield\data, core_customfield\field, core_files\conversion, core_payment\account, core_payment\account_gateway, core_reportbuilder\local\models\audience, core_reportbuilder\local\models\column, core_reportbuilder\local\models\filter, core_reportbuilder\local\models\report, core_reportbuilder\local\models\schedule, mod_bigbluebuttonbn\recording, quizaccess_seb\seb_quiz_settings, quizaccess_seb\template, repository_onedrive\access, tool_cohortroles\cohort_role_assignment, tool_dataprivacy\category, tool_dataprivacy\context_instance, tool_dataprivacy\contextlevel, tool_dataprivacy\contextlist_context, tool_dataprivacy\data_request, tool_dataprivacy\dataprivacy_contextlist, tool_dataprivacy\expired_context, tool_dataprivacy\purpose, tool_dataprivacy\purpose_override, tool_dataprivacy\request_contextlist, and tool_policy\policy_version.

delete()

core\persistent::delete ( )

final

Delete an entry from the database.

Return values

bool	True on success.

extract_record()

static core\persistent::extract_record ( $row, $prefix = null )

static

Extract a record from a row of data.

Most likely used in combination with self::get_sql_fields(). This method is simple enough to be used by non-persistent classes, keep that in mind when modifying it.

e.g. persistent\extract_record($row, 'user'); should work.

Parameters

stdClass	$row	The row of data.
string	$prefix	The prefix the data fields are prefixed with, defaults to the table name followed by underscore.

Return values

stdClass

The extracted data.

from_record()

core\persistent::from_record ( stdClass $record )

final

Populate this class with data from a DB record.

Note that this does not use any custom setter because the data here is intended to represent what is stored in the database.

Parameters

stdClass

$record

A DB record.

Return values

static

get()

core\persistent::get ( $property )

final

Data getter.

This is the main getter for all the properties. Developers can implement their own getters (get_propertyname) and they will be called by this function. Custom getters can use raw_get to get the raw value. Internally this is not used by self::to_record() or self::from_record() because the data is not expected to be validated or changed when reading/writing raw records from the DB.

Parameters

string

$property

The property name.

Return values

mixed

get_errors()

core\persistent::get_errors ( )

final

Returns the validation errors.

Return values

array

get_formatted_properties()

static core\persistent::get_formatted_properties ( )

staticfinal

Gets all the formatted properties.

Formatted properties are properties which have a format associated with them.

Return values

array

Keys are property names, values are property format names.

get_property_default_value()

static core\persistent::get_property_default_value ( $property )

staticfinalprotected

Gets the default value for a property.

This assumes that the property exists.

Parameters

string

$property

The property name.

Return values

mixed

get_property_error_message()

static core\persistent::get_property_error_message ( $property )

staticfinalprotected

Gets the error message for a property.

This assumes that the property exists.

Parameters

string

$property

The property name.

Return values

lang_string

get_record()

static core\persistent::get_record ( array $filters = [], int $strictness = IGNORE_MISSING )

static

Load a single record.

Parameters

array	$filters	Filters to apply.
int	$strictness	Similar to the internal DB get_record call, indicate whether a missing record should be ignored/return false ({

See also

IGNORE_MISSING}) or should cause an exception to be thrown ({

MUST_EXIST})

Return values

false|static

get_records()

static core\persistent::get_records ( $filters = array(), $sort = '', $order = 'ASC', $skip = 0, $limit = 0 )

static

Load a list of records.

Parameters

array	$filters	Filters to apply.
string	$sort	Field to sort by.
string	$order	Sort order.
int	$skip	Limitstart.
int	$limit	Number of rows to return.

Return values

static[]

get_records_select()

static core\persistent::get_records_select ( $select, $params = null, $sort = '', $fields = '*', $limitfrom = 0, $limitnum = 0 )

static

Load a list of records based on a select query.

Parameters

string	$select
array	$params
string	$sort
string	$fields
int	$limitfrom
int	$limitnum

Return values

static[]

get_sql_fields()

static core\persistent::get_sql_fields ( $alias, $prefix = null )

static

Return the list of fields for use in a SELECT clause.

Having the complete list of fields prefixed allows for multiple persistents to be fetched in a single query. Use self::extract_record() to extract the records from the query result.

Parameters

string	$alias	The alias used for the table.
string	$prefix	The prefix to use for each field, defaults to the table name followed by underscore.

Return values

string

The SQL fragment.

has_property()

static core\persistent::has_property ( $property )

staticfinal

Returns whether or not a property was defined.

Parameters

string

$property

The property name.

Return values

boolean

is_property_required()

static core\persistent::is_property_required ( $property )

staticfinal

Returns whether or not a property is required.

By definition a property with a default value is not required.

Parameters

string

$property

The property name.

Return values

boolean

is_valid()

core\persistent::is_valid ( )

final

Returns whether or not the model is valid.

Return values

boolean

True when it is.

properties_definition()

static core\persistent::properties_definition ( )

staticfinal

Get the properties definition of this model.

Return values

array

properties_filter()

static core\persistent::properties_filter ( stdClass $record )

staticfinal

For a given record, return an array containing only those properties that are defined by the persistent.

Parameters

stdClass

$record

Return values

array

raw_get()

core\persistent::raw_get ( $property )

finalprotected

Internal Data getter.

This is the main getter for all the properties. Developers can implement their own getters but they should be calling self::get() in order to retrieve the value. Essentially the getters defined by the developers would only ever be used as helper methods and will not be called internally at this stage. In other words, do not expect self::to_record() or self::from_record() to use them.

This is protected because it is only for raw low level access to the data fields. Note this function is named raw_get and not get_raw to avoid naming clashes with a property named raw.

Parameters

string

$property

The property name.

Return values

mixed

raw_set()

core\persistent::raw_set ( $property, $value )

finalprotected

Data setter.

This is the main setter for all the properties. Developers can implement their own setters but they should always be calling self::set() in order to set the value. Essentially the setters defined by the developers are helper methods and will not be called internally at this stage. In other words do not expect self::to_record() or self::from_record() to use them.

This is protected because it is only for raw low level access to the data fields.

Parameters

string	$property	The property name.
mixed	$value	The value.

Return values

$this

read()

core\persistent::read ( )

final

Load the data from the DB.

Return values

static

record_exists()

static core\persistent::record_exists ( $id )

static

Check if a record exists by ID.

Parameters

int

$id

Record ID.

Return values

bool

record_exists_select()

static core\persistent::record_exists_select ( $select, array $params = null )

static

Check if a records exists.

Parameters

string	$select
array	$params

Return values

bool

save()

core\persistent::save ( )

final

Saves the record to the database.

If this record has an ID, then self::update() is called, otherwise self::create() is called. Before and after hooks for create() or update() will be called appropriately.

Return values

void

set()

core\persistent::set ( $property, $value )

final

Data setter.

This is the main setter for all the properties. Developers can implement their own setters (set_propertyname) and they will be called by this function. Custom setters should call internal_set() to finally set the value. Internally this is not used self::to_record() or self::from_record() because the data is not expected to be validated or changed when reading/writing raw records from the DB.

Parameters

string

$property

The property name.

Return values

$this

Exceptions

coding_exception

set_many()

core\persistent::set_many ( array $values )

final

Data setter for multiple properties.

Internally calls {

See also

set} on each property

Parameters

array

$values

Array of property => value elements

Return values

$this

to_record()

core\persistent::to_record ( )

final

Create a DB record from this class.

Note that this does not use any custom getter because the data here is intended to represent what is stored in the database.

Return values

stdClass

update()

core\persistent::update ( )

final

Update the existing record in the DB.

Return values

bool	True on success.

validate()

core\persistent::validate ( )

final

Validates the data.

Developers can implement addition validation by defining a method as follows. Note that the method MUST return a lang_string() when there is an error, and true when the data is valid.

protected function validate_propertyname($value) { if ($value !== 'My expected value') { return new lang_string('invaliddata', 'error'); } return true }

It is OK to use other properties in your custom validation methods when you need to, however note they might not have been validated yet, so try not to rely on them too much.

Note that the validation methods should be protected. Validating just one field is not recommended because of the possible dependencies between one field and another,also the field ID can be used to check whether the object is being updated or created.

When validating foreign keys the persistent should only check that the associated model exists. The validation methods should not be used to check for a change in that relationship. The API method setting the attributes on the model should be responsible for that. E.g. On a course model, the method validate_categoryid will check that the category exists. However, if a course can never be moved outside of its category it would be up to the calling code to ensure that the category ID will not be altered.

Return values

array|true

Returns true when the validation passed, or an array of properties with errors.

verify_protected_methods()

core\persistent::verify_protected_methods ( )

finalprotected

This function is used to verify that custom getters and setters are declared as protected.

Persistent properties should always be accessed via get('property') and set('property', 'value') which will call the custom getter or setter if it exists. We do not want to allow inconsistent access to the properties.

---

The documentation for this class was generated from the following file:

• lib/classes/persistent.php