<?php
/**
* Abstracts operations against Perforce clients/workspaces.
*
* @copyright 2011 Perforce Software. All rights reserved.
* @license Please see LICENSE.txt in top-level folder of this distribution.
* @version <release>/<patch>
* @todo Add support for 'p4 opened'
* @todo Deal with converting updated/created date/times from listing format
* @todo Return DateTime objects as appropriate
*/
namespace P4\Spec;
use P4\Validate;
use P4\Connection\ConnectionInterface;
class Client extends PluralAbstract
{
const SPEC_TYPE = 'client';
const ID_FIELD = 'Client';
const FETCH_BY_NAME = 'name';
const FETCH_BY_OWNER = 'owner';
const FETCH_BY_STREAM = 'stream';
protected $fields = array(
'Update' => array(
'accessor' => 'getUpdateDateTime'
),
'Access' => array(
'accessor' => 'getAccessDateTime'
),
'Owner' => array(
'accessor' => 'getOwner',
'mutator' => 'setOwner'
),
'Host' => array(
'accessor' => 'getHost',
'mutator' => 'setHost'
),
'Description' => array(
'accessor' => 'getDescription',
'mutator' => 'setDescription'
),
'Root' => array(
'accessor' => 'getRoot',
'mutator' => 'setRoot'
),
'Options' => array(
'accessor' => 'getOptions',
'mutator' => 'setOptions'
),
'SubmitOptions' => array(
'accessor' => 'getSubmitOptions',
'mutator' => 'setSubmitOptions'
),
'LineEnd' => array(
'accessor' => 'getLineEnd',
'mutator' => 'setLineEnd'
),
'View' => array(
'accessor' => 'getView',
'mutator' => 'setView'
),
'Stream' => array(
'accessor' => 'getStream',
'mutator' => 'setStream'
)
);
/**
* Get all Clients from Perforce. Adds filtering options.
*
* @param 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').
*
* @param ConnectionInterface $connection optional - a specific connection to use.
* @return \P4\Model\Fielded\Iterator all records of this type.
*/
public static function fetchAll($options = array(), ConnectionInterface $connection = null)
{
// simply return parent - method exists to document options.
return parent::fetchAll($options, $connection);
}
/**
* 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.
*
* @return SpecAbstract provides a fluent interface
*/
public function save()
{
if ($this->get('Stream')) {
$this->set('View', array());
}
return parent::save();
}
/**
* Remove this client. Extends parent to offer force delete.
*
* @param boolean $force pass true to force delete this client.
* @return Client provides fluent interface.
*/
public function delete($force = false)
{
return parent::delete($force ? array('-f') : null);
}
/**
* Determine if the given client id exists.
*
* @param string $id the id to check for.
* @param ConnectionInterface $connection optional - a specific connection to use.
* @return bool true if the given id matches an existing client.
*/
public static function exists($id, ConnectionInterface $connection = null)
{
// 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);
}
/**
* 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.
*
* @return callable A callback function with the signature function($entry)
*/
protected static function getTempCleanupCallback()
{
$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);
};
}
/**
* 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.
*
* @return string|null Date/Time of last update, formatted "2009/11/23 12:57:06" or null
*/
public function getUpdateDateTime()
{
return $this->getRawValue('Update');
}
/**
* 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.
*
* @return string|null Date/Time of last access, formatted "2009/11/23 12:57:06" or null
*/
public function getAccessDateTime()
{
return $this->getRawValue('Access');
}
/**
* Get the owner of this client.
*
* @return string|null User who owns this record.
*/
public function getOwner()
{
return $this->getRawValue('Owner');
}
/**
* Set the owner of this client to passed value.
*
* @param string|null $owner A string containing username
* @return Client provides a fluent interface.
* @throws \InvalidArgumentException Owner is incorrect type.
*/
public function setOwner($owner)
{
if (!is_string($owner) && !is_null($owner)) {
throw new \InvalidArgumentException('Owner must be a string or null.');
}
return $this->setRawValue('Owner', $owner);
}
/**
* Get the host setting for this client.
*
* @return string|null Host name set for this client, empty string for any.
*/
public function getHost()
{
return $this->getRawValue('Host');
}
/**
* If set, restricts access to the named host. Specify a blank string or null
* to allow access from all hosts.
*
* @param string|null $host Host name for this client, empty string or null for any
* @return Client provides a fluent interface.
* @throws \InvalidArgumentException Host is incorrect type.
*/
public function setHost($host)
{
if (!is_string($host) && !is_null($host)) {
throw new \InvalidArgumentException('Host must be a string or null.');
}
return $this->setRawValue('Host', $host);
}
/**
* Get the description for this client.
*
* @return string|null description for this client.
*/
public function getDescription()
{
return $this->getRawValue('Description');
}
/**
* Set a description for this client.
*
* @param string|null $description description for this client.
* @return Client provides a fluent interface.
* @throws \InvalidArgumentException Description is incorrect type.
*/
public function setDescription($description)
{
if (!is_string($description) && !is_null($description)) {
throw new \InvalidArgumentException('Description must be a string or null.');
}
return $this->setRawValue('Description', $description);
}
/**
* Get the base directory of the client workspace.
*
* @return string|null Base directory of the client workspace.
*/
public function getRoot()
{
return $this->getRawValue('Root');
}
/**
* Set the base directory of the client workspace.
*
* @param string|null $root Base directory for the client workspace.
* @return Client provides a fluent interface.
* @throws \InvalidArgumentException Root is incorrect type.
*/
public function setRoot($root)
{
if (!is_string($root) && !is_null($root)) {
throw new \InvalidArgumentException('Root must be a string or null.');
}
return $this->setRawValue('Root', $root);
}
/**
* 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'
* )
*
* @return array options which are set on this client.
*/
public function getOptions()
{
$options = $this->getRawValue('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;
}
/**
* Set the options for this client.
* Accepts an array, format detailed in getOptions, or a single string containing
* a space seperated list of options.
*
* @param array|string $options options to set on this client in array or string.
* @return Client provides a fluent interface.
* @throws \InvalidArgumentException Options are incorrect type.
*/
public function setOptions($options)
{
if (is_array($options)) {
$options = implode(' ', $options);
}
if (!is_string($options)) {
throw new \InvalidArgumentException('Options must be an array or string');
}
return $this->setRawValue('Options', $options);
}
/**
* Get the submit options for this client.
* Returned array will contain one option per element e.g.:
* array (
* 0 => 'submitunchanged'
* )
*
* @return array submit options which are set on this client.
*/
public function getSubmitOptions()
{
$options = $this->getRawValue('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;
}
/**
* 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.
*
* @param array|string $options submit options to set on this client in array or string
* @return Client provides a fluent interface.
* @throws \InvalidArgumentException Submit Options are incorrect type.
*/
public function setSubmitOptions($options)
{
if (is_array($options)) {
$options = implode(' ', $options);
}
if (!is_string($options)) {
throw new \InvalidArgumentException('Submit Options must be an array or string');
}
return $this->setRawValue('SubmitOptions', $options);
}
/**
* Get the line ending setting for this client.
* Will be one of: local/unix/mac/win/share
*
* @return string|null Line ending setting for this client.
*/
public function getLineEnd()
{
return $this->getRawValue('LineEnd');
}
/**
* Set the line ending setting for this client.
* See getLineEnd for available options.
*
* @param string|null $lineEnd Line ending setting for this client.
* @return Client provides a fluent interface.
* @throws \InvalidArgumentException lineEnd is incorrect type.
*/
public function setLineEnd($lineEnd)
{
if (!is_string($lineEnd) && !is_null($lineEnd)) {
throw new \InvalidArgumentException('Line End must be a string or null.');
}
return $this->setRawValue('LineEnd', $lineEnd);
}
/**
* 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/...'
* )
* )
*
* @return array list view entries for this client.
*/
public function getView()
{
// 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->getRawValue('View') ?: array() as $entry) {
$entry = str_getcsv($entry, ' ');
$view[] = array_combine(array('depot','client'), $entry);
}
return $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.
*
* @param array $view View entries, formatted into depot/client sub-arrays.
* @return Client provides a fluent interface.
* @throws \InvalidArgumentException View array, or a view entry, is incorrect type.
*/
public function setView($view)
{
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->setRawValue('View', $parsedView);
}
/**
* Add a view mapping to this client.
*
* @param string $depot the depot half of the view mapping.
* @param string $client the client half of the view mapping.
* @return Client provides a fluent interface.
*/
public function addView($depot, $client)
{
$mappings = $this->getView();
$mappings[] = array("depot" => $depot, "client" => $client);
return $this->setView($mappings);
}
/**
* Updates the 'client' half of the view to ensure the
* current client ID is used.
*
* @return Client provides a fluent interface.
*/
public function touchUpView()
{
$view = $this->getView();
foreach ($view as &$mapping) {
$mapping['client'] = preg_replace(
"#//[^/]*/#",
'//' . $this->getId() . '/',
$mapping['client']
);
}
$this->setView($view);
return $this;
}
/**
* Get the stream this client is dedicated to.
*
* @return string|null Stream setting for this client.
*/
public function getStream()
{
return $this->getRawValue('Stream');
}
/**
* Set the stream this client is dedicated to.
*
* @param string|null $stream stream setting for this client.
* @return Client provides a fluent interface.
* @throws \InvalidArgumentException stream is incorrect type.
* @todo Validate stream id
*/
public function setStream($stream)
{
if (!is_string($stream) && !is_null($stream)) {
throw new \InvalidArgumentException('Stream must be a string or null.');
}
return $this->setRawValue('Stream', $stream);
}
/**
* Check if the given id is in a valid format for this spec type.
*
* @param string $id the id to check
* @return bool true if id is valid, false otherwise
*/
protected static function isValidId($id)
{
$validator = new Validate\SpecName;
$validator->allowRelative(true);
$validator->allowPercent(false);
$validator->allowCommas(false);
return $validator->isValid($id);
}
/**
* Produce set of flags for the spec list command, given fetch all options array.
* Extends parent to add support for filter option.
*
* @param array $options array of options to augment fetch behavior.
* see fetchAll for documented options.
* @return array set of flags suitable for passing to spec list command.
*/
protected static function getFetchAllFlags($options)
{
$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;
}
}