<?php
/**
* Abstracts operations against the Perforce protections table.
*
* @copyright 2011 Perforce Software. All rights reserved.
* @license Please see LICENSE.txt in top-level folder of this distribution.
* @version <release>/<patch>
*/
namespace P4\Spec;
class Protections extends SingularAbstract
{
const SPEC_TYPE = 'protect';
protected $fields = array(
'Protections' => array(
'accessor' => 'getProtections',
'mutator' => 'setProtections'
)
);
/**
* Get protections in array form. Format of array is as follows:
*
* array (
* array (
* 'mode' => 'super',
* 'type' => 'user',
* 'name' => '*',
* 'host' => '*',
* 'path' => '//...'
* )
* )
*
* @return array array of protect entries.
*/
public function getProtections()
{
$protections = array();
foreach ((array) $this->getRawValue('Protections') as $line) {
$protections[] = $this->toProtectArray($line);
}
return $protections;
}
/**
* Set protections table entries.
*
* Individual protection entries may be specified in array or
* raw string format for convienence. See getProtections() for format.
*
* @param array $protections array of protect entries in array or raw string format.
* @return Protections provides a fluent interface.
*/
public function setProtections($protections)
{
if (!is_array($protections)) {
throw new \InvalidArgumentException(
'Protections must be passed as an array'
);
}
$strings = array();
foreach ($protections as $protect) {
// Normalize protection entries to array format for validation
if (is_string($protect)) {
$protect = $this->toProtectArray($protect);
}
$strings[] = $this->fromProtectArray($protect);
}
$this->setRawValue('Protections', $strings);
return $this;
}
/**
* Add a protection table entry.
*
* @param string $mode the access level (e.g. read, write, super, etc.)
* @param string $type the type of protection (user or group)
* @param string $name the user or group name
* @param string $host the host restriction
* @param string $path the path to apply the protection to.
* @return Protections provides a fluent interface.
* @throws \InvalidArgumentException if any inputs are invalid.
*/
public function addProtection($mode, $type, $name, $host, $path)
{
if (!is_string($mode)
|| !is_string($type)
|| !is_string($name)
|| !is_string($host)
|| !is_string($path)
) {
throw new \InvalidArgumentException(
"Cannot add protection. All parameters must be in string form."
);
}
// add to protections array.
$protections = $this->getRawValue('Protections');
$protections[] = $this->fromProtectArray(
array(
'mode' => $mode,
'type' => $type,
'name' => $name,
'host' => $host,
'path' => $path,
)
);
$this->setRawValue('Protections', $protections);
return $this;
}
/**
* Remove a protection table entry.
*
* @param string $mode the access level (e.g. read, write, super, etc.)
* @param string $type the type of protection (user or group)
* @param string $name the user or group name
* @param string $host the host restriction
* @param string $path the path to apply the protection to.
* @return Protections provides a fluent interface.
* @throws \InvalidArgumentException if any inputs are invalid.
*/
public function removeProtection($mode, $type, $name, $host, $path)
{
if (!is_string($mode)
|| !is_string($type)
|| !is_string($name)
|| !is_string($host)
|| !is_string($path)
) {
throw new \InvalidArgumentException(
"Cannot add protection. All parameters must be in string form."
);
}
$removeArray = array(
'mode' => $mode,
'type' => $type,
'name' => $name,
'host' => $host,
'path' => $path,
);
if (!$this->isValidProtectArray($removeArray)) {
throw new \InvalidArgumentException(
'Protection array entry is invalid.'
);
}
// When retrieving the protects value from the depot, the path is not
// encapsulated in quotes, so fromProtectArray cannot be used in this case.
$remove = $removeArray['mode'] ." ".
$removeArray['type'] ." ".
$removeArray['name'] ." ".
$removeArray['host'] ." ".
$removeArray['path'] ;
$protections = $this->getRawValue('Protections');
$key = array_search($remove, $protections);
if ($key !== false) {
unset($protections[$key]);
}
$this->setRawValue('Protections', $protections);
return $this;
}
/**
* Convert a raw protections string (single entry) into an array,
* see getProtections for format.
*
* @param string $entry A single protection entry in string format
* @return array A single protect entry array
* @throws \InvalidArgumentException If passed string is unparsable
*/
protected function toProtectArray($entry)
{
$keys = array('mode', 'type', 'name', 'host', 'path');
$protection = str_getcsv($entry, ' ');
if (count($protection) != count($keys)) {
throw new \InvalidArgumentException(
'Protection entry with missing field(s) encountered'
);
}
return array_combine($keys, $protection);
}
/**
* Convert a protection array (single entry) into a string, see
* getProtections for format. Will validate input array and throw
* on errors.
*
* @param array $array The single protection entry to validate and convert to string
* @return string A single protections entry in string format
* @throws \InvalidArgumentException If input is poorly formatted
*/
protected function fromProtectArray($array)
{
// Validate the array, will throw if invalid
if (!$this->isValidProtectArray($array)) {
throw new \InvalidArgumentException(
'Protection array entry is invalid.'
);
}
$protect = $array['mode'] ." ".
$array['type'] ." ".
$array['name'] ." ".
$array['host'] ." ".
'"'. $array['path'] .'"';
return $protect;
}
/**
* Validates a single protection entry in array format, see getProtections
* for format details.
*
* @param array $array A single protect entry in array format
* @return bool True - Valid, False - Error(s) found
*/
protected function isValidProtectArray($array)
{
if (!is_array($array)) {
return false;
}
// Validate all 'word' fields are present and don't contain spaces
$fields = array('mode', 'type', 'name', 'host');
foreach ($fields as $key) {
if (!array_key_exists($key, $array) ||
trim($array[$key]) === '' ||
preg_match('/\s/', $array[$key])) {
return false;
}
}
// Validate 'path' field is present, spaces are permitted
if (!array_key_exists('path', $array) || trim($array['path']) === '') {
return false;
}
return true;
}
}