1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 84: 85: 86: 87: 88: 89: 90: 91: 92: 93: 94: 95: 96: 97: 98: 99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 265: 266: 267: 268: 269: 270: 271: 272: 273: 274: 275: 276: 277: 278: 279: 280: 281: 282: 283: 284: 285: 286: 287: 288: 289: 290: 291: 292: 293: 294: 295: 296: 297: 298: 299: 300: 301: 302: 303: 304: 305: 306: 307: 308: 309: 310: 311: 312: 313: 314: 315: 316: 317: 318: 319: 320: 321: 322: 323: 324: 325: 326: 327: 328: 329: 330: 331: 332: 333: 334: 335: 336: 337: 338: 339: 340: 341: 342: 343: 344: 345: 346: 347: 348: 349: 350: 351: 352: 353: 354: 355: 356: 357: 358: 359: 360: 361: 362: 363: 364: 365: 366: 367: 368: 369: 370: 371: 372: 373: 374: 375: 376: 377: 378: 379: 380: 381: 382: 383: 384: 385: 386: 387: 388: 389: 390: 391: 392: 393: 394: 395: 396: 397: 398: 399: 400: 401: 402: 403: 404: 405: 406: 407: 408: 409: 410: 411: 412: 413: 414: 415: 416: 417: 418: 419: 420: 421: 422: 423: 424: 425: 426: 427: 428: 429: 430: 431: 432: 433: 434: 435: 436: 437: 438: 439: 440: 441: 442: 443: 444: 445: 446: 447: 448: 449: 450: 451: 452: 453: 454: 455: 456: 457: 458: 459: 460: 461: 462: 463: 464: 465: 466: 467: 468: 469: 470: 471: 472: 473: 474: 475: 476: 477: 478: 479: 480: 481: 482: 483: 484: 485: 486: 487: 488: 489: 490: 491: 492: 493: 494: 495: 496: 497: 498: 499: 500: 501: 502: 503: 504: 505: 506: 507: 508: 509: 510: 511: 512: 513: 514: 515: 516: 517: 518: 519: 520: 521: 522: 523: 524: 525: 526: 527: 528: 529: 530: 531: 532: 533: 534: 535: 536: 537: 538: 539: 540: 541: 542: 543: 544: 545: 546: 547: 548: <?php
namespace Guzzle\Service\Description;
use Guzzle\Common\Exception\InvalidArgumentException;
/**
* Data object holding the information of an API command
*/
class Operation implements OperationInterface
{
/** @var string Default command class to use when none is specified */
const DEFAULT_COMMAND_CLASS = 'Guzzle\\Service\\Command\\OperationCommand';
/** @var array Hashmap of properties that can be specified. Represented as a hash to speed up constructor. */
protected static $properties = array(
'name' => true, 'httpMethod' => true, 'uri' => true, 'class' => true, 'responseClass' => true,
'responseType' => true, 'responseNotes' => true, 'notes' => true, 'summary' => true, 'documentationUrl' => true,
'deprecated' => true, 'data' => true, 'parameters' => true, 'additionalParameters' => true,
'errorResponses' => true
);
/** @var array Parameters */
protected $parameters = array();
/** @var Parameter Additional parameters schema */
protected $additionalParameters;
/** @var string Name of the command */
protected $name;
/** @var string HTTP method */
protected $httpMethod;
/** @var string This is a short summary of what the operation does */
protected $summary;
/** @var string A longer text field to explain the behavior of the operation. */
protected $notes;
/** @var string Reference URL providing more information about the operation */
protected $documentationUrl;
/** @var string HTTP URI of the command */
protected $uri;
/** @var string Class of the command object */
protected $class;
/** @var string This is what is returned from the method */
protected $responseClass;
/** @var string Type information about the response */
protected $responseType;
/** @var string Information about the response returned by the operation */
protected $responseNotes;
/** @var bool Whether or not the command is deprecated */
protected $deprecated;
/** @var array Array of errors that could occur when running the command */
protected $errorResponses;
/** @var ServiceDescriptionInterface */
protected $description;
/** @var array Extra operation information */
protected $data;
/**
* Builds an Operation object using an array of configuration data:
* - name: (string) Name of the command
* - httpMethod: (string) HTTP method of the operation
* - uri: (string) URI template that can create a relative or absolute URL
* - class: (string) Concrete class that implements this command
* - parameters: (array) Associative array of parameters for the command. {@see Parameter} for information.
* - summary: (string) This is a short summary of what the operation does
* - notes: (string) A longer text field to explain the behavior of the operation.
* - documentationUrl: (string) Reference URL providing more information about the operation
* - responseClass: (string) This is what is returned from the method. Can be a primitive, PSR-0 compliant
* class name, or model.
* - responseNotes: (string) Information about the response returned by the operation
* - responseType: (string) One of 'primitive', 'class', 'model', or 'documentation'. If not specified, this
* value will be automatically inferred based on whether or not there is a model matching the
* name, if a matching PSR-0 compliant class name is found, or set to 'primitive' by default.
* - deprecated: (bool) Set to true if this is a deprecated command
* - errorResponses: (array) Errors that could occur when executing the command. Array of hashes, each with a
* 'code' (the HTTP response code), 'reason' (response reason phrase or description of the
* error), and 'class' (a custom exception class that would be thrown if the error is
* encountered).
* - data: (array) Any extra data that might be used to help build or serialize the operation
* - additionalParameters: (null|array) Parameter schema to use when an option is passed to the operation that is
* not in the schema
*
* @param array $config Array of configuration data
* @param ServiceDescriptionInterface $description Service description used to resolve models if $ref tags are found
*/
public function __construct(array $config = array(), ServiceDescriptionInterface $description = null)
{
$this->description = $description;
// Get the intersection of the available properties and properties set on the operation
foreach (array_intersect_key($config, self::$properties) as $key => $value) {
$this->{$key} = $value;
}
$this->class = $this->class ?: self::DEFAULT_COMMAND_CLASS;
$this->deprecated = (bool) $this->deprecated;
$this->errorResponses = $this->errorResponses ?: array();
$this->data = $this->data ?: array();
if (!$this->responseClass) {
$this->responseClass = 'array';
$this->responseType = 'primitive';
} elseif ($this->responseType) {
// Set the response type to perform validation
$this->setResponseType($this->responseType);
} else {
// A response class was set and no response type was set, so guess what the type is
$this->inferResponseType();
}
// Parameters need special handling when adding
if ($this->parameters) {
foreach ($this->parameters as $name => $param) {
if ($param instanceof Parameter) {
$param->setName($name)->setParent($this);
} elseif (is_array($param)) {
$param['name'] = $name;
$this->addParam(new Parameter($param, $this->description));
}
}
}
if ($this->additionalParameters) {
if ($this->additionalParameters instanceof Parameter) {
$this->additionalParameters->setParent($this);
} elseif (is_array($this->additionalParameters)) {
$this->setadditionalParameters(new Parameter($this->additionalParameters, $this->description));
}
}
}
public function toArray()
{
$result = array();
// Grab valid properties and filter out values that weren't set
foreach (array_keys(self::$properties) as $check) {
if ($value = $this->{$check}) {
$result[$check] = $value;
}
}
// Remove the name property
unset($result['name']);
// Parameters need to be converted to arrays
$result['parameters'] = array();
foreach ($this->parameters as $key => $param) {
$result['parameters'][$key] = $param->toArray();
}
// Additional parameters need to be cast to an array
if ($this->additionalParameters instanceof Parameter) {
$result['additionalParameters'] = $this->additionalParameters->toArray();
}
return $result;
}
public function getServiceDescription()
{
return $this->description;
}
public function setServiceDescription(ServiceDescriptionInterface $description)
{
$this->description = $description;
return $this;
}
public function getParams()
{
return $this->parameters;
}
public function getParamNames()
{
return array_keys($this->parameters);
}
public function hasParam($name)
{
return isset($this->parameters[$name]);
}
public function getParam($param)
{
return isset($this->parameters[$param]) ? $this->parameters[$param] : null;
}
/**
* Add a parameter to the command
*
* @param Parameter $param Parameter to add
*
* @return self
*/
public function addParam(Parameter $param)
{
$this->parameters[$param->getName()] = $param;
$param->setParent($this);
return $this;
}
/**
* Remove a parameter from the command
*
* @param string $name Name of the parameter to remove
*
* @return self
*/
public function removeParam($name)
{
unset($this->parameters[$name]);
return $this;
}
public function getHttpMethod()
{
return $this->httpMethod;
}
/**
* Set the HTTP method of the command
*
* @param string $httpMethod Method to set
*
* @return self
*/
public function setHttpMethod($httpMethod)
{
$this->httpMethod = $httpMethod;
return $this;
}
public function getClass()
{
return $this->class;
}
/**
* Set the concrete class of the command
*
* @param string $className Concrete class name
*
* @return self
*/
public function setClass($className)
{
$this->class = $className;
return $this;
}
public function getName()
{
return $this->name;
}
/**
* Set the name of the command
*
* @param string $name Name of the command
*
* @return self
*/
public function setName($name)
{
$this->name = $name;
return $this;
}
public function getSummary()
{
return $this->summary;
}
/**
* Set a short summary of what the operation does
*
* @param string $summary Short summary of the operation
*
* @return self
*/
public function setSummary($summary)
{
$this->summary = $summary;
return $this;
}
public function getNotes()
{
return $this->notes;
}
/**
* Set a longer text field to explain the behavior of the operation.
*
* @param string $notes Notes on the operation
*
* @return self
*/
public function setNotes($notes)
{
$this->notes = $notes;
return $this;
}
public function getDocumentationUrl()
{
return $this->documentationUrl;
}
/**
* Set the URL pointing to additional documentation on the command
*
* @param string $docUrl Documentation URL
*
* @return self
*/
public function setDocumentationUrl($docUrl)
{
$this->documentationUrl = $docUrl;
return $this;
}
public function getResponseClass()
{
return $this->responseClass;
}
/**
* Set what is returned from the method. Can be a primitive, class name, or model. For example: 'array',
* 'Guzzle\\Foo\\Baz', or 'MyModelName' (to reference a model by ID).
*
* @param string $responseClass Type of response
*
* @return self
*/
public function setResponseClass($responseClass)
{
$this->responseClass = $responseClass;
$this->inferResponseType();
return $this;
}
public function getResponseType()
{
return $this->responseType;
}
/**
* Set qualifying information about the responseClass. One of 'primitive', 'class', 'model', or 'documentation'
*
* @param string $responseType Response type information
*
* @return self
* @throws InvalidArgumentException
*/
public function setResponseType($responseType)
{
static $types = array(
self::TYPE_PRIMITIVE => true,
self::TYPE_CLASS => true,
self::TYPE_MODEL => true,
self::TYPE_DOCUMENTATION => true
);
if (!isset($types[$responseType])) {
throw new InvalidArgumentException('responseType must be one of ' . implode(', ', array_keys($types)));
}
$this->responseType = $responseType;
return $this;
}
public function getResponseNotes()
{
return $this->responseNotes;
}
/**
* Set notes about the response of the operation
*
* @param string $notes Response notes
*
* @return self
*/
public function setResponseNotes($notes)
{
$this->responseNotes = $notes;
return $this;
}
public function getDeprecated()
{
return $this->deprecated;
}
/**
* Set whether or not the command is deprecated
*
* @param bool $isDeprecated Set to true to mark as deprecated
*
* @return self
*/
public function setDeprecated($isDeprecated)
{
$this->deprecated = $isDeprecated;
return $this;
}
public function getUri()
{
return $this->uri;
}
/**
* Set the URI template of the command
*
* @param string $uri URI template to set
*
* @return self
*/
public function setUri($uri)
{
$this->uri = $uri;
return $this;
}
public function getErrorResponses()
{
return $this->errorResponses;
}
/**
* Add an error to the command
*
* @param string $code HTTP response code
* @param string $reason HTTP response reason phrase or information about the error
* @param string $class Exception class associated with the error
*
* @return self
*/
public function addErrorResponse($code, $reason, $class)
{
$this->errorResponses[] = array('code' => $code, 'reason' => $reason, 'class' => $class);
return $this;
}
/**
* Set all of the error responses of the operation
*
* @param array $errorResponses Hash of error name to a hash containing a code, reason, class
*
* @return self
*/
public function setErrorResponses(array $errorResponses)
{
$this->errorResponses = $errorResponses;
return $this;
}
public function getData($name)
{
return isset($this->data[$name]) ? $this->data[$name] : null;
}
/**
* Set a particular data point on the operation
*
* @param string $name Name of the data value
* @param mixed $value Value to set
*
* @return self
*/
public function setData($name, $value)
{
$this->data[$name] = $value;
return $this;
}
/**
* Get the additionalParameters of the operation
*
* @return Parameter|null
*/
public function getAdditionalParameters()
{
return $this->additionalParameters;
}
/**
* Set the additionalParameters of the operation
*
* @param Parameter|null $parameter Parameter to set
*
* @return self
*/
public function setAdditionalParameters($parameter)
{
if ($this->additionalParameters = $parameter) {
$this->additionalParameters->setParent($this);
}
return $this;
}
/**
* Infer the response type from the responseClass value
*/
protected function inferResponseType()
{
static $primitives = array('array' => 1, 'boolean' => 1, 'string' => 1, 'integer' => 1, '' => 1);
if (isset($primitives[$this->responseClass])) {
$this->responseType = self::TYPE_PRIMITIVE;
} elseif ($this->description && $this->description->hasModel($this->responseClass)) {
$this->responseType = self::TYPE_MODEL;
} else {
$this->responseType = self::TYPE_CLASS;
}
}
}