Perforce Chronicle 2012.2/486814
API Documentation
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes

P4Cms_Model Class Reference

Provides a base implementation for data models that have key/value pairs (fields). More...

Inheritance diagram for P4Cms_Model:
P4Cms_ModelInterface P4Cms_Menu_Mixed P4Cms_Navigation_DynamicHandler P4Cms_Navigation_PageTypeHandler P4Cms_PackageAbstract P4Cms_Record_Connected P4Cms_Record_RegisteredType P4Cms_Site P4Cms_Site_Config P4Cms_Widget_Type Site_Model_PullPathGroup System_Model_Info Workflow_Model_State Workflow_Model_Transition

List of all members.

Public Member Functions

 __construct ($values=null)
 Create a new model instance and (optionally) set the field values.
 __get ($field)
 Permits field values to be accessed like public class members.
 __isset ($field)
 Allows isset() to be called on fields.
 __set ($field, $value)
 Permits field values to be set like public class members.
 __unset ($field)
 Allows unset() to be called on fields.
 fromArray ($data)
 Generate a new model instance from an array.
 getDefinedFields ()
 Get the explicitly defined fields.
 getFields ()
 Get all of the model field names.
 getId ()
 Get the id of this record.
 getValue ($field)
 Get a particular field value.
 getValues ()
 Get all of the model field values.
 hasField ($field)
 Check if this model has a specific field.
 hasId ()
 Determine if this record has an id.
 isReadOnlyField ($field)
 Check if the specified field is read only.
 setId ($id)
 Set the id of this record.
 setValue ($field, $value)
 Set a particular field value.
 setValues ($values, $filter=false)
 Set all of the model's values at once.
 toArray ()
 Get the model as an array.
 unsetValue ($field)
 Unset a particular field value.

Static Public Member Functions

static create ($values=null)
 Creates and returns a new instance of this class.

Protected Member Functions

 _getDefaultValue ($field)
 Get a default field value.
 _getFieldProperty ($field, $property)
 Get value of given property from given field definition.
 _getValue ($field)
 Get a raw field value.
 _getValues ()
 Get all of the raw field values.
 _normalizeFields ()
 Normalize fields definition such that after this operation, all fields are defined as:
 _setValue ($field, $value)
 Set raw field value.
 _setValues (array $values)
 Set all of the model's raw values at once.

Protected Attributes

 $_id = null
 $_values = array()

Static Protected Attributes

static $_fields = array()
static $_idField = null

Detailed Description

Provides a base implementation for data models that have key/value pairs (fields).

Each sub-class may define an initial set of fields via the $_fields variable.

Each field is defined by a name and a list of field properties as key/value pairs. For example:

protected static $_fields = array( 'foo' => array( 'property1' => 'value1', 'property2' => 'value2' ) )

If field has no properties, it can be defined in a shorter way just by specifying field's name:

protected static $_fields = array('foo')

Both methods shown above can be arbitrarily combined when defining fields via $_fields variable.

Field's property key must be a string where the following keys are recognized:

'accessor' - value (string) specifies a name of the model's method that will be used to retrieve field's value; accessor methods take no parameters and must return a value

'mutator' - value (string) specifies a name of the model's method that will be used to set field's value; mutator methods must accept a single value parameter and it is recommended that mutator methods return $this to provide a fluent interface

'default' - value specifies default field's value (null will be used if this property is not set)

'readOnly' - value (boolean) specifies if field is read only

Copyright:
2011-2012 Perforce Software. All rights reserved
License:
Please see LICENSE.txt in top-level folder of this distribution.
Version:
2012.2/486814

Constructor & Destructor Documentation

P4Cms_Model::__construct ( $  values = null)

Create a new model instance and (optionally) set the field values.

Parameters:
array$valuesassociative array of keyed field values to load into the model.

Reimplemented in System_Model_Info.

    {
        // normalize fields definition
        $this->_normalizeFields();

        if (is_array($values)) {
            $this->setValues($values);
        }
    }

Member Function Documentation

P4Cms_Model::__get ( $  field)

Permits field values to be accessed like public class members.

Is invoked when reading data from inaccessible members.

Parameters:
string$fieldthe name of the field to get the value of.
Returns:
mixed the value of the field. 
    {
        if ($this->hasField($field)) {
            return $this->getValue($field);
        }

        return null;
    }
P4Cms_Model::__isset ( $  field)

Allows isset() to be called on fields.

Is invoked when calling isset() or empty() on inaccessible members.

Parameters:
string$fieldthe name of the field to call isset() on. 
    {
        $value = $this->getValue($field);
        return isset($value);
    }
P4Cms_Model::__set ( $  field,
$  value 
)

Permits field values to be set like public class members.

Is invoked when writing data to inaccessible members.

Parameters:
string$fieldthe name of the field to set the value of.
mixed$valuethe value to set. 
    {
        if ($this->hasField($field)) {
            $this->setValue($field, $value);
        } else {
            $this->{$field} = $value;
        }
    }
P4Cms_Model::__unset ( $  field)

Allows unset() to be called on fields.

Is invoked when calling unset() is used on inaccessible members.

Parameters:
string$fieldthe name of the field to call unset() on. 
    {
        $this->unsetValue($field);
    }
P4Cms_Model::_getDefaultValue ( $  field) [protected]

Get a default field value.

Returns null if there is no default value for the requested field.

Parameters:
string$fieldthe name of the field to get the value of.
Returns:
mixed|null the default value of the field or null if no default value has been set.

Reimplemented in P4Cms_Content.

    {
        return $this->_getFieldProperty($field, 'default');
    }
P4Cms_Model::_getFieldProperty ( $  field,
$  property 
) [protected]

Get value of given property from given field definition.

Parameters:
string$fieldname of field to get property value for.
string$propertyname of field property to get value for.
Returns:
mixed|null value for given field property or null if property has not been set. 
    {
        return isset(static::$_fields[$field][$property])
            ? static::$_fields[$field][$property]
            : null;
    }
P4Cms_Model::_getValue ( $  field) [protected]

Get a raw field value.

Does not use custom accessor methods. If idField is specified; will utilize 'getId' function.

Parameters:
string$fieldthe name of the field to get the value of.
Returns:
mixed the value of the field.
Exceptions:
P4Cms_Model_Exceptionif the field does not exist.

Reimplemented in P4Cms_Record, and P4Cms_Site_Config.

    {
        // if they are asking for the idField; route through getId
        if (isset(static::$_idField)
            && $field === static::$_idField) {
            return $this->getId();
        }

        // if field has an explicit value, return it.
        if (array_key_exists($field, $this->_values)) {
            return $this->_values[$field];
        }

        return $this->_getDefaultValue($field);
    }
P4Cms_Model::_getValues ( ) [protected]

Get all of the raw field values.

Returns:
array an associative array of raw values. 
    {
        $values = array();
        foreach ($this->getFields() as $field) {
            $values[$field] = $this->_getValue($field);
        }
        return $values;
    }
P4Cms_Model::_normalizeFields ( ) [protected]

Normalize fields definition such that after this operation, all fields are defined as:

<field name>=""> => <array with="" field="" properties>="">

where properties array is blank for fields with no properties. 

    {
        $normalizedFields = array();
        foreach (static::$_fields as $key => $value) {
            if (is_int($key) && is_string($value)) {
                $normalizedFields[$value] = array();
            } else {
                $normalizedFields[$key] = $value;
            }
        }

        static::$_fields = $normalizedFields;
    }
P4Cms_Model::_setValue ( $  field,
$  value 
) [protected]

Set raw field value.

Does not use custom mutator methods. If idField is specified; will utilize 'setId' function.

Parameters:
string$fieldthe name of the field to set the value of.
mixed$valuethe value to set in the field.
Returns:
P4Cms_Model provides fluent interface.
Exceptions:
P4Cms_Model_Exceptionif the field does not exist.

Reimplemented in P4Cms_Site_Config.

    {
        if ($this->isReadOnlyField($field)) {
            throw new P4Cms_Model_Exception("Can't set the value of a read-only field");
        }

        // if they are setting the idField; route through setId
        if (isset(static::$_idField)
            && $field === static::$_idField) {
            return $this->setId($value);
        }

        $this->_values[$field] = $value;

        return $this;
    }
P4Cms_Model::_setValues ( array $  values) [protected]

Set all of the model's raw values at once.

Does not use custom mutator methods.

Parameters:
array$valuesassociative array of field values.
Returns:
P4Cms_Model provides a fluent interface 
    {
        foreach ($values as $field => $value) {
            try {
                $this->_setValue($field, $value);
            } catch (P4Cms_Model_Exception $e) {
            }
        }

        return $this;
    }
static P4Cms_Model::create ( $  values = null) [static]

Creates and returns a new instance of this class.

Useful for working around PHP's lack of chaining off 'new'.

Parameters:
array$valuesassociative array of keyed field values to load into the model.
Returns:
P4Cms_Model new instance of this model class. 
    {
        return new static($values);
    }
P4Cms_Model::fromArray ( $  data)

Generate a new model instance from an array.

Parameters:
array$datathe data to populate the model with.
Returns:
P4Cms_Model a new model instance with the given data. 
    {
        $model = new static;
        return $model->setValues($data);
    }
P4Cms_Model::getDefinedFields ( )

Get the explicitly defined fields.

Returns:
array a list of this model's predefined field names 
    {
        $fields = array_keys(static::$_fields);

        // ensure id field is present if defined.
        if (!empty(static::$_idField) && !in_array(static::$_idField, $fields)) {
            array_unshift($fields, static::$_idField);
        }

        // return field names.
        return $fields;
    }
P4Cms_Model::getFields ( )

Get all of the model field names.

Returns:
array a list of field names for this model.

Implements P4Cms_ModelInterface.

Reimplemented in P4Cms_Content, P4Cms_Record, and P4Cms_Site_Config.

    {
        $fields = array_flip($this->getDefinedFields())
                + $this->_values;

        // return field names.
        return array_keys($fields);
    }
P4Cms_Model::getId ( )

Get the id of this record.

Returns:
mixed the value of the id field.

Reimplemented in Site_Model_PullPathGroup, P4Cms_Menu_Mixed, P4Cms_PackageAbstract, and P4Cms_Record.

    {
        // if _idField is defined, return value of id field or null if unset.
        if (!empty(static::$_idField)) {
            if (array_key_exists(static::$_idField, $this->_values)) {
                return $this->_values[static::$_idField];
            } else {
                return null;
            }
        }

        // if we make it this far; no _idField is defined, use _id value
        return $this->_id;
    }
P4Cms_Model::getValue ( $  field)

Get a particular field value.

Will route through custom field accessor if one is defined.

Parameters:
string$fieldthe name of the field to get the value of.
Returns:
mixed the value of the field.
Exceptions:
P4Cms_Model_Exceptionif the field does not exist.

Implements P4Cms_ModelInterface.

    {
        // if an accessor is specified for this field, use it.
        $fieldAccessor = $this->_getFieldProperty($field, 'accessor');
        if ($fieldAccessor !== null) {
            return $this->{$fieldAccessor}();
        } else {
            return $this->_getValue($field);
        }
    }
P4Cms_Model::getValues ( )

Get all of the model field values.

Returns:
array an associative array of field values. 
    {
        $values = array();
        foreach ($this->getFields() as $field) {
            $values[$field] = $this->getValue($field);
        }
        return $values;
    }
P4Cms_Model::hasField ( $  field)

Check if this model has a specific field.

Parameters:
string$fieldthe field to check for the existence of.
Returns:
boolean true if the model has the named field, false otherwise.

Implements P4Cms_ModelInterface.

    {
        return in_array($field, $this->getFields());
    }
P4Cms_Model::hasId ( )

Determine if this record has an id.

Returns:
bool true if the model has a non-empty id. 
    {
        return (bool) strlen($this->getId());
    }
P4Cms_Model::isReadOnlyField ( $  field)

Check if the specified field is read only.

Parameters:
string$fieldThe field name to check
Returns:
bool true if read only false otherwise 
    {
        return (bool)$this->_getFieldProperty($field, 'readOnly');
    }
P4Cms_Model::setId ( $  id)

Set the id of this record.

Parameters:
mixed$idthe value of the id of this record.
Returns:
P4Cms_Model provides a fluent interface

Reimplemented in P4Cms_Acl_Role, P4Cms_Categorization_CategoryAbstract, P4Cms_Content_Type, P4Cms_Content, P4Cms_Record_Volatile, P4Cms_Record, P4Cms_User, and Url_Model_Url.

    {
        // if _idField is defined, set value of id field.
        if (isset(static::$_idField)) {
            if ($this->isReadOnlyField(static::$_idField)) {
                throw new P4Cms_Model_Exception("Can't set the value of a read-only field");
            }

            $this->_values[static::$_idField] = $id;
        } else {
            $this->_id = $id;
        }

        return $this;
    }
P4Cms_Model::setValue ( $  field,
$  value 
)

Set a particular field value.

Will route through custom field mutator if one is defined.

Parameters:
string$fieldthe name of the field to set the value of.
mixed$valuethe value to set in the field.
Returns:
P4Cms_Model provides a fluent interface
Exceptions:
P4Cms_Model_Exceptionif the field does not exist.

Reimplemented in P4Cms_Record.

    {
        // if a mutator is specified for this field, use it.
        $fieldMutator = $this->_getFieldProperty($field, 'mutator');
        if ($fieldMutator !== null) {
            return $this->{$fieldMutator}($value);
        } else {
            return $this->_setValue($field, $value);
        }
    }
P4Cms_Model::setValues ( $  values,
$  filter = false 
)

Set all of the model's values at once.

Parameters:
array | null$valuesassociative array of field values or null to clear values.
bool$filteroptional - if true, ignores values for unknown fields.
Returns:
P4Cms_Model provides a fluent interface

Reimplemented in P4Cms_Record.

    {
        if ($values === null) {
            $this->_values = array();
        }

        if (!is_array($values)) {
            throw new InvalidArgumentException(
                "Cannot set values. Values must be an array."
            );
        }

        foreach ($values as $field => $value) {

            // skip unknown fields if filter is set.
            if ($filter === true && !$this->hasField($field)) {
                continue;
            }

            // skip read only fields
            if ($this->isReadOnlyField($field)) {
                continue;
            }

            $this->setValue($field, $value);
        }

        return $this;
    }
P4Cms_Model::toArray ( )

Get the model as an array.

Returns:
array the model data as an array.

Implements P4Cms_ModelInterface.

    {
        return $this->getValues();
    }
P4Cms_Model::unsetValue ( $  field)

Unset a particular field value.

Will route through custom field mutator if one is defined. This will remove the field from the fields list (

See also:
getFields()), unless it is a 'defined' field (
getDefinedFields()).
Parameters:
string$fieldthe name of the field to unset the value of.
Returns:
P4Cms_Model provides a fluent interface
Exceptions:
P4Cms_Model_Exceptionif the field does not exist. 
    {
        $this->setValue($field, null);
        unset($this->_values[$field]);
    }

Member Data Documentation

P4Cms_Model::$_fields = array() [static, protected]

Reimplemented in Category_Model_Category, Cron_Model_Cron, Site_Model_PullPathGroup, System_Model_Info, Workflow_Model_State, Workflow_Model_Transition, Workflow_Model_Workflow, P4Cms_Acl_Role, P4Cms_Categorization_CategoryAbstract, P4Cms_Content_Type, P4Cms_Content, P4Cms_Menu_Mixed, P4Cms_Menu, P4Cms_Module, P4Cms_Navigation_DynamicHandler, P4Cms_Navigation_PageTypeHandler, P4Cms_Record_Config, P4Cms_Record_RegisteredType, P4Cms_Record, P4Cms_Site_Config, P4Cms_Theme, P4Cms_User, P4Cms_Widget, and Comment_Model_Comment.

P4Cms_Model::$_id = null [protected]

Reimplemented in P4Cms_Record.

P4Cms_Model::$_idField = null [static, protected]

Reimplemented in Category_Model_Category, P4Cms_Acl_Role, P4Cms_Menu_Mixed, P4Cms_Module, P4Cms_Navigation_PageTypeHandler, P4Cms_Record, P4Cms_Site, P4Cms_Theme, P4Cms_User, P4Cms_Widget, Comment_Model_Comment, and Url_Model_Url.

P4Cms_Model::$_values = array() [protected]
The documentation for this class was generated from the following file: