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

P4_SpecAbstract Class Reference

Provides a base for singular spec models such as protections, triggers, typemap, etc. More...

Inheritance diagram for P4_SpecAbstract:
P4_ModelAbstract P4_ConnectedAbstract P4_ModelInterface P4_ConnectedInterface P4_Protections P4_Spec_PluralAbstract P4_Triggers P4_Typemap P4_Branch P4_Change P4_Client P4_Depot P4_Group P4_Job P4_Label P4_Stream P4_User

List of all members.

Public Member Functions

 getFields ()
 Get all of the spec field names.
 getRequiredFields ()
 Get all of the required fields.
 getSpecDefinition ()
 Gets the definition of this specification from Perforce.
 getValue ($field)
 Get field value.
 getValues ()
 Get all of the spec field values.
 hasField ($field)
 Check if this spec has a particular field.
 save ()
 Save this spec to Perforce.
 setValue ($field, $value)
 Set field value.
 setValues ($values)
 Set several of the spec's values at once.

Static Public Member Functions

static fetch (P4_Connection_Interface $connection=null)
 Get this spec from Perforce.

Protected Member Functions

 _deferPopulate ($reset=false)
 Schedule populate to run when data is requested (lazy-load).
 _getDefaultValue ($field)
 Get a field's default value.
 _getSpecData ()
 Get raw spec data direct from Perforce.
 _getValue ($field)
 Get a field's raw value.
 _getValues ()
 Get all of the raw field values.
 _populate ()
 Get the values for this spec from Perforce and set them in the instance.
 _setValue ($field, $value)
 Set a field's raw value.
 _setValues ($values)
 Set several of the spec's raw values at once.
 _validateRequiredFields ($values=null)
 Ensure that all required fields have values.

Static Protected Member Functions

static _getSpecType ()
 Get the type of this spec.

Protected Attributes

 $_needsPopulate = false
 $_specDefinition = null
 $_values = array()

Static Protected Attributes

static $_accessors = array()
static $_mutators = array()
static $_specType = ''

Detailed Description

Provides a base for singular spec models such as protections, triggers, typemap, etc.

to extend.

Keyed specs such as changes, jobs, users, etc. should extend P4_Spec_KeyedAbstract.

When extending this class, be sure to set the _specType to the name of the Perforce Specification Type (e.g. protect, typemap, etc.)

To provide custom field accessor methods, add entries to the _accessors array in the form of: '<field>' => '<function>'. Accessor methods take no parameters and must return a value.

Similarly, to provide custom field mutator methods, add entries to the _mutators array in the same format. Mutator methods must accept a single value parameter. It is recommended that mutator methods return $this to provide a fluent interface.

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

Member Function Documentation

P4_SpecAbstract::_deferPopulate ( $  reset = false) [protected]

Schedule populate to run when data is requested (lazy-load).

Parameters:
bool$resetoptionally clear instance values.

Reimplemented in P4_Spec_PluralAbstract.

    {
        $this->_needsPopulate = true;

        if ($reset) {
            $this->_values = array();
        }
    }
P4_SpecAbstract::_getDefaultValue ( $  field) [protected]

Get a field's default value.

Parameters:
string$fieldthe name of the field to get the default value of.
Returns:
mixed the default value of the field. 
    {
        $definition = $this->getSpecDefinition();
        $field      = $definition->getField($field);

        if (isset($field['default'])) {
            return $definition::expandDefault($field['default'], $this->getConnection());
        } else {
            return null;
        }
    }
P4_SpecAbstract::_getSpecData ( ) [protected]

Get raw spec data direct from Perforce.

No caching involved.

Returns:
array $data the raw spec output from Perforce.

Reimplemented in P4_Change, and P4_Spec_PluralAbstract.

    {
        $result = $this->getConnection()->run(static::_getSpecType(), "-o");
        return $result->expandSequences()->getData(0);
    }
static P4_SpecAbstract::_getSpecType ( ) [static, protected]

Get the type of this spec.

Returns:
string the name of this spec type.
Exceptions:
P4_Spec_Exceptionif the spec type is unset. 
    {
        // if spec type not defined, throw.
        if (!is_string(static::$_specType) || !trim(static::$_specType)) {
           throw new P4_Spec_Exception('No type is defined for this specification.');
        }

        return static::$_specType;
    }
P4_SpecAbstract::_getValue ( $  field) [protected]

Get a field's raw value.

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

Reimplemented in P4_Spec_PluralAbstract.

    {
        // if field doesn't exist, throw exception.
        if (!$this->hasField($field)) {
            throw new P4_Spec_Exception("Can't get the value of a non-existant field.");
        }

        // if field has not been set, populate.
        if (!array_key_exists($field, $this->_values)) {
            $this->_populate();
        }

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

        // get default value if field is required - return null for
        // optional fields so that they don't get values automatically.
        // optional field defaults are best handled by the server.
        if ($this->getSpecDefinition($this->getConnection())->isRequiredField($field)) {
            return $this->_getDefaultValue($field);
        } else {
            return null;
        }
    }
P4_SpecAbstract::_getValues ( ) [protected]

Get all of the raw field values.

DOES NOT use custom accessors.

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

Get the values for this spec from Perforce and set them in the instance.

Won't clobber existing values.

Reimplemented in P4_Spec_PluralAbstract.

    {
        // early exit if populate not needed.
        if (!$this->_needsPopulate) {
            return;
        }

        // get spec data from Perforce.
        $data = $this->_getSpecData();

        // ensure fields is an array.
        if (!is_array($data)) {
            throw new P4_Spec_Exception("Failed to populate spec. Perforce result invalid.");
        }

        // copy field values to instance without clobbering.
        foreach ($data as $key => $value) {
            if (!array_key_exists($key, $this->_values)) {
                $this->_values[$key] = $value;
            }
        }

        // clear needs populate flag.
        $this->_needsPopulate = false;
    }
P4_SpecAbstract::_setValue ( $  field,
$  value 
) [protected]

Set a field's raw value.

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

Reimplemented in P4_Spec_PluralAbstract.

    {
        // if field doesn't exist, throw exception.
        if (!$this->hasField($field)) {
            throw new P4_Spec_Exception("Can't set the value of a non-existant field.");
        }

        // if field is read-only, throw exception.
        if ($this->getSpecDefinition()->isReadOnlyField($field)) {
            throw new P4_Spec_Exception("Can't set the value of a read-only field.");
        }

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

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

Set several of the spec's raw values at once.

DOES NOT use custom mutators.

Parameters:
array$valuesassociative array of raw field values.
Returns:
P4_SpecAbstract provides a fluent interface 
    {
        foreach ($values as $field => $value) {
            if ($this->hasField($field)) {
                $this->_values[$field] = $value;
            }
        }

        return $this;
    }
P4_SpecAbstract::_validateRequiredFields ( $  values = null) [protected]

Ensure that all required fields have values.

Parameters:
array$valuesoptional - set of values to validate against defaults to instance values.
Exceptions:
P4_Spec_Exceptionif any required fields are missing values. 
    {
        $values = (array) $values ?: $this->_getValues();

        // check that each required field has a value.
        foreach ($this->getRequiredFields() as $field) {

            $value = isset($values[$field]) ? $values[$field] : null;

            // in order to satisfy a required field, array values
            // must have elements and all values must have string length.
            if ((is_array($value) && !count($value)) || (!is_array($value) && !strlen($value))) {
                $missing[] = $field;
            }

        }

        if (isset($missing)) {
            throw new P4_Spec_Exception(
                "Cannot save spec. Missing required fields: " . implode(", ", $missing)
            );
        }
    }
static P4_SpecAbstract::fetch ( P4_Connection_Interface $  connection = null) [static]

Get this spec from Perforce.

Creates a new spec instance and schedules a populate.

Parameters:
P4_Connection_Interface$connectionoptional - a specific connection to use.
Returns:
P4_Spec_PluralAbstract instace of the requested entry.
Exceptions:
InvalidArgumentExceptionif no id is given. 
    {
        $spec = new static($connection);
        $spec->_deferPopulate();

        return $spec;
    }
P4_SpecAbstract::getFields ( )

Get all of the spec field names.

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

Implements P4_ModelInterface.

    {
        $fields = $this->getSpecDefinition()->getFields();
        return array_keys($fields);
    }
P4_SpecAbstract::getRequiredFields ( )

Get all of the required fields.

Returns:
array a list of required fields for this spec. 
    {
        $fields = array();
        $spec   = $this->getSpecDefinition();
        foreach ($this->getFields() as $field) {
            if ($spec->isRequiredField($field)) {
                $fields[] = $field;
            }
        }

        return $fields;
    }
P4_SpecAbstract::getSpecDefinition ( )

Gets the definition of this specification from Perforce.

The specification definition provides: field names, field types, field options, preset values, comments, etc.

Only fetches it once per instance. Additionally, the spec definition object has a per-process (static) cache.

Returns:
P4_Spec_Definition instance containing details about this spec type. 
    {
        // load the spec definition if we haven't already done so.
        if (!$this->_specDefinition instanceof P4_Spec_Definition) {
            $this->_specDefinition = P4_Spec_Definition::fetch(
                static::_getSpecType(),
                $this->getConnection()
            );
        }

        return $this->_specDefinition;
    }
P4_SpecAbstract::getValue ( $  field)

Get field value.

If a custom field accessor exists, it will be used.

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

Implements P4_ModelInterface.

Reimplemented in P4_Job.

    {
        // if field doesn't exist, throw exception.
        if (!$this->hasField($field)) {
            throw new P4_Spec_Exception("Can't get the value of a non-existant field.");
        }

        // if field has custom accessor, use it.
        if (isset(static::$_accessors[$field])) {
            return $this->{static::$_accessors[$field]}();
        }

        return $this->_getValue($field);
    }
P4_SpecAbstract::getValues ( )

Get all of the spec field values.

Uses custom accessors where available.

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

Check if this spec has a particular field.

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

Implements P4_ModelInterface.

    {
        return in_array((string)$field, $this->getFields());
    }
P4_SpecAbstract::save ( )

Save this spec to Perforce.

Returns:
P4_SpecAbstract provides a fluent interface

Reimplemented in P4_Client, P4_Job, P4_Stream, and P4_User.

    {
        // ensure all required fields have values.
        $this->_validateRequiredFields();

        $this->getConnection()->run(
            static::_getSpecType(),
            "-i",
            $this->_getValues()
        );

        // should re-populate (server may change values).
        $this->_deferPopulate(true);

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

Set field value.

If a custom field mutator exists, it will be used.

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

Reimplemented in P4_Job.

    {
        // if field doesn't exist, throw exception.
        if (!$this->hasField($field)) {
            throw new P4_Spec_Exception("Can't set the value of a non-existant field.");
        }

        // if field has custom mutator, use it.
        if (isset(static::$_mutators[$field])) {
            return $this->{static::$_mutators[$field]}($value);
        }

        $this->_setValue($field, $value);

        return $this;
    }
P4_SpecAbstract::setValues ( $  values)

Set several of the spec's values at once.

Uses custom mutators where available.

Parameters:
array$valuesassociative array of field values.
Returns:
P4_SpecAbstract provides a fluent interface
Exceptions:
InvalidArgumentExceptionif values is not an array. 
    {
        if (!is_array($values)) {
            throw new InvalidArgumentException("Values must be passed as an array.");
        }

        foreach ($values as $field => $value) {
            try {
                $this->setValue($field, $value);
            } catch (P4_Spec_Exception $e) {
            }
        }

        return $this;
    }

Member Data Documentation

P4_SpecAbstract::$_accessors = array() [static, protected]

Reimplemented in P4_Branch, P4_Change, P4_Client, P4_Depot, P4_Group, P4_Job, P4_Label, P4_Protections, P4_Stream, P4_Triggers, P4_Typemap, and P4_User.

P4_SpecAbstract::$_mutators = array() [static, protected]

Reimplemented in P4_Branch, P4_Change, P4_Client, P4_Depot, P4_Group, P4_Job, P4_Label, P4_Protections, P4_Stream, P4_Triggers, P4_Typemap, and P4_User.

P4_SpecAbstract::$_needsPopulate = false [protected]
P4_SpecAbstract::$_specDefinition = null [protected]
P4_SpecAbstract::$_specType = '' [static, protected]

Reimplemented in P4_Branch, P4_Change, P4_Client, P4_Depot, P4_Group, P4_Job, P4_Label, P4_Protections, P4_Stream, P4_Triggers, P4_Typemap, and P4_User.

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