library/Zend/XmlRpc/Server.php

   1 <?php
   2 /**
   3  * Zend Framework
   4  *
   5  * LICENSE
   6  *
   7  * This source file is subject to the new BSD license that is bundled
   8  * with this package in the file LICENSE.txt.
   9  * It is also available through the world-wide-web at this URL:
  10  * http://framework.zend.com/license/new-bsd
  11  * If you did not receive a copy of the license and are unable to
  12  * obtain it through the world-wide-web, please send an email
  13  * to license@zend.com so we can send you a copy immediately.
  14  *
  15  * @category   Zend
  16  * @package    Zend_XmlRpc
  17  * @subpackage Server
  18  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
  19  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  20  * @version    $Id: Server.php 17786 2009-08-23 22:26:33Z lars $
  21  */
  22
  23 /**
  24  * Extends Zend_Server_Abstract
  25  */
  26 require_once 'Zend/Server/Abstract.php';
  27
  28 /**
  29  * XMLRPC Request
  30  */
  31 require_once 'Zend/XmlRpc/Request.php';
  32
  33 /**
  34  * XMLRPC Response
  35  */
  36 require_once 'Zend/XmlRpc/Response.php';
  37
  38 /**
  39  * XMLRPC HTTP Response
  40  */
  41 require_once 'Zend/XmlRpc/Response/Http.php';
  42
  43 /**
  44  * XMLRPC server fault class
  45  */
  46 require_once 'Zend/XmlRpc/Server/Fault.php';
  47
  48 /**
  49  * XMLRPC server system methods class
  50  */
  51 require_once 'Zend/XmlRpc/Server/System.php';
  52
  53 /**
  54  * Convert PHP to and from xmlrpc native types
  55  */
  56 require_once 'Zend/XmlRpc/Value.php';
  57
  58 /**
  59  * Reflection API for function/method introspection
  60  */
  61 require_once 'Zend/Server/Reflection.php';
  62
  63 /**
  64  * Zend_Server_Reflection_Function_Abstract
  65  */
  66 require_once 'Zend/Server/Reflection/Function/Abstract.php';
  67
  68 /**
  69  * Specifically grab the Zend_Server_Reflection_Method for manually setting up
  70  * system.* methods and handling callbacks in {@link loadFunctions()}.
  71  */
  72 require_once 'Zend/Server/Reflection/Method.php';
  73
  74 /**
  75  * An XML-RPC server implementation
  76  *
  77  * Example:
  78  * <code>
  79  * require_once 'Zend/XmlRpc/Server.php';
  80  * require_once 'Zend/XmlRpc/Server/Cache.php';
  81  * require_once 'Zend/XmlRpc/Server/Fault.php';
  82  * require_once 'My/Exception.php';
  83  * require_once 'My/Fault/Observer.php';
  84  *
  85  * // Instantiate server
  86  * $server = new Zend_XmlRpc_Server();
  87  *
  88  * // Allow some exceptions to report as fault responses:
  89  * Zend_XmlRpc_Server_Fault::attachFaultException('My_Exception');
  90  * Zend_XmlRpc_Server_Fault::attachObserver('My_Fault_Observer');
  91  *
  92  * // Get or build dispatch table:
  93  * if (!Zend_XmlRpc_Server_Cache::get($filename, $server)) {
  94  *     require_once 'Some/Service/Class.php';
  95  *     require_once 'Another/Service/Class.php';
  96  *
  97  *     // Attach Some_Service_Class in 'some' namespace
  98  *     $server->setClass('Some_Service_Class', 'some');
  99  *
 100  *     // Attach Another_Service_Class in 'another' namespace
 101  *     $server->setClass('Another_Service_Class', 'another');
 102  *
 103  *     // Create dispatch table cache file
 104  *     Zend_XmlRpc_Server_Cache::save($filename, $server);
 105  * }
 106  *
 107  * $response = $server->handle();
 108  * echo $response;
 109  * </code>
 110  *
 111  * @category   Zend
 112  * @package    Zend_XmlRpc
 113  * @subpackage Server
 114  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
 115  * @license    http://framework.zend.com/license/new-bsd     New BSD License
 116  */
 117 class Zend_XmlRpc_Server extends Zend_Server_Abstract
 118 {
 119     /**
 120      * Character encoding
 121      * @var string
 122      */
 123     protected $_encoding = 'UTF-8';
 124
 125     /**
 126      * Request processed
 127      * @var null|Zend_XmlRpc_Request
 128      */
 129     protected $_request = null;
 130
 131     /**
 132      * Class to use for responses; defaults to {@link Zend_XmlRpc_Response_Http}
 133      * @var string
 134      */
 135     protected $_responseClass = 'Zend_XmlRpc_Response_Http';
 136
 137     /**
 138      * Dispatch table of name => method pairs
 139      * @var Zend_Server_Definition
 140      */
 141     protected $_table;
 142
 143     /**
 144      * PHP types => XML-RPC types
 145      * @var array
 146      */
 147     protected $_typeMap = array(
 148         'i4'               => 'i4',
 149         'int'              => 'int',
 150         'integer'          => 'int',
 151         'double'           => 'double',
 152         'float'            => 'double',
 153         'real'             => 'double',
 154         'boolean'          => 'boolean',
 155         'bool'             => 'boolean',
 156         'true'             => 'boolean',
 157         'false'            => 'boolean',
 158         'string'           => 'string',
 159         'str'              => 'string',
 160         'base64'           => 'base64',
 161         'dateTime.iso8601' => 'dateTime.iso8601',
 162         'date'             => 'dateTime.iso8601',
 163         'time'             => 'dateTime.iso8601',
 164         'time'             => 'dateTime.iso8601',
 165         'array'            => 'array',
 166         'struct'           => 'struct',
 167         'null'             => 'nil',
 168         'nil'              => 'nil',
 169         'void'             => 'void',
 170         'mixed'            => 'struct'
 171     );
 172
 173     /**
 174      * Send arguments to all methods or just constructor?
 175      *
 176      * @var bool
 177      */
 178     protected $_sendArgumentsToAllMethods = true;
 179
 180     /**
 181      * Constructor
 182      *
 183      * Creates system.* methods.
 184      *
 185      * @return void
 186      */
 187     public function __construct()
 188     {
 189         $this->_table = new Zend_Server_Definition();
 190         $this->_registerSystemMethods();
 191     }
 192
 193     /**
 194      * Proxy calls to system object
 195      *
 196      * @param  string $method
 197      * @param  array $params
 198      * @return mixed
 199      * @throws Zend_XmlRpc_Server_Exception
 200      */
 201     public function __call($method, $params)
 202     {
 203         $system = $this->getSystem();
 204         if (!method_exists($system, $method)) {
 205             require_once 'Zend/XmlRpc/Server/Exception.php';
 206             throw new Zend_XmlRpc_Server_Exception('Unknown instance method called on server: ' . $method);
 207         }
 208         return call_user_func_array(array($system, $method), $params);
 209     }
 210
 211     /**
 212      * Attach a callback as an XMLRPC method
 213      *
 214      * Attaches a callback as an XMLRPC method, prefixing the XMLRPC method name
 215      * with $namespace, if provided. Reflection is done on the callback's
 216      * docblock to create the methodHelp for the XMLRPC method.
 217      *
 218      * Additional arguments to pass to the function at dispatch may be passed;
 219      * any arguments following the namespace will be aggregated and passed at
 220      * dispatch time.
 221      *
 222      * @param string|array $function Valid callback
 223      * @param string $namespace Optional namespace prefix
 224      * @return void
 225      * @throws Zend_XmlRpc_Server_Exception
 226      */
 227     public function addFunction($function, $namespace = '')
 228     {
 229         if (!is_string($function) && !is_array($function)) {
 230             require_once 'Zend/XmlRpc/Server/Exception.php';
 231             throw new Zend_XmlRpc_Server_Exception('Unable to attach function; invalid', 611);
 232         }
 233
 234         $argv = null;
 235         if (2 < func_num_args()) {
 236             $argv = func_get_args();
 237             $argv = array_slice($argv, 2);
 238         }
 239
 240         $function = (array) $function;
 241         foreach ($function as $func) {
 242             if (!is_string($func) || !function_exists($func)) {
 243                 require_once 'Zend/XmlRpc/Server/Exception.php';
 244                 throw new Zend_XmlRpc_Server_Exception('Unable to attach function; invalid', 611);
 245             }
 246             $reflection = Zend_Server_Reflection::reflectFunction($func, $argv, $namespace);
 247             $this->_buildSignature($reflection);
 248         }
 249     }
 250
 251     /**
 252      * Attach class methods as XMLRPC method handlers
 253      *
 254      * $class may be either a class name or an object. Reflection is done on the
 255      * class or object to determine the available public methods, and each is
 256      * attached to the server as an available method; if a $namespace has been
 257      * provided, that namespace is used to prefix the XMLRPC method names.
 258      *
 259      * Any additional arguments beyond $namespace will be passed to a method at
 260      * invocation.
 261      *
 262      * @param string|object $class
 263      * @param string $namespace Optional
 264      * @param mixed $argv Optional arguments to pass to methods
 265      * @return void
 266      * @throws Zend_XmlRpc_Server_Exception on invalid input
 267      */
 268     public function setClass($class, $namespace = '', $argv = null)
 269     {
 270         if (is_string($class) && !class_exists($class)) {
 271             require_once 'Zend/XmlRpc/Server/Exception.php';
 272             throw new Zend_XmlRpc_Server_Exception('Invalid method class', 610);
 273         }
 274
 275         $argv = null;
 276         if (2 < func_num_args()) {
 277             $argv = func_get_args();
 278             $argv = array_slice($argv, 2);
 279         }
 280
 281         $dispatchable = Zend_Server_Reflection::reflectClass($class, $argv, $namespace);
 282         foreach ($dispatchable->getMethods() as $reflection) {
 283             $this->_buildSignature($reflection, $class);
 284         }
 285     }
 286
 287     /**
 288      * Raise an xmlrpc server fault
 289      *
 290      * @param string|Exception $fault
 291      * @param int $code
 292      * @return Zend_XmlRpc_Server_Fault
 293      */
 294     public function fault($fault = null, $code = 404)
 295     {
 296         if (!$fault instanceof Exception) {
 297             $fault = (string) $fault;
 298             if (empty($fault)) {
 299                 $fault = 'Unknown Error';
 300             }
 301             require_once 'Zend/XmlRpc/Server/Exception.php';
 302             $fault = new Zend_XmlRpc_Server_Exception($fault, $code);
 303         }
 304
 305         return Zend_XmlRpc_Server_Fault::getInstance($fault);
 306     }
 307
 308     /**
 309      * Handle an xmlrpc call
 310      *
 311      * @param Zend_XmlRpc_Request $request Optional
 312      * @return Zend_XmlRpc_Response|Zend_XmlRpc_Fault
 313      */
 314     public function handle($request = false)
 315     {
 316         // Get request
 317         if ((!$request || !$request instanceof Zend_XmlRpc_Request)
 318             && (null === ($request = $this->getRequest()))
 319         ) {
 320             require_once 'Zend/XmlRpc/Request/Http.php';
 321             $request = new Zend_XmlRpc_Request_Http();
 322             $request->setEncoding($this->getEncoding());
 323         }
 324
 325         $this->setRequest($request);
 326
 327         if ($request->isFault()) {
 328             $response = $request->getFault();
 329         } else {
 330             try {
 331                 $response = $this->_handle($request);
 332             } catch (Exception $e) {
 333                 $response = $this->fault($e);
 334             }
 335         }
 336
 337         // Set output encoding
 338         $response->setEncoding($this->getEncoding());
 339
 340         return $response;
 341     }
 342
 343     /**
 344      * Load methods as returned from {@link getFunctions}
 345      *
 346      * Typically, you will not use this method; it will be called using the
 347      * results pulled from {@link Zend_XmlRpc_Server_Cache::get()}.
 348      *
 349      * @param  array|Zend_Server_Definition $definition
 350      * @return void
 351      * @throws Zend_XmlRpc_Server_Exception on invalid input
 352      */
 353     public function loadFunctions($definition)
 354     {
 355         if (!is_array($definition) && (!$definition instanceof Zend_Server_Definition)) {
 356             if (is_object($definition)) {
 357                 $type = get_class($definition);
 358             } else {
 359                 $type = gettype($definition);
 360             }
 361             require_once 'Zend/XmlRpc/Server/Exception.php';
 362             throw new Zend_XmlRpc_Server_Exception('Unable to load server definition; must be an array or Zend_Server_Definition, received ' . $type, 612);
 363         }
 364
 365         $this->_table->clearMethods();
 366         $this->_registerSystemMethods();
 367
 368         if ($definition instanceof Zend_Server_Definition) {
 369             $definition = $definition->getMethods();
 370         }
 371
 372         foreach ($definition as $key => $method) {
 373             if ('system.' == substr($key, 0, 7)) {
 374                 continue;
 375             }
 376             $this->_table->addMethod($method, $key);
 377         }
 378     }
 379
 380     /**
 381      * Set encoding
 382      *
 383      * @param string $encoding
 384      * @return Zend_XmlRpc_Server
 385      */
 386     public function setEncoding($encoding)
 387     {
 388         $this->_encoding = $encoding;
 389         return $this;
 390     }
 391
 392     /**
 393      * Retrieve current encoding
 394      *
 395      * @return string
 396      */
 397     public function getEncoding()
 398     {
 399         return $this->_encoding;
 400     }
 401
 402     /**
 403      * Do nothing; persistence is handled via {@link Zend_XmlRpc_Server_Cache}
 404      *
 405      * @param  mixed $mode
 406      * @return void
 407      */
 408     public function setPersistence($mode)
 409     {
 410     }
 411
 412     /**
 413      * Set the request object
 414      *
 415      * @param string|Zend_XmlRpc_Request $request
 416      * @return Zend_XmlRpc_Server
 417      * @throws Zend_XmlRpc_Server_Exception on invalid request class or object
 418      */
 419     public function setRequest($request)
 420     {
 421         if (is_string($request) && class_exists($request)) {
 422             $request = new $request();
 423             if (!$request instanceof Zend_XmlRpc_Request) {
 424                 require_once 'Zend/XmlRpc/Server/Exception.php';
 425                 throw new Zend_XmlRpc_Server_Exception('Invalid request class');
 426             }
 427             $request->setEncoding($this->getEncoding());
 428         } elseif (!$request instanceof Zend_XmlRpc_Request) {
 429             require_once 'Zend/XmlRpc/Server/Exception.php';
 430             throw new Zend_XmlRpc_Server_Exception('Invalid request object');
 431         }
 432
 433         $this->_request = $request;
 434         return $this;
 435     }
 436
 437     /**
 438      * Return currently registered request object
 439      *
 440      * @return null|Zend_XmlRpc_Request
 441      */
 442     public function getRequest()
 443     {
 444         return $this->_request;
 445     }
 446
 447     /**
 448      * Set the class to use for the response
 449      *
 450      * @param string $class
 451      * @return boolean True if class was set, false if not
 452      */
 453     public function setResponseClass($class)
 454     {
 455         if (!class_exists($class) or
 456             ($c = new ReflectionClass($class) and !$c->isSubclassOf('Zend_XmlRpc_Response'))) {
 457
 458             require_once 'Zend/XmlRpc/Server/Exception.php';
 459             throw new Zend_XmlRpc_Server_Exception('Invalid response class');
 460         }
 461         $this->_responseClass = $class;
 462         return true;
 463     }
 464
 465     /**
 466      * Retrieve current response class
 467      *
 468      * @return string
 469      */
 470     public function getResponseClass()
 471     {
 472         return $this->_responseClass;
 473     }
 474
 475     /**
 476      * Retrieve dispatch table
 477      *
 478      * @return array
 479      */
 480     public function getDispatchTable()
 481     {
 482         return $this->_table;
 483     }
 484
 485     /**
 486      * Returns a list of registered methods
 487      *
 488      * Returns an array of dispatchables (Zend_Server_Reflection_Function,
 489      * _Method, and _Class items).
 490      *
 491      * @return array
 492      */
 493     public function getFunctions()
 494     {
 495         return $this->_table->toArray();
 496     }
 497
 498     /**
 499      * Retrieve system object
 500      *
 501      * @return Zend_XmlRpc_Server_System
 502      */
 503     public function getSystem()
 504     {
 505         return $this->_system;
 506     }
 507
 508     /**
 509      * Send arguments to all methods?
 510      *
 511      * If setClass() is used to add classes to the server, this flag defined
 512      * how to handle arguments. If set to true, all methods including constructor
 513      * will receive the arguments. If set to false, only constructor will receive the
 514      * arguments
 515      */
 516     public function sendArgumentsToAllMethods($flag = null)
 517     {
 518         if ($flag === null) {
 519             return $this->_sendArgumentsToAllMethods;
 520         }
 521
 522         $this->_sendArgumentsToAllMethods = (bool)$flag;
 523         return $this;
 524     }
 525
 526     /**
 527      * Map PHP type to XML-RPC type
 528      *
 529      * @param  string $type
 530      * @return string
 531      */
 532     protected function _fixType($type)
 533     {
 534         if (isset($this->_typeMap[$type])) {
 535             return $this->_typeMap[$type];
 536         }
 537         return 'void';
 538     }
 539
 540     /**
 541      * Handle an xmlrpc call (actual work)
 542      *
 543      * @param Zend_XmlRpc_Request $request
 544      * @return Zend_XmlRpc_Response
 545      * @throws Zend_XmlRpcServer_Exception|Exception
 546      * Zend_XmlRpcServer_Exceptions are thrown for internal errors; otherwise,
 547      * any other exception may be thrown by the callback
 548      */
 549     protected function _handle(Zend_XmlRpc_Request $request)
 550     {
 551         $method = $request->getMethod();
 552
 553         // Check for valid method
 554         if (!$this->_table->hasMethod($method)) {
 555             require_once 'Zend/XmlRpc/Server/Exception.php';
 556             throw new Zend_XmlRpc_Server_Exception('Method "' . $method . '" does not exist', 620);
 557         }
 558
 559         $info     = $this->_table->getMethod($method);
 560         $params   = $request->getParams();
 561         $argv     = $info->getInvokeArguments();
 562         if (0 < count($argv) and $this->sendArgumentsToAllMethods()) {
 563             $params = array_merge($params, $argv);
 564         }
 565
 566         // Check calling parameters against signatures
 567         $matched    = false;
 568         $sigCalled  = $request->getTypes();
 569
 570         $sigLength  = count($sigCalled);
 571         $paramsLen  = count($params);
 572         if ($sigLength < $paramsLen) {
 573             for ($i = $sigLength; $i < $paramsLen; ++$i) {
 574                 $xmlRpcValue = Zend_XmlRpc_Value::getXmlRpcValue($params[$i]);
 575                 $sigCalled[] = $xmlRpcValue->getType();
 576             }
 577         }
 578
 579         $signatures = $info->getPrototypes();
 580         foreach ($signatures as $signature) {
 581             $sigParams = $signature->getParameters();
 582             if ($sigCalled === $sigParams) {
 583                 $matched = true;
 584                 break;
 585             }
 586         }
 587         if (!$matched) {
 588             require_once 'Zend/XmlRpc/Server/Exception.php';
 589             throw new Zend_XmlRpc_Server_Exception('Calling parameters do not match signature', 623);
 590         }
 591
 592         $return        = $this->_dispatch($info, $params);
 593         $responseClass = $this->getResponseClass();
 594         return new $responseClass($return);
 595     }
 596
 597     /**
 598      * Register system methods with the server
 599      *
 600      * @return void
 601      */
 602     protected function _registerSystemMethods()
 603     {
 604         $system = new Zend_XmlRpc_Server_System($this);
 605         $this->_system = $system;
 606         $this->setClass($system, 'system');
 607     }
 608 }