\Disco\classesRecord

Abstract Record class. Treats an object as a table row (Active Record/ORM). Use the Disco CLI tool to generate your records.

Records:

  • protects against missing ids
  • making sure fields conform to the data type set forth by the table
  • Protect against attempting to update fields that don't exist
  • only updating changed fields to prevent redundancy and database load

Records throw

Summary

Methods
Properties
Constants
__construct()
setValidationLevel()
__get()
__set()
__isset()
__unset()
offsetGet()
offsetSet()
offsetExists()
offsetUnset()
allowKeyUpdates()
update()
delete()
insert()
upsert()
getFields()
fetchMissing()
fetch()
primaryKeys()
primaryKeysWithValidation()
validateFields()
validateField()
diff()
exists()
convertEmptyStringsToNull()
find()
findAll()
validate()
autoIncrementField()
getFieldNames()
getRequiredFieldNames()
No public properties found
VALIDATION_STRICT
VALIDATION_EMIT
VALIDATION_LOOSE
No protected methods found
$model
$fieldDefinitions
$autoIncrementField
$fields
N/A
No private methods found
$validationLevel
$cache
$initial_primary_keys
$allowKeyUpdates
$numericalRanges
$regexHelpers
N/A

Constants

VALIDATION_STRICT

VALIDATION_STRICT

VALIDATION_EMIT

VALIDATION_EMIT

VALIDATION_LOOSE

VALIDATION_LOOSE

Properties

$model

$model : string

Type

string — The model that owns the record.

$fieldDefinitions

$fieldDefinitions : array

Type

array — The fields defintions for the record.

$autoIncrementField

$autoIncrementField : boolean|string

Type

boolean|string — The autoincrement field name.

$fields

$fields : array

Type

array — The fields of the record.

$validationLevel

$validationLevel : integer

Type

integer — The level of validation to apply to columns when perfomring data manipulation.

$cache

$cache : array

Type

array — A Cache of the fields of the record.

$initial_primary_keys

$initial_primary_keys : boolean|array

Type

boolean|array — The primary keys that were present when the record was constructed. Only used when allowKeyUpdates is set to true and a record is updated and some of the records primary keys have changed. This prevents the record from attempting to update its self with the new primary key values, which will result in the updates where statement using conditions pointing to a record that doesn't exist, or is wrong all togethor.

$allowKeyUpdates

$allowKeyUpdates : boolean

Type

boolean — Allow primary keys of the record to be updated?

$numericalRanges

$numericalRanges : array

Type

array — Store mins and maxes for SQL column types. Used when validating fields of records.

$regexHelpers

$regexHelpers : array

Type

array — Helpers for validating date and time.

Methods

__construct()

__construct(array  $fields = array(), boolean  $cache = false) : void

Set the intital fields of the record. Performs an array intersection to only take fields that exist on the model from the passed fields.

Parameters

array $fields

Fields of the record.

boolean $cache

Whether to cache the initial passed fields.

setValidationLevel()

setValidationLevel(integer  $lvl) 

Set the level of validation applied to record columns, based on one of the class constants: - VALIDATION_LOOSE - VALIDATION_EMIT - VALIDATION_STRICT

Parameters

integer $lvl

The validation level.

__get()

__get(string  $key) : mixed

Get a field of the record using object syntax.

Parameters

string $key

The key.

Returns

mixed

__set()

__set(string  $key, mixed  $value) 

Set a field of the record using object syntax.

Parameters

string $key

The key.

mixed $value

The value.

__isset()

__isset(string  $key) : boolean

Determine whether a field exists in the record.

Parameters

string $key

The key.

Returns

boolean

__unset()

__unset(string  $key) 

Delete a field from the record (Set it to null).

Parameters

string $key

The key.

offsetGet()

offsetGet(string  $key) : mixed

Get a field of the record using array access syntax.

Parameters

string $key

The key.

Returns

mixed

offsetSet()

offsetSet(string  $key, mixed  $value) 

Set a field of the record using array access syntax.

Parameters

string $key

The key.

mixed $value

The value.

offsetExists()

offsetExists(string  $key) : boolean

Determine whether a field exists in the record.

Parameters

string $key

The key.

Returns

boolean

offsetUnset()

offsetUnset(string  $key) 

Delete a field from the record (Set it to null).

Parameters

string $key

The key.

allowKeyUpdates()

allowKeyUpdates(boolean  $allow = true) : void

Allow primary keys of the record to be updated. This is by default false, and will be made false again after every update.

Parameters

boolean $allow

update()

update(boolean  $using_only_auto_increment_key = false) : boolean

Update the changed fields in the record.

Parameters

boolean $using_only_auto_increment_key

Perform the update using only the auto-increment key, regardless of other primary keys specified by the record.

Throws

\Disco\exceptions\RecordId

When primary keys are null.

\Disco\exceptions\RecordValidation

When a field fails validation.

Returns

boolean

delete()

delete(boolean  $using_only_auto_increment_key = false) : boolean

Delete the record.

Parameters

boolean $using_only_auto_increment_key

Perform the delete using only the auto-increment key, regardless of other primary keys specified by the record.

Throws

\Disco\exceptions\RecordId

When primary keys are null.

Returns

boolean

insert()

insert() : integer

Create the record. If the record has an Auto Increment Primary Key it will be set on the record with the newly created id.

Throws

\Disco\exceptions\RecordValidation

When a field fails validation or is required and missing.

Returns

integer

upsert()

upsert() : boolean|integer

INSERT or UPDATE the record based on the presense or lack there of the records primary keys.

Throws

\Disco\exceptions\Record

When required fields are null.

Returns

boolean|integer

getFields()

getFields() : array

Get all the set fields of the record.

Returns

array —

An assoc array of the fields and their values.

fetchMissing()

fetchMissing() : boolean|array

Get and set all the fields of the record that are not currently set. Must have the primary keys defined.

Throws

\Disco\exceptions\RecordId

When ids are null.

Returns

boolean|array —

False if no missing fields. An assoc array of the missing fields and their values otherwise.

fetch()

fetch(null|string|array  $fields = array()) : array

Get and set fields of the record. Must have the primary keys defined.

Parameters

null|string|array $fields

The fields to fetch and set on the record. If null is passed all fields will be fetched.

Throws

\Disco\exceptions\RecordId

When ids are null.

\Disco\exceptions\RecordNonExistent

When the record doesn't exist.

\Disco\exceptions\Record

When multiple records are returned.

Returns

array —

An assoc array of the records field and their values.

primaryKeys()

primaryKeys() : array

Get the primary keys and their current values from the fields.

Returns

array —

The primary keys.

primaryKeysWithValidation()

primaryKeysWithValidation() : array

Get the primary keys and their current values from the fields, validating each one. If not all keys are present but the auto increment key is present and valid return just that.

Throws

\Disco\exceptions\RecordId

When any of the primary keys are null.

Returns

array —

The primary keys.

validateFields()

validateFields() : void

Validate the current fields of the record.

Throws

\Disco\exceptions\RecordValidation

When a field doesn't exist or a field fails validation.

validateField()

validateField(string  $key) : boolean

Validate a single field of the record.

Parameters

string $key

The field name to validate.

Returns

boolean —

The field passed validation.

diff()

diff() : array

Get the fields that have changed since the instantiation of the record or the last update or insert.

Returns

array —

The fields that have changed.

exists()

exists() : boolean

Determine whether a record exists based on its current primary keys.

Returns

boolean —

The record exists

convertEmptyStringsToNull()

convertEmptyStringsToNull(null|string|array  $fields = array()) : void

Convert a single field, an array of fields, or all fields which are empty strings to null values.

Parameters

null|string|array $fields

An optional subset of fields or single field to convert.

Throws

\Disco\exceptions\RecordValidation

If a passed field fails to exist.

find()

find(array  $where, null|string|array  $select = null) : boolean|mixed

Find the first record that matches the where condition.

Parameters

array $where

The conditions used to find the record.

null|string|array $select

The fields to select from the record.

Returns

boolean|mixed —

Return false if the record wasn't found, otherwise return an instance of the record.

findAll()

findAll(array  $where, null|string|array  $select = null) : array

Find the all record that match the where condition.

Parameters

array $where

The conditions used to find the records.

null|string|array $select

The fields to select from the records.

Returns

array —

An array of the records found.

validate()

validate(  $field,   $v) : boolean

Determine if a value is valid for a records particular field.

Parameters

$field
$v

Returns

boolean —

Did it validate?

autoIncrementField()

autoIncrementField() 

Get the name of the autoincrement field.

getFieldNames()

getFieldNames() : array

Get the fields of the record.

Returns

array —

The fields.

getRequiredFieldNames()

getRequiredFieldNames() : array

Get the required fields of the record (cannot be null) with the exception of the autoincrement field.

Returns

array —

The fields.