interface/modules/zend_modules/library/Zend/Json/Server/Smd/Service.php

   1 <?php
   2 /**
   3  * Zend Framework (http://framework.zend.com/)
   4  *
   5  * @link      http://github.com/zendframework/zf2 for the canonical source repository
   6  * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
   7  * @license   http://framework.zend.com/license/new-bsd New BSD License
   8  */
   9
  10 namespace Zend\Json\Server\Smd;
  11
  12 use Zend\Json\Server;
  13 use Zend\Json\Server\Exception\InvalidArgumentException;
  14 use Zend\Json\Server\Smd;
  15
  16 /**
  17  * Create Service Mapping Description for a method
  18  *
  19  * @todo       Revised method regex to allow NS; however, should SMD be revised to strip PHP NS instead when attaching functions?
  20  */
  21 class Service
  22 {
  23     /**#@+
  24      * Service metadata
  25      * @var string
  26      */
  27     protected $envelope  = Smd::ENV_JSONRPC_1;
  28     protected $name;
  29     protected $return;
  30     protected $target;
  31     protected $transport = 'POST';
  32     /**#@-*/
  33
  34     /**
  35      * Allowed envelope types
  36      * @var array
  37      */
  38     protected $envelopeTypes = array(
  39         Smd::ENV_JSONRPC_1,
  40         Smd::ENV_JSONRPC_2,
  41     );
  42
  43     /**
  44      * Regex for names
  45      * @var string
  46      */
  47     protected $nameRegex = '/^[a-z][a-z0-9.\\\\_]+$/i';
  48
  49     /**
  50      * Parameter option types
  51      * @var array
  52      */
  53     protected $paramOptionTypes = array(
  54         'name'        => 'is_string',
  55         'optional'    => 'is_bool',
  56         'default'     => null,
  57         'description' => 'is_string',
  58     );
  59
  60     /**
  61      * Service params
  62      * @var array
  63      */
  64     protected $params = array();
  65
  66     /**
  67      * Mapping of parameter types to JSON-RPC types
  68      * @var array
  69      */
  70     protected $paramMap = array(
  71         'any'     => 'any',
  72         'arr'     => 'array',
  73         'array'   => 'array',
  74         'assoc'   => 'object',
  75         'bool'    => 'boolean',
  76         'boolean' => 'boolean',
  77         'dbl'     => 'float',
  78         'double'  => 'float',
  79         'false'   => 'boolean',
  80         'float'   => 'float',
  81         'hash'    => 'object',
  82         'integer' => 'integer',
  83         'int'     => 'integer',
  84         'mixed'   => 'any',
  85         'nil'     => 'null',
  86         'null'    => 'null',
  87         'object'  => 'object',
  88         'string'  => 'string',
  89         'str'     => 'string',
  90         'struct'  => 'object',
  91         'true'    => 'boolean',
  92         'void'    => 'null',
  93     );
  94
  95     /**
  96      * Allowed transport types
  97      * @var array
  98      */
  99     protected $transportTypes = array(
 100         'POST',
 101     );
 102
 103     /**
 104      * Constructor
 105      *
 106      * @param  string|array $spec
 107      * @throws InvalidArgumentException if no name provided
 108      */
 109     public function __construct($spec)
 110     {
 111         if (is_string($spec)) {
 112             $this->setName($spec);
 113         } elseif (is_array($spec)) {
 114             $this->setOptions($spec);
 115         }
 116
 117         if (null == $this->getName()) {
 118             throw new InvalidArgumentException('SMD service description requires a name; none provided');
 119         }
 120     }
 121
 122     /**
 123      * Set object state
 124      *
 125      * @param  array $options
 126      * @return Service
 127      */
 128     public function setOptions(array $options)
 129     {
 130         $methods = get_class_methods($this);
 131         foreach ($options as $key => $value) {
 132             if ('options' == strtolower($key)) {
 133                 continue;
 134             }
 135             $method = 'set' . ucfirst($key);
 136             if (in_array($method, $methods)) {
 137                 $this->$method($value);
 138             }
 139         }
 140         return $this;
 141     }
 142
 143     /**
 144      * Set service name
 145      *
 146      * @param  string $name
 147      * @return Service
 148      * @throws InvalidArgumentException
 149      */
 150     public function setName($name)
 151     {
 152         $name = (string) $name;
 153         if (!preg_match($this->nameRegex, $name)) {
 154             throw new InvalidArgumentException("Invalid name '{$name} provided for service; must follow PHP method naming conventions");
 155         }
 156         $this->name = $name;
 157         return $this;
 158     }
 159
 160     /**
 161      * Retrieve name
 162      *
 163      * @return string
 164      */
 165     public function getName()
 166     {
 167         return $this->name;
 168     }
 169
 170     /**
 171      * Set Transport
 172      *
 173      * Currently limited to POST
 174      *
 175      * @param  string $transport
 176      * @throws InvalidArgumentException
 177      * @return Service
 178      */
 179     public function setTransport($transport)
 180     {
 181         if (!in_array($transport, $this->transportTypes)) {
 182             throw new InvalidArgumentException("Invalid transport '{$transport}'; please select one of (" . implode(', ', $this->transportTypes) . ')');
 183         }
 184
 185         $this->transport = $transport;
 186         return $this;
 187     }
 188
 189     /**
 190      * Get transport
 191      *
 192      * @return string
 193      */
 194     public function getTransport()
 195     {
 196         return $this->transport;
 197     }
 198
 199     /**
 200      * Set service target
 201      *
 202      * @param  string $target
 203      * @return Service
 204      */
 205     public function setTarget($target)
 206     {
 207         $this->target = (string) $target;
 208         return $this;
 209     }
 210
 211     /**
 212      * Get service target
 213      *
 214      * @return string
 215      */
 216     public function getTarget()
 217     {
 218         return $this->target;
 219     }
 220
 221     /**
 222      * Set envelope type
 223      *
 224      * @param  string $envelopeType
 225      * @throws InvalidArgumentException
 226      * @return Service
 227      */
 228     public function setEnvelope($envelopeType)
 229     {
 230         if (!in_array($envelopeType, $this->envelopeTypes)) {
 231             throw new InvalidArgumentException("Invalid envelope type '{$envelopeType}'; please specify one of (" . implode(', ', $this->envelopeTypes) . ')');
 232         }
 233
 234         $this->envelope = $envelopeType;
 235         return $this;
 236     }
 237
 238     /**
 239      * Get envelope type
 240      *
 241      * @return string
 242      */
 243     public function getEnvelope()
 244     {
 245         return $this->envelope;
 246     }
 247
 248     /**
 249      * Add a parameter to the service
 250      *
 251      * @param  string|array $type
 252      * @param  array $options
 253      * @param  int|null $order
 254      * @throws InvalidArgumentException
 255      * @return Service
 256      */
 257     public function addParam($type, array $options = array(), $order = null)
 258     {
 259         if (is_string($type)) {
 260             $type = $this->_validateParamType($type);
 261         } elseif (is_array($type)) {
 262             foreach ($type as $key => $paramType) {
 263                 $type[$key] = $this->_validateParamType($paramType);
 264             }
 265         } else {
 266             throw new InvalidArgumentException('Invalid param type provided');
 267         }
 268
 269         $paramOptions = array(
 270             'type' => $type,
 271         );
 272         foreach ($options as $key => $value) {
 273             if (in_array($key, array_keys($this->paramOptionTypes))) {
 274                 if (null !== ($callback = $this->paramOptionTypes[$key])) {
 275                     if (!$callback($value)) {
 276                         continue;
 277                     }
 278                 }
 279                 $paramOptions[$key] = $value;
 280             }
 281         }
 282
 283         $this->params[] = array(
 284             'param' => $paramOptions,
 285             'order' => $order,
 286         );
 287
 288         return $this;
 289     }
 290
 291     /**
 292      * Add params
 293      *
 294      * Each param should be an array, and should include the key 'type'.
 295      *
 296      * @param  array $params
 297      * @return Service
 298      */
 299     public function addParams(array $params)
 300     {
 301         ksort($params);
 302         foreach ($params as $options) {
 303             if (!is_array($options)) {
 304                 continue;
 305             }
 306             if (!array_key_exists('type', $options)) {
 307                 continue;
 308             }
 309             $type  = $options['type'];
 310             $order = (array_key_exists('order', $options)) ? $options['order'] : null;
 311             $this->addParam($type, $options, $order);
 312         }
 313         return $this;
 314     }
 315
 316     /**
 317      * Overwrite all parameters
 318      *
 319      * @param  array $params
 320      * @return Service
 321      */
 322     public function setParams(array $params)
 323     {
 324         $this->params = array();
 325         return $this->addParams($params);
 326     }
 327
 328     /**
 329      * Get all parameters
 330      *
 331      * Returns all params in specified order.
 332      *
 333      * @return array
 334      */
 335     public function getParams()
 336     {
 337         $params = array();
 338         $index  = 0;
 339         foreach ($this->params as $param) {
 340             if (null === $param['order']) {
 341                 if (array_search($index, array_keys($params), true)) {
 342                     ++$index;
 343                 }
 344                 $params[$index] = $param['param'];
 345                 ++$index;
 346             } else {
 347                 $params[$param['order']] = $param['param'];
 348             }
 349         }
 350         ksort($params);
 351         return $params;
 352     }
 353
 354     /**
 355      * Set return type
 356      *
 357      * @param  string|array $type
 358      * @throws InvalidArgumentException
 359      * @return Service
 360      */
 361     public function setReturn($type)
 362     {
 363         if (is_string($type)) {
 364             $type = $this->_validateParamType($type, true);
 365         } elseif (is_array($type)) {
 366             foreach ($type as $key => $returnType) {
 367                 $type[$key] = $this->_validateParamType($returnType, true);
 368             }
 369         } else {
 370             throw new InvalidArgumentException("Invalid param type provided ('" . gettype($type) . "')");
 371         }
 372         $this->return = $type;
 373         return $this;
 374     }
 375
 376     /**
 377      * Get return type
 378      *
 379      * @return string|array
 380      */
 381     public function getReturn()
 382     {
 383         return $this->return;
 384     }
 385
 386     /**
 387      * Cast service description to array
 388      *
 389      * @return array
 390      */
 391     public function toArray()
 392     {
 393         $envelope   = $this->getEnvelope();
 394         $target     = $this->getTarget();
 395         $transport  = $this->getTransport();
 396         $parameters = $this->getParams();
 397         $returns    = $this->getReturn();
 398
 399         if (empty($target)) {
 400             return compact('envelope', 'transport', 'parameters', 'returns');
 401         }
 402
 403         return $paramInfo = compact('envelope', 'target', 'transport', 'parameters', 'returns');
 404     }
 405
 406     /**
 407      * Return JSON encoding of service
 408      *
 409      * @return string
 410      */
 411     public function toJson()
 412     {
 413         $service = array($this->getName() => $this->toArray());
 414         return \Zend\Json\Json::encode($service);
 415     }
 416
 417     /**
 418      * Cast to string
 419      *
 420      * @return string
 421      */
 422     public function __toString()
 423     {
 424         return $this->toJson();
 425     }
 426
 427     /**
 428      * Validate parameter type
 429      *
 430      * @param string  $type
 431      * @param  bool $isReturn
 432      * @return string
 433      * @throws InvalidArgumentException
 434      */
 435     protected function _validateParamType($type, $isReturn = false)
 436     {
 437         if (!is_string($type)) {
 438             throw new InvalidArgumentException("Invalid param type provided ('{$type}')");
 439         }
 440
 441         if (!array_key_exists($type, $this->paramMap)) {
 442             $type = 'object';
 443         }
 444
 445         $paramType = $this->paramMap[$type];
 446         if (!$isReturn && ('null' == $paramType)) {
 447             throw new InvalidArgumentException("Invalid param type provided ('{$type}')");
 448         }
 449
 450         return $paramType;
 451     }
 452 }