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

Inheritance diagram for P4_SpecAbstract:

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 $reset optionally 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 $field the 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_Exception if 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 $field the name of the field to get the value of.

Returns:: mixed the value of the field.

Exceptions:

P4_Spec_Exception if 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	$field	the name of the field to set the value of.
mixed	$value	the value to set in the field.

Returns:: P4_SpecAbstract provides a fluent interface

Exceptions:

P4_Spec_Exception if 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 $values associative 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 $values optional - set of values to validate against defaults to instance values.

Exceptions:

P4_Spec_Exception if 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 $connection optional - a specific connection to use.

Returns:: P4_Spec_PluralAbstract instace of the requested entry.

Exceptions:

InvalidArgumentException if 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 $field the name of the field to get the value of.

Returns:: mixed the value of the field.

Exceptions:

P4_Spec_Exception if 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 $field the 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	$field	the name of the field to set the value of.
mixed	$value	the value to set in the field.

Returns:: P4_SpecAbstract provides a fluent interface

Exceptions:

P4_Spec_Exception if 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 $values associative array of field values.

Returns:: P4_SpecAbstract provides a fluent interface

Exceptions:

InvalidArgumentException if 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:

SpecAbstract.php

P4_SpecAbstract Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

Member Data Documentation