Abstracts operations against Perforce clients/workspaces. More...

Inheritance diagram for P4_Client:

Public Member Functions
	addView ($depot, $client)
	Add a view mapping to this client.
	delete ($force=false)
	Remove this client.
	getAccessDateTime ()
	Get the last access time for this client spec.
	getDescription ()
	Get the description for this client.
	getHost ()
	Get the host setting for this client.
	getLineEnd ()
	Get the line ending setting for this client.
	getOptions ()
	Get options for this client.
	getOwner ()
	Get the owner of this client.
	getRoot ()
	Get the base directory of the client workspace.
	getStream ()
	Get the stream this client is dedicated to.
	getSubmitOptions ()
	Get the submit options for this client.
	getUpdateDateTime ()
	Get the last update time for this client spec.
	getView ()
	Get the view for this client.
	save ()
	Save this spec to Perforce.
	setDescription ($description)
	Set a description for this client.
	setHost ($host)
	If set, restricts access to the named host.
	setLineEnd ($lineEnd)
	Set the line ending setting for this client.
	setOptions ($options)
	Set the options for this client.
	setOwner ($owner)
	Set the owner of this client to passed value.
	setRoot ($root)
	Set the base directory of the client workspace.
	setStream ($stream)
	Set the stream this client is dedicated to.
	setSubmitOptions ($options)
	Set the submit options for this client.
	setView ($view)
	Set the view for this client.
	touchUpView ()
	Updates the 'client' half of the view to ensure the current client ID is used.
Static Public Member Functions
static	exists ($id, P4_Connection_Interface $connection=null)
	Determine if the given client id exists.
static	fetchAll ($options=array(), P4_Connection_Interface $connection=null)
	Get all Clients from Perforce.
Public Attributes
const	FETCH_BY_NAME = 'name'
const	FETCH_BY_OWNER = 'owner'
const	FETCH_BY_STREAM = 'stream'
Static Protected Member Functions
static	_fromSpecListEntry ($listEntry, $flags, P4_Connection_Interface $connection)
	Given a spec entry from spec list output (p4 clients), produce an instance of this spec with field values set where possible.
static	_getFetchAllFlags ($options)
	Produce set of flags for the spec list command, given fetch all options array.
static	_getTempCleanupCallback ()
	Extends the parent temp cleanup callback to try reverting any files prior to client deletion.
Static Protected Attributes
static	$_accessors
static	$_idField = 'Client'
static	$_mutators
static	$_specType = 'client'

Detailed Description

Abstracts operations against Perforce clients/workspaces.

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_Client::_fromSpecListEntry	(	$	listEntry,
		$	flags,
		P4_Connection_Interface $	connection
	)		`[static, protected]`

Given a spec entry from spec list output (p4 clients), produce an instance of this spec with field values set where possible.

Parameters:

array	$listEntry	a single spec entry from spec list output.
array	$flags	the flags that were used for this 'fetchAll' run.
P4_Connection_Interface	$connection	a specific connection to use.

Returns:: P4_Client a (partially) populated instance of this spec class.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // update/access time are return as longs. Unset to avoid figuring out timezone
        // for a proper conversion.
        unset($listEntry['Update']);
        unset($listEntry['Access']);

        return parent::_fromSpecListEntry($listEntry, $flags, $connection);
    }

static P4_Client::_getFetchAllFlags ( $ options ) [static, protected]

Produce set of flags for the spec list command, given fetch all options array.

Extends parent to add support for filter option.

Parameters:

array $options array of options to augment fetch behavior. see fetchAll for documented options.

Returns:: array set of flags suitable for passing to spec list command.

Reimplemented from P4_Spec_PluralAbstract.

    {
        $flags = parent::_getFetchAllFlags($options);

        if (isset($options[static::FETCH_BY_NAME])) {
            $name = $options[static::FETCH_BY_NAME];

            if (!is_string($name) || trim($name) === '') {
                throw new InvalidArgumentException(
                    'Filter by Name expects a non-empty string as input'
                );
            }

            $flags[] = '-e';
            $flags[] = $name;
        }

        if (isset($options[static::FETCH_BY_OWNER])) {
            $owner = $options[static::FETCH_BY_OWNER];

            // We allow empty values as this returns clients with no owner
            if (!is_string($owner) || trim($owner) === '') {
                throw new InvalidArgumentException(
                    'Filter by Owner expects a non-empty string as input'
                );
            }

            $flags[] = '-u';
            $flags[] = $owner;
        }

        if (isset($options[static::FETCH_BY_STREAM])) {
            $stream = $options[static::FETCH_BY_STREAM];

            if (!is_string($stream) || trim($stream) === '') {
                throw new InvalidArgumentException(
                    'Filter by Stream expects a non-empty string as input'
                );
            }

            $flags[] = '-S';
            $flags[] = $stream;
        }

        return $flags;
    }

static P4_Client::_getTempCleanupCallback ( ) [static, protected]

Extends the parent temp cleanup callback to try reverting any files prior to client deletion.

This won't always be successful, but it will reduce the number of temp clients that cannot be deleted due to open files.

Returns:: function A callback function with the signature function($entry)

Reimplemented from P4_Spec_PluralAbstract.

    {
        $parentCallback = parent::_getTempCleanupCallback();

        return function($entry) use ($parentCallback)
        {
            $p4       = $entry->getConnection();
            $original = $p4->getClient();
            $p4->setClient($entry->getId());

            // try to revert any open files - if this fails we
            // want to carry on so the original client gets restored
            // and we still attempt to delete the client spec.
            try {
                $p4->run('revert', array('-k', '//...'));
            } catch (Exception $e) {
                // carry on!
            }

            // restore the original client
            $p4->setClient($original);

            // let parent delete the spec entry.
            return $parentCallback($entry);
        };
    }

P4_Client::addView	(	$	depot,
		$	client
	)

Add a view mapping to this client.

Parameters:

string	$depot	the depot half of the view mapping.
string	$client	the client half of the view mapping.

Returns:: P4_Client provides a fluent interface.

    {
        $mappings   = $this->getView();
        $mappings[] = array("depot" => $depot, "client" => $client);

        return $this->setView($mappings);
    }

P4_Client::delete ( $ force = false )

Remove this client.

Extends parent to offer force delete.

Parameters:

boolean $force pass true to force delete this client.

Returns:: P4_Client provides fluent interface.

    {
        return parent::delete($force ? array('-f') : null);
    }

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

Determine if the given client 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 client.

Reimplemented from P4_Spec_PluralAbstract.

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

        $clients = static::fetchAll(
            array(
                static::FETCH_BY_NAME => $id,
                static::FETCH_MAXIMUM => 1
            ),
            $connection
        );

        return (bool) count($clients);
    }

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

Get all Clients from Perforce.

Adds filtering options.

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. FETCH_BY_NAME - set to client name pattern (e.g. 'pc*'). FETCH_BY_OWNER - set to owner's username (e.g. 'jdoe'). FETCH_BY_STREAM - set to stream name (e.g. '//depotname/string').

Parameters:

P4_Connection_Interface $connection optional - a specific connection to use.

Returns:: P4_Model_Iterator all records of this type.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // simply return parent - method exists to document options.
        return parent::fetchAll($options, $connection);
    }

P4_Client::getAccessDateTime ( )

Get the last access time for this client spec.

This value is read only, no setAccessTime function is provided.

If this is a brand new spec, null will be returned in lieu of a time.

Returns:: string|null Date/Time of last access, formatted "2009/11/23 12:57:06" or null

    {
        return $this->_getValue('Access');
    }

P4_Client::getDescription ( )

Get the description for this client.

Returns:: string|null description for this client.

    {
        return $this->_getValue('Description');
    }

P4_Client::getHost ( )

Get the host setting for this client.

Returns:: string|null Host name set for this client, empty string for any.

    {
        return $this->_getValue('Host');
    }

P4_Client::getLineEnd ( )

Get the line ending setting for this client.

Will be one of: local/unix/mac/win/share

Returns:: string|null Line ending setting for this client.

    {
        return $this->_getValue('LineEnd');
    }

P4_Client::getOptions ( )

Get options for this client.

Returned array will contain one option per element e.g.: array ( 0 => 'noallwrite', 1 => 'noclobber', 2 => 'nocompress', 3 => 'unlocked', 4 => 'nomodtime', 5 => 'rmdir' )

Returns:: array options which are set on this client.

    {
        $options = $this->_getValue('Options');
        $options = explode(' ', $options);

        // Explode will set key 0 to null for empty input; clean it up.
        if (count($options) == 1 && empty($options[0])) {
            $options = array();
        }

        return $options;
    }

P4_Client::getOwner ( )

Get the owner of this client.

Returns:: string|null User who owns this record.

    {
        return $this->_getValue('Owner');
    }

P4_Client::getRoot ( )

Get the base directory of the client workspace.

Returns:: string|null Base directory of the client workspace.

    {
        return $this->_getValue('Root');
    }

P4_Client::getStream ( )

Get the stream this client is dedicated to.

Returns:: string|null Stream setting for this client.

    {
        return $this->_getValue('Stream');
    }

P4_Client::getSubmitOptions ( )

Get the submit options for this client.

Returned array will contain one option per element e.g.: array ( 0 => 'submitunchanged' )

Returns:: array submit options which are set on this client.

    {
        $options = $this->_getValue('SubmitOptions');
        $options = explode(' ', $options);

        // Explode will set key 0 to null for empty input; clean it up.
        if (count($options) == 1 && empty($options[0])) {
            $options = array();
        }

        return $options;
    }

P4_Client::getUpdateDateTime ( )

Get the last update time for this client spec.

This value is read only, no setUpdateTime function is provided.

If this is a brand new spec, null will be returned in lieu of a time.

Returns:: string|null Date/Time of last update, formatted "2009/11/23 12:57:06" or null

    {
        return $this->_getValue('Update');
    }

P4_Client::getView ( )

Get the view for this client.

View entries will be returned as an array with 'depot' and 'client' entries, e.g.: array ( 0 => array ( 'depot' => '//depot/example/with space/...', 'client' => '//client.name/...' ) )

Returns:: array list view entries for this client.

    {
        // The raw view data is formatted as:
        //  array (
        //      0 => '"//depot/example/with space/..." //client.name/...',
        //  )
        //
        // We split this into 'depot' and 'client' components via the str_getcsv function
        // and key the two resulting entries as 'depot' and 'client'
        $view = array();
        // The ?: translates empty views into an empty array
        foreach ($this->_getValue('View') ?: array() as $entry) {
            $entry = str_getcsv($entry, ' ');
            $view[] = array_combine(array('depot','client'), $entry);
        }

        return $view;
    }

P4_Client::save ( )

Save this spec to Perforce.

Extends parent to blank out the 'View' if a stream is specified. You cannot edit the view on a stream spec but leaving it can cause errors.

Returns:: P4_SpecAbstract provides a fluent interface

Reimplemented from P4_SpecAbstract.

    {
        if ($this->getValue('Stream')) {
            $this->setValue('View', array());
        }

        return parent::save();
    }

P4_Client::setDescription ( $ description )

Set a description for this client.

Parameters:

string | null $description description for this client.

Returns:: P4_Client provides a fluent interface.

Exceptions:

InvalidArgumentException Description is incorrect type.

    {
        if (!is_string($description) && !is_null($description)) {
            throw new InvalidArgumentException('Description must be a string or null.');
        }

        return $this->_setValue('Description', $description);
    }

P4_Client::setHost ( $ host )

If set, restricts access to the named host.

Specify a blank string or null to allow access from all hosts.

Parameters:

string | null $host Host name for this client, empty string or null for any

Returns:: P4_Client provides a fluent interface.

Exceptions:

InvalidArgumentException Host is incorrect type.

    {
        if (!is_string($host) && !is_null($host)) {
            throw new InvalidArgumentException('Host must be a string or null.');
        }

        return $this->_setValue('Host', $host);
    }

P4_Client::setLineEnd ( $ lineEnd )

Set the line ending setting for this client.

See getLineEnd for available options.

Parameters:

string | null $lineEnd Line ending setting for this client.

Returns:: P4_Client provides a fluent interface.

Exceptions:

InvalidArgumentException lineEnd is incorrect type.

    {
        if (!is_string($lineEnd) && !is_null($lineEnd)) {
            throw new InvalidArgumentException('Line End must be a string or null.');
        }

        return $this->_setValue('LineEnd', $lineEnd);
    }

P4_Client::setOptions ( $ options )

Set the options for this client.

Accepts an array, format detailed in getOptions, or a single string containing a space seperated list of options.

Parameters:

array | string $options options to set on this client in array or string.

Returns:: P4_Client provides a fluent interface.

Exceptions:

InvalidArgumentException Options are incorrect type.

    {
        if (is_array($options)) {
            $options = implode(' ', $options);
        }

        if (!is_string($options)) {
            throw new InvalidArgumentException('Options must be an array or string');
        }

        return $this->_setValue('Options', $options);
    }

P4_Client::setOwner ( $ owner )

Set the owner of this client to passed value.

Parameters:

string | null $owner A string containing username

Returns:: P4_Client provides a fluent interface.

Exceptions:

InvalidArgumentException Owner is incorrect type.

    {
        if (!is_string($owner) && !is_null($owner)) {
            throw new InvalidArgumentException('Owner must be a string or null.');
        }

        return $this->_setValue('Owner', $owner);
    }

P4_Client::setRoot ( $ root )

Set the base directory of the client workspace.

Parameters:

string | null $root Base directory for the client workspace.

Returns:: P4_Client provides a fluent interface.

Exceptions:

InvalidArgumentException Root is incorrect type.

    {
        if (!is_string($root) && !is_null($root)) {
            throw new InvalidArgumentException('Root must be a string or null.');
        }

        return $this->_setValue('Root', $root);
    }

P4_Client::setStream ( $ stream )

Set the stream this client is dedicated to.

Parameters:

string | null $stream stream setting for this client.

Returns:: P4_Client provides a fluent interface.

Exceptions:

InvalidArgumentException stream is incorrect type.

    {
        if (!is_string($stream) && !is_null($stream)) {
            throw new InvalidArgumentException('Stream must be a string or null.');
        }

        return $this->_setValue('Stream', $stream);
    }

P4_Client::setSubmitOptions ( $ options )

Set the submit options for this client.

Accepts an array, format detailed in getSubmitOptions, or a single string containing a space seperated list of options.

Parameters:

array | string $options submit options to set on this client in array or string

Returns:: P4_Client provides a fluent interface.

Exceptions:

InvalidArgumentException Submit Options are incorrect type.

    {
        if (is_array($options)) {
            $options = implode(' ', $options);
        }

        if (!is_string($options)) {
            throw new InvalidArgumentException('Submit Options must be an array or string');
        }

        return $this->_setValue('SubmitOptions', $options);
    }

P4_Client::setView ( $ view )

Set the view for this client.

View is passed as an array of view entries. Each view entry can be an array with 'depot' and 'client' entries or a raw string.

Parameters:

array $view View entries, formatted into depot/client sub-arrays.

Returns:: P4_Client provides a fluent interface.

Exceptions:

InvalidArgumentException View array, or a view entry, is incorrect type.

    {
        if (!is_array($view)) {
            throw new InvalidArgumentException('View must be passed as array.');
        }

        // The View array contains either:
        // - Child arrays keyed on depot/client which we glue together
        // - Raw strings which we simply leave as is
        // The below foreach run will normalize the whole thing for storage
        $parsedView = array();
        foreach ($view as $entry) {
            if (is_array($entry) &&
                isset($entry['depot'], $entry['client']) &&
                is_string($entry['depot']) &&
                is_string($entry['client'])) {
                $entry = '"'. $entry['depot'] .'" "'. $entry['client'] .'"';
            }

            if (!is_string($entry)) {
                throw new InvalidArgumentException(
                   "Each view entry must be a 'depot' and 'client' array or a string."
                );
            }

            $validate = str_getcsv($entry, ' ');
            if (count($validate) != 2 || trim($validate[0]) === '' || trim($validate[1]) === '') {
                throw new InvalidArgumentException(
                   "Each view entry must contain two paths, no more, no less."
                );
            }

            $parsedView[] = $entry;
        };

        return $this->_setValue('View', $parsedView);
    }

P4_Client::touchUpView ( )

Updates the 'client' half of the view to ensure the current client ID is used.

Returns:: P4_Client provides a fluent interface.

    {
        $view = $this->getView();
        foreach ($view as &$mapping) {
            $mapping['client'] = preg_replace(
                "#//[^/]*/#",
                '//' . $this->getId() . '/',
                $mapping['client']
            );
        }
        $this->setView($view);

        return $this;
    }

Member Data Documentation

P4_Client::$_accessors [static, protected]

Initial value:

 array(
        'Update'        => 'getUpdateDateTime',
        'Access'        => 'getAccessDateTime',
        'Owner'         => 'getOwner',
        'Host'          => 'getHost',
        'Description'   => 'getDescription',
        'Root'          => 'getRoot',
        'Options'       => 'getOptions',
        'SubmitOptions' => 'getSubmitOptions',
        'LineEnd'       => 'getLineEnd',
        'View'          => 'getView',
        'Stream'        => 'getStream'
    )

Reimplemented from P4_SpecAbstract.

P4_Client::$_idField = 'Client' [static, protected]

Reimplemented from P4_Spec_PluralAbstract.

P4_Client::$_mutators [static, protected]

Initial value:

 array(
        'Owner'         => 'setOwner',
        'Host'          => 'setHost',
        'Description'   => 'setDescription',
        'Root'          => 'setRoot',
        'Options'       => 'setOptions',
        'SubmitOptions' => 'setSubmitOptions',
        'LineEnd'       => 'setLineEnd',
        'View'          => 'setView',
        'Stream'        => 'setStream'
    )

Reimplemented from P4_SpecAbstract.

P4_Client::$_specType = 'client' [static, protected]

Reimplemented from P4_SpecAbstract.

const P4_Client::FETCH_BY_NAME = 'name'

const P4_Client::FETCH_BY_OWNER = 'owner'

const P4_Client::FETCH_BY_STREAM = 'stream'

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

Client.php

P4_Client Class Reference

Public Member Functions

Static Public Member Functions

Public Attributes

Static Protected Member Functions

Static Protected Attributes

Detailed Description

Member Function Documentation

Member Data Documentation