Source API for the «PorteRecord» class

Base class to wrap a database record.

The class can be used as is or may be extended to define user functionnalities or alter existing behaviors.

Exemple to instantiate a new record:

$record = new PorteRecord();
// Next line not required if porte is loaded in static mode
$record->setPorte($porte);

Exemple to instantiate a new record from Porte:

$porte->{$record_type};

Exemple to instantiate a new record from PorteTable:

$porte->tables->{$record_type}->load();

Exemple to retrieve an existing record:

$record = new PorteRecord();
// Next line not required if porte is loaded in static mode
$record->setPorte($porte);
$record->load($recordId);

Exemples to retrieve an existing record from Porte:

$porte->{$record_type}($recordId);
$porte->$record_type}('field=:field_value',array('field_value'=>'my value');

Exemples to retrieve an existing record from PorteTable:

$porte->tables->{$record_type}->find($recordId);
$porte->tables->{$record_type}->find('field=:field_value',array('field_value'=>'my value');

PHP magic methods

__get

Magically get a record property defined in the model as well as the record "porte", "events", "table" and "type" properties.

__set

Magically set a record property defined in the model as well as the record "porte", "events", "table" and "type" properties.

__isset

Check wether a record property is set or not.

__call

Provide various methods by default.

Method be be user defined in the record class in which case the magic get method will be bypassed and it will be the responsibility of the developer to implement the right logic.

It is possible to retrieve all the dynamic methods of a record with the following code:

$record->porte->models($record->type)->getMethods();

The get family

  • get + CamelCaseProperty (?find_options)
  • Sample:
    property my_username will be map to getMyUsername()
    association my_files will be map to getMyFiles()

The set family

  • set + CamelCaseProperty (mixed parameter)
  • Sample:
    property my_username will be map to setMyUsername('my username')
    property my_gender will be map to setMyGender(aGender)

The add family

  • add + SingularCamelCaseProperty (object)
  • Sample:
    association my_groups will be map to addMyGroup(aGroup)
    association my_groups will be map to addMyGroups(array(aGroup1,aGroup2))

The delete family:

  • delete + CamelCaseProperty (mixed)
    delete + SingularCamelCaseProperty (int||numeric||object)

We do not yet support cascading removal, only the association between two records is removed.
Singular versions of delete take a primary key value or an object as parameter.
Plural version of delete may take a list of primary key values, and array of primary key values, an array of objects or an empty parameter.

The date family

  • getProperty() return a string formated as yyyy-mm-dd hh:mm:ss
    getPropertyAsSeconds() return as unix time stamp integer

The count family (used in many-to-many and one-to-many relationships)

  • count + CamelCaseProperty(?find_options)

Public methods

get

Retrieve a property value.

set

Set a new property value

load

The load method allows the initialisation of the current object based on a database record retrieved from its primary key value or from on a where query statement.

Loading a record from its primary key:

$user->load(1);
$user->load('1');

Loading a record from a "where" query statement:

$user->load('username=? AND password=?',array(1=>'my username',2=>'my password'));
$user->load('username=:username',array('username'=>'my username'));

Loading a record from an array (similar to calling the method "fromArray"):

$user->load(array('id'=>1));

Options include:

  • no_exception Return boolean false instead of throwing an exception if record does not exist
  • force Force the record retrieval from the database instead of lazy loading its data when we really need them
return
PorteRecord
Current record
fromDb

Map database data to the record, reserved for internal usage.

reload

Reloading the current record by reseting its internal.

If record is new, the method act as an alias to the reset method otherwise it will reset all the internal values and update them with the ones present in the database

Options include:
throws_exception Throws an exception on error

return
PorteRecord
The current record or false on error
getIdentifier

Return the primary key value or "false" if new record.

isNew

Check whether the record exist in the database or not.

return
boolean
True is record exist in database, otherwise false
hasChanged

This method is not yet documented.

save

Save a record in the database by performing a create statement if record is not yet present and an update statement if record already present in database.

Options may include

  • force_insert Carefull, not tested yet
return
Id
of the record
delete

Delete this record from the database. All the properties previously stored in the object are removed by calling the reset function on success.
When a instance is delete, all the associated references to it are removed. However, other instances of the same record are loaded, their associations will not be removed, calling the save function on those instances might lead to incorrect results.

return
PorteRecord
Current reseted instance
reset

Reinitialise the object with empty values. Calling the save method after the reset method will create a new record.

return
PorteRecord
The current record
getPorte

Access the Porte instance

return
Porte
setPorte

Set the Porte instance.

return
PorteRecord
Current record
$con[optional]
Porte, Porte
instance or null if static mode
fromArray

Take an array as parameter and map the object from it. This function does set associations as well so be carefull not overwriting your existing associations.

Available options:

  • relax
    If true, every field present in the array parameter will be mapped to the object,
    even if not defined in meta.
  • dont_encode_password
    Disable password encoding.
  • encoding
    Define the encoding of the strings present in the source array.
  • null_if
    Substitute the value to null if equals to null_if value if it is a string or if in array if
    it is an array. For exemple the option "null if empty" would be written "null_if"=>"".
return
PorteRecord
Current record
Array
$array, made
of field=>value used to map our record
Various
$options, options
used to alter the behavior of the mapping
toArray

Convert this record into an array with the relationship preserved and converted as well.
Usefull to transform the resulting array into a json string for example.
The "toArray" method may contain an optional argument, an array of options.
Default options may be set for a given type of record by filling the model table configuration with the property "to_array"

Calling the method with no argument:

$record->toArray();

Calling the method with options:

$record->toArray(array('relax'=>true));

Available options:

  • relax (boolean)
    If true, every field present in the object will be returned, even if not defined in meta or if type is 'password'
  • include (array||string)
    If present, only the properties present in include will be returned
  • exclude (array||string)
    If present, properties present in exclude will not be returned
  • depth (int)
    Define how deep in the association hierarchy the array convertion shall go
  • by_type (array)
    Merge options for provided type of records defined as keys in the array
  • by_property (array)
    Merge options for provided properties defined as keys in the array
  • seconds
    Return dates in seconds (Unix timestamp)
  • milliseconds
    Return dates in milliseconds (Unix timestamp)

Using the "extended" and "include" options:

$user->toArray(array(
    'extended'=>true,
    'include'=>array(
        'id_fournisseur',
        'title'=>true,
        'logo',
        'group'=>array(
            'id_offre',
            'title'
        ),
    ),
));
destroy

Clean up potential circular references before disposing the record.