Abstracts operations against Perforce counters. More...

Inheritance diagram for P4_Counter:

Public Member Functions
	delete ($force=false)
	Delete this counter entry.
	getId ()
	Get the id of this counter.
	getValue ()
	Get counter's value.
	increment ()
	Increment counters value by 1.
	setId ($id)
	Set the id of this counter.
	setValue ($value, $force=false)
	Set counters value.
Static Public Member Functions
static	exists ($id, P4_Connection_Interface $connection=null)
	Determine if the given counter id exists.
static	fetch ($id, P4_Connection_Interface $connection=null)
	Get the requested counter from Perforce.
static	fetchAll ($options=array(), P4_Connection_Interface $connection=null)
	Get all Counters from Perforce.
Public Attributes
const	FETCH_MAXIMUM = 'maximum'
Static Protected Member Functions
static	_isValidId ($id)
	Check if the given id is in a valid format.
Protected Attributes
	$_id = null

Detailed Description

Abstracts operations against Perforce counters.

As counters are quite volatile, this class performs no caching. Reading a counter always queries perforce for the current value and setting a new value immediately stores to perforce.

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

static P4_Counter::_isValidId ( $ id ) [static, protected]

Check if the given id is in a valid format.

Parameters:

string $id the id to check

Returns:: bool true if id is valid, false otherwise

    {
        $validator = new P4_Validate_CounterName;
        return $validator->isValid($id);
    }

P4_Counter::delete ( $ force = false )

Delete this counter entry.

Parameters:

bool $force optional - force delete the counter.

Returns:: P4_Counter provides a fluent interface

Exceptions:

P4_Exception if no id has been set.

    {
        $id = $this->getId();
        if ($id === null) {
            throw new P4_Exception("Cannot delete. No id has been set.");
        }

        // ensure id exists.
        $connection = $this->getConnection();
        if (!static::exists($id, $connection)) {
            throw new P4_Exception(
                "Cannot delete counter. Counter does not exist."
            );
        }

        // setup counter command args.
        $params   = $force ? array('-f') : array();
        $params[] = "-d";
        $params[] = $id;

        $result = $connection->run('counter', $params);

        return $this;
    }

static P4_Counter::exists	(	$	id,
		P4_Connection_Interface $	connection = `null`
	)		`[static]`

Determine if the given counter id exists.

Parameters:

string	$id	the id to check for.
P4_Connection_Interface	$connection	optional - a specific connection to use.

Returns:: bool true if the given id matches an existing counter.

    {
        // check id for valid format
        if (!static::_isValidId($id)) {
            return false;
        }

        $counters = static::fetchAll(array(), $connection);

        return in_array($id, $counters->invoke('getId'));
    }

static P4_Counter::fetch	(	$	id,
		P4_Connection_Interface $	connection = `null`
	)		`[static]`

Get the requested counter from Perforce.

Parameters:

string	$id	the id of the counter to fetch.
P4_Connection_Interface	$connection	optional - a specific connection to use.

Returns:: P4_Counter instace of the requested counter.

Exceptions:

InvalidArgumentException if invalid id is given.

    {
        // ensure a valid id is provided.
        if (!static::_isValidId($id)) {
            throw new InvalidArgumentException("Must supply a valid id to fetch.");
        }

        // if no connection given, use default.
        $connection = $connection ?: static::getDefaultConnection();

        // ensure id exists.
        if (!static::exists($id, $connection)) {
            throw new P4_Exception(
                "Cannot fetch counter. Counter does not exist."
            );
        }

        // construct counter instance.
        $counter = new static($connection);
        $counter->setId($id);

        return $counter;
    }

static P4_Counter::fetchAll	(	$	options = `array()`,
		P4_Connection_Interface $	connection = `null`
	)		`[static]`

Get all Counters from Perforce.

Parameters:

array	$options	optional - array of options to augment fetch behavior. supported options are: FETCH_MAXIMUM - set to integer value to limit to the first 'max' number of entries. *Note: Limits imposed client side.
P4_Connection_Interface	$connection	optional - a specific connection to use.

Returns:: P4_Iterator all counters matching passed option(s).

    {
        // if no connection given, use default.
        $connection = $connection ?: static::getDefaultConnection();

        // fetch all counters.
        $result = $connection->run('counters');

        // convert result data to counter objects.
        $counters = new P4_Iterator;
        $max      = array_key_exists(static::FETCH_MAXIMUM, $options) ? (int)$options[static::FETCH_MAXIMUM] : 0;
  
        foreach ($result->getData() as $data) {
            // populate a counter and add it to the iterator
            $counter = new static($connection);
            $counter->setId($data['counter']);

            $counters[] = $counter;

            // stop looping if we reach 'FETCH_MAXIMUM'
            if ($max > 0 && count($counters) == $max) {
                break;
            }
        }

        return $counters;
    }

P4_Counter::getId ( )

Get the id of this counter.

Returns:: null|string the id of this entry.

    {
        return $this->_id;
    }

P4_Counter::getValue ( )

Get counter's value.

There is no caching, the value is always read from perforce.

Returns:: mixed the value of the counter.

    {
        $id = $this->getId();
        $connection = $this->getConnection();

        // if the ID is not set or the ID doesn't exist in perforce, return null
        if ($id === null || !static::exists($id, $connection)) {
            return null;
        }
        
        $result = $connection->run('counter', $id);
        $data = $result->getData();

        return $data[0]['value'];
    }

P4_Counter::increment ( )

Increment counters value by 1.

If the counter doesn't exist it will be created and assigned the value 1. The update is carried out atomically by the server.

Returns:: string The counters new value

Exceptions:

P4_Exception If the current value is non-numeric

    {
        $id = $this->getId();
        if ($id === null) {
            throw new P4_Exception("Cannot increment value. No id has been set.");
        }

        $result = $this->getConnection()->run('counter', array('-i', $id));
        $data   = $result->getData();

        return $data[0]['value'];
    }

P4_Counter::setId ( $ id )

Set the id of this counter.

Id must be in a valid format or null.

Parameters:

null | string $id the id of this entry - pass null to clear.

Returns:: P4_Counter provides a fluent interface

Exceptions:

InvalidArgumentException if id does not pass validation.

    {
        if ($id !== null && !static::_isValidId($id)) {
            throw new InvalidArgumentException("Cannot set id. Id is invalid.");
        }

        $this->_id = $id;
        
        return $this;
    }

P4_Counter::setValue	(	$	value,
		$	force = `false`
	)

Set counters value.

The value will be immediately written to perforce.

Parameters:

mixed	$value	the value to set in the counter.
bool	$force	optional - force set the counter.

Returns:: P4_Counter provides a fluent interface

Exceptions:

P4_Exception if no Id has been set

    {
        $id = $this->getId();
        if ($id === null) {
            throw new P4_Exception("Cannot set value. No id has been set.");
        }
        
        // setup counter command args.
        $params   = $force ? array('-f') : array();
        $params[] = $id;
        $params[] = $value;

        $this->getConnection()->run('counter', $params);

        return $this;
    }

Member Data Documentation

P4_Counter::$_id = null [protected]

const P4_Counter::FETCH_MAXIMUM = 'maximum'

The documentation for this class was generated from the following file:

Counter.php

P4_Counter Class Reference

Public Member Functions

Static Public Member Functions

Public Attributes

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

Member Data Documentation