[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3  * dom_xmlrpc_server provides basic XML-RPC server functionality
   4  * @package dom-xmlrpc
   5  * @copyright (C) 2004 John Heinstein. All rights reserved
   6  * @license http://www.gnu.org/copyleft/lesser.html LGPL License
   7  * @author John Heinstein <johnkarl@nbnet.nb.ca>
   8  * @link http://www.engageinteractive.com/dom_xmlrpc/ DOM XML-RPC Home Page
   9  * DOM XML-RPC is Free Software
  10  **/
  11  
  12  if (!defined('DOM_XMLRPC_INCLUDE_PATH')) {
  13      define('DOM_XMLRPC_INCLUDE_PATH', (dirname(__FILE__) . "/"));
  14  }
  15  
  16  //XML-RPC Exceptions
  17  //From Specification for Fault Code Interoperability
  18  /** @var int XML not well formed error */
  19  define('DOM_XMLRPC_PARSE_ERROR_NOT_WELL_FORMED', -32700);
  20  /** @var int unsupported encoding error */
  21  define('DOM_XMLRPC_PARSE_ERROR_UNSUPPORTED_ENCODING', -32701);
  22  /** @var int invalid encoding error */
  23  define('DOM_XMLRPC_PARSE_ERROR_INVALID_CHARACTER_ENCODING', -32702);
  24  /** @var int nonconformat XML-RPC error */
  25  define('DOM_XMLRPC_SERVER_ERROR_INVALID_XMLRPC_NONCONFORMANT', -32600);
  26  /** @var int requested method not found error */
  27  define('DOM_XMLRPC_SERVER_ERROR_REQUESTED_METHOD_NOT_FOUND', -32601);
  28  /** @var int invalid method parameters error */
  29  define('DOM_XMLRPC_SERVER_ERROR_INVALID_METHOD_PARAMETERS', -32602);
  30  /** @var int internal server error */
  31  define('DOM_XMLRPC_SERVER_ERROR_INTERNAL_XMLRPC', -32603);
  32  /** @var int application error */
  33  define('DOM_XMLRPC_APPLICATION_ERROR', -32500);
  34  /** @var int system error */
  35  define('DOM_XMLRPC_SYSTEM_ERROR', -32400);
  36  /** @var int http transport error */
  37  define('DOM_XMLRPC_TRANSPORT_ERROR', -32300);
  38  
  39  require_once (DOM_XMLRPC_INCLUDE_PATH . 'php_http_server_generic.php');
  40  require_once (DOM_XMLRPC_INCLUDE_PATH . 'dom_xmlrpc_constants.php');
  41  
  42  /**
  43  * Provides basic XML-RPC server functionality
  44  *
  45  * @package dom-xmlrpc
  46  * @author John Heinstein <johnkarl@nbnet.nb.ca>
  47  */
  48  class dom_xmlrpc_server extends php_http_server_generic {
  49      /** @var object A reference to a method mapping class */
  50      var $methodmapper;
  51      /** @var boolean True if params array is to be tokenized */
  52      var $tokenizeParamsArray = false;
  53      /** @var int Server error code */
  54      var $serverError = -1;
  55      /** @var string Server error string */
  56      var $serverErrorString = '';
  57      /** @var object A reference to the handler for missing methods  */
  58      var $methodNotFoundHandler = null;
  59      /** @var boolean True if object awareness is enabled */
  60      var $objectAwareness = false;
  61      /** @var object A reference to the handler for PHP object values */
  62      var $objectDefinitionHandler = null;
  63      /** @var array Repository for multiple method responses */
  64      var $multiresponse = array();
  65  
  66      /**
  67      * Constructor
  68      * @param object A reference to a mapping of custom method handlers
  69      * @param boolean True if onPost is to be immediately called
  70      */
  71  	function dom_xmlrpc_server($customMethods = null, $postData = null) {
  72          $this->php_http_server_generic();
  73          $this->setHTTPEvents();
  74          $this->setHeaders();
  75  
  76          $this->methodmapper = new dom_xmlrpc_methodmapper();
  77          $this->addSystemMethods();
  78  
  79          if ($customMethods != null) $this->addCustomMethods($customMethods);
  80          if ($postData != null) $this->fireHTTPEvent('onPost'); //don't have to call receive() method in this case
  81      } //dom_xmlrpc_server
  82  
  83      /**
  84      * Sets the headers for the client connection
  85      */
  86  	function setHeaders() {
  87          $this->setHeader('Content-Type', 'text/xml');
  88          $this->setHeader('Server', 'DOM XML-RPC Server/0.1');
  89      } //setHeaders
  90  
  91      /**
  92      * Sets the default HTTP event handling
  93      */
  94  	function setHTTPEvents() {
  95          $this->setHTTPEvent('onPost', array(&$this, 'onPost'));
  96  
  97          $defaultHandler = array(&$this, 'onWrongRequestMethod');
  98          $this->setHTTPEvent('onGet', $defaultHandler);
  99          $this->setHTTPEvent('onHead', $defaultHandler);
 100          $this->setHTTPEvent('onPut', $defaultHandler);
 101      } //setHTTPEvents
 102  
 103      /**
 104      * Adds the default XML-RPC system methods to the method map
 105      */
 106  	function addSystemMethods() {
 107          $this->methodmapper->addMethod(new dom_xmlrpc_method(array(
 108                                      'name' => 'system.listMethods',
 109                                      'method' => array(&$this, 'listMethods'),
 110                                      'help' => 'Lists available server methods.',
 111                                      'signature' => array(DOM_XMLRPC_TYPE_ARRAY))));
 112  
 113          $this->methodmapper->addMethod(new dom_xmlrpc_method(array(
 114                                      'name' => 'system.methodSignature',
 115                                      'method' => array(&$this, 'methodSignature'),
 116                                      'help' => 'Returns signature of specified method.',
 117                                      'signature' => array(DOM_XMLRPC_TYPE_ARRAY,DOM_XMLRPC_TYPE_STRING))));
 118  
 119          $this->methodmapper->addMethod(new dom_xmlrpc_method(array(
 120                                      'name' => 'system.methodHelp',
 121                                      'method' => array(&$this, 'methodHelp'),
 122                                      'help' => 'Returns help for the specified method.',
 123                                      'signature' => array(DOM_XMLRPC_TYPE_STRING,DOM_XMLRPC_TYPE_STRING))));
 124  
 125          $this->methodmapper->addMethod(new dom_xmlrpc_method(array(
 126                                      'name' => 'system.getCapabilities',
 127                                      'method' => array(&$this, 'getCapabilities'),
 128                                      'help' => 'Returns an array of supported server specifications.',
 129                                      'signature' => array(DOM_XMLRPC_TYPE_ARRAY))));
 130  
 131          $this->methodmapper->addMethod(new dom_xmlrpc_method(array(
 132                                      'name' => 'system.multicall',
 133                                      'method' => array(&$this, 'multicall'),
 134                                      'help' => 'Handles multiple, asynchronous XML-RPC calls bundled into a single request.',
 135                                      'signature' => array(DOM_XMLRPC_TYPE_ARRAY,DOM_XMLRPC_TYPE_ARRAY))));
 136      } //addSystemMethods
 137  
 138      /**
 139      * Adds user defined methods to the method map
 140      * @param object A map of custom methods
 141      */
 142  	function addCustomMethods($customMethods) {
 143          foreach ($customMethods as $key => $value) {
 144              $this->methodmapper->addMethod($customMethods[$key]);
 145          }
 146      } //addCustomMethods
 147  
 148      /**
 149      * Adds user defined methods to the method map
 150      * @param array An array of custom methods
 151      */
 152  	function addMethods($methodsArray) {
 153          foreach ($methodsArray as $key => $value) {
 154              $this->methodmapper->addMethod($methodsArray[$key]);
 155          }
 156      } //addMethods
 157  
 158      /**
 159      * Adds a single user defined method to the method map
 160      * @param array An array of custom methods
 161      */
 162  	function addMethod($method) {
 163          //expects an associative array
 164          $this->methodmapper->addMethod($method);
 165      } //addMethod
 166  
 167      /**
 168      * Adds a map of user defined method to the method map
 169      * @param object A map of custom methods
 170      * @param array A list of method names
 171      */
 172  	function addMappedMethods(&$methodmap, $methodNameList) {
 173          $this->methodmapper->addMappedMethods($methodmap, $methodNameList);
 174      } //addMethodMap
 175  
 176      /**
 177      * Specifies whether params should be tokenized
 178      * @param boolean True if params should be tokenized
 179      */
 180  	function tokenizeParams($truthVal) {
 181          //if true, params array will be split
 182          //into individual parameters
 183          $this->tokenizeParamsArray = $truthVal;
 184      } //tokenizeParams
 185  
 186  
 187      //************************************************************************
 188      //****************************system methods******************************
 189  
 190      /**
 191      * XML-RPC defined method: lists all available methods
 192      * @return array A list of method names
 193      */
 194  	function listMethods() {
 195          return $this->methodmapper->getMethodNames();
 196      } //listMethods
 197  
 198      /**
 199      * XML-RPC defined method: returns the signature of the specified method
 200      * @param string The method name
 201      * @return array The method signature
 202      */
 203  	function methodSignature($name) {
 204          $myMethod =& $this->methodmapper->getMethod($name);
 205          return $myMethod->signature;
 206      } //methodSignature
 207  
 208      /**
 209      * XML-RPC defined method: returns help on the specified method
 210      * @param string The method name
 211      * @return string Help on the method
 212      */
 213  	function methodHelp($name) {
 214          $myMethod =& $this->methodmapper->getMethod($name);
 215          return $myMethod->help;
 216      } //methodHelp
 217  
 218      /**
 219      * XML-RPC defined method: delineates what XML-RPC services are provided by the server
 220      * @return array The XML-RPC services provided by the server
 221      */
 222  	function getCapabilities() {
 223          $capabilities = array('xmlrpc' => array(
 224                                      'specUrl' => 'http://www.xmlrpc.com/spec',
 225                                      'specVersion' => 1),
 226                               'introspect' => array(
 227                                      'specUrl' => 'http://xmlrpc.usefulinc.com/doc/reserved.html',
 228                                      'specVersion' => 1),
 229                               'system.multicall' => array(
 230                                      'specUrl' => 'http://www.xmlrpc.com/discuss/msgReader$1208',
 231                                      'specVersion' => 1),
 232                               'faults_interop' => array(
 233                                      'specUrl' => 'http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php',
 234                                      'specVersion' => 3));
 235          return $capabilities;
 236      } //getCapabilities
 237  
 238      /**
 239      * Handles multiple method calls in a single request
 240      * @param array An array of method calls
 241      * @return array An array of method responses
 242      */
 243      function &multicall(&$myArray) {
 244          //call each method and store each result
 245          //in $this->multiresponse
 246          foreach ($myArray as $key => $value) {
 247              $currCall =& $myArray[$key];
 248              $methodName = $currCall[DOM_XMLRPC_TYPE_METHODNAME];
 249              $method =& $this->methodmapper->getMethod($methodName);
 250              $params = $currCall[DOM_XMLRPC_TYPE_PARAMS];
 251  
 252              if (!($method == null)) {
 253                  if ($this->tokenizeParamsArray) {
 254                      $this->multiresponse[] =& call_user_func_array($method->method, $params); //should I worry about < PHP 4.04?
 255                  }
 256                  else {
 257                      if (count($params) == 1) {
 258                          //if only one param, send $params[0]
 259                          //rather than than $params
 260                          $this->multiresponse[] =& call_user_func($method->method, $params[0]);
 261                      }
 262                      else {
 263                          //send the entire array
 264                          $this->multiresponse[] =& call_user_func($method->method, $params);
 265                      }
 266                  }
 267              }
 268              else { //method doesn't exist
 269                  ////return $this->handleMethodNotFound($methodName, $params);
 270              }
 271          }
 272  
 273          return $this->multiresponse;
 274      } //multicall
 275  
 276      //****************************system methods******************************
 277      //************************************************************************
 278  
 279      /**
 280      * Handles the POSTing of data to the server
 281      * @param string The POST data
 282      */
 283  	function onPost($postData) {
 284          global $HTTP_RAW_POST_DATA;
 285  
 286          if ($postData == null) $postData = $HTTP_RAW_POST_DATA;
 287          $this->respond($this->invokeMethod($postData));
 288      } //onPost
 289  
 290      /**
 291      * Invokes the method(s) in the XML request
 292      * @param string The XML text of the request
 293      * @return mixed The method response
 294      */
 295      function &invokeMethod($xmlText) {
 296          $xmlrpcdoc = $this->parseRequest($xmlText);
 297  
 298          if (!$this->isError()) {
 299              $methodName = $xmlrpcdoc->getMethodName();
 300              $method =& $this->methodmapper->getMethod($methodName);
 301              $params =& $xmlrpcdoc->getParams();
 302  
 303              if (!($method == null)) {
 304                  if ($this->tokenizeParamsArray) {
 305                      $response =& call_user_func_array($method->method, $params); //should I worry about < PHP 4.04?
 306                  }
 307                  else {
 308                      if (count($params) == 1) {
 309                          //if only one param, send $params[0]
 310                          //rather than than $params
 311                          $response =& call_user_func($method->method, $params[0]);
 312                      }
 313                      else {
 314                          //send the entire array
 315                          $response =& call_user_func($method->method, $params);
 316                      }
 317                  }
 318  
 319                  return $this->buildResponse($response);
 320              }
 321              else { //method doesn't exist
 322                  return $this->handleMethodNotFound($methodName, $params);
 323              }
 324          }
 325      } //invokeMethod
 326  
 327      /**
 328      * Default handler for a missing method
 329      * @param string The method name
 330      * @param mixed The method params
 331      * @return mixed A fault or user defined data
 332      */
 333      function &handleMethodNotFound($methodName, &$params) {
 334          if ($this->methodNotFoundHandler == null) {
 335              //raise exception, method doesn't exist
 336              $this->serverError = DOM_XMLRPC_SERVER_ERROR_REQUESTED_METHOD_NOT_FOUND;
 337              $this->serverErrorString = 'DOM XML-RPC Server Error - Requested method not found.';
 338              return $this->raiseFault();
 339          }
 340          else {
 341              //fire the custom event; pass in a reference to the server
 342              //so that a fault can be generated as with default handler above
 343              return call_user_func($this->methodNotFoundHandler, $this, $methodName, $params);
 344          }
 345      } //handleMethodNotFound
 346  
 347      /**
 348      * Sets the handler for a missing method
 349      * @param object A reference to the method not found handler
 350      */
 351  	function setMethodNotFoundHandler($method) {
 352          $this->methodNotFoundHandler =& $method;
 353      } //setMethodNotFoundHandler
 354  
 355      /**
 356      * Builds a method response or fault
 357      * @param object A reference to the method response data
 358      * @return mixed The method response or fault
 359      */
 360      function &buildResponse(&$response) {
 361          require_once (DOM_XMLRPC_INCLUDE_PATH . 'dom_xmlrpc_fault.php');
 362  
 363          if (is_object($response) && (get_class($response) == 'dom_xmlrpc_fault')) {
 364              return $this->buildFault($response);
 365          }
 366          else {
 367              return $this->buildMethodResponse($response);
 368          }
 369      } //buildResponse
 370  
 371      /**
 372      * Builds a method response
 373      * @param object A reference to the method response data
 374      * @return mixed The method response
 375      */
 376  	function buildMethodResponse($response) {
 377          require_once (DOM_XMLRPC_INCLUDE_PATH . 'dom_xmlrpc_methodresponse.php');
 378          $methodResponse = new dom_xmlrpc_methodresponse($response);
 379  
 380          return $methodResponse->toXML();
 381      } //buildMethodResponse
 382  
 383      /**
 384      * Determines whether an error has occurred
 385      * @return boolean True if an error has occurred
 386      */
 387  	function isError() {
 388          return ($this->serverError != -1);
 389      } //isError
 390  
 391      /**
 392      * Raises an XML-RPC fault
 393      * @return object An XML-RPC fault
 394      */
 395      function &raiseFault() {
 396          require_once (DOM_XMLRPC_INCLUDE_PATH . 'dom_xmlrpc_fault.php');
 397  
 398          $fault = new dom_xmlrpc_fault($this->serverError, $this->serverErrorString);
 399          return $this->buildFault($fault);
 400      } //raiseFault
 401  
 402      /**
 403      * Builds an XML-RPC fault
 404      * @param object A reference to the method response data
 405      * @return mixed The XML-RPC fault
 406      */
 407  	function buildFault($response) {
 408          require_once (DOM_XMLRPC_INCLUDE_PATH . 'dom_xmlrpc_methodresponse_fault.php');
 409          $fault = new dom_xmlrpc_methodresponse_fault($response);
 410  
 411          return $fault->toXML();
 412      } //buildFault
 413  
 414      /**
 415      * Sets object awareness to the specified value
 416      * @param boolean True if object awareness is to be enabled
 417      */
 418  	function setObjectAwareness($truthVal) {
 419          $this->objectAwareness = $truthVal;
 420      } //setObjectAwareness
 421  
 422      /**
 423      * Sets the handler for object handling
 424      * @param object The handler for object handling
 425      */
 426  	function setObjectDefinitionHandler($handler) {
 427          $this->objectDefinitionHandler =& $handler;
 428      } //setObjectDefinitionHandler
 429  
 430      /**
 431      * Parses the method request
 432      * @param string The text of the method request
 433      * @return mixed The method response document
 434      */
 435      function &parseRequest($xmlText) {
 436          if ($this->objectAwareness) {
 437              require_once (DOM_XMLRPC_INCLUDE_PATH . 'dom_xmlrpc_object_parser.php');
 438              $parser = new dom_xmlrpc_object_parser($this->objectDefinitionHandler);
 439          }
 440          else {
 441              require_once (DOM_XMLRPC_INCLUDE_PATH . 'dom_xmlrpc_array_parser.php');
 442              $parser = new dom_xmlrpc_array_parser();
 443          }
 444  
 445          if ($parser->parseXML($xmlText, false)) {
 446              return $parser->getArrayDocument();
 447          }
 448          else {
 449              //raise exception, parsing error
 450              $this->serverError = DOM_XMLRPC_PARSE_ERROR_NOT_WELL_FORMED;
 451              $this->serverErrorString = 'DOM XML-RPC Parse Error - XML document not well formed.';
 452              return null;
 453          }
 454      } //parseRequest
 455  
 456      /**
 457      * Raises fault if POST is not used for method request
 458      */
 459  	function onWrongRequestMethod() {
 460          //raise exception, POST method not used
 461          $this->serverError = DOM_XMLRPC_SERVER_ERROR_INTERNAL_XMLRPC;
 462          $this->serverErrorString = 'DOM XML-RPC Server Error - ' .
 463                  'Only POST method is allowed by the XML-RPC specification.';
 464  
 465          $this->respond($this->raiseFault());
 466      } //onWrongRequestMethod
 467  } //dom_xmlrpc_server
 468  
 469  
 470  /**
 471  * Represents an XML-RPC server method
 472  *
 473  * @package dom-xmlrpc
 474  * @author John Heinstein <johnkarl@nbnet.nb.ca>
 475  */
 476  class dom_xmlrpc_methods {
 477      /** @var array A list of methods */
 478      var $methods = array();
 479  
 480      /**
 481      * Adds a method to the method array
 482      * @param object The method to be added
 483      */
 484  	function addMethod(&$method) {
 485          $this->methods[$method->name] =& $method;
 486      } //addMethod
 487  
 488      /**
 489      * Retrieves a method from the method array
 490      * @param string The name of the method
 491      * @return object A reference to the requested method
 492      */
 493      function &getMethod($name) {
 494          if (isset($this->methods[$name])) {
 495              return $this->methods[$name];
 496          }
 497  
 498          return null;
 499      } //getMethod
 500  
 501      /**
 502      * Retrieves a list of methods in the method array
 503      * @return array A list of methods in the method array
 504      */
 505  	function getMethodNames() {
 506          return array_keys($this->methods);
 507      } //getMethodNames
 508  } //dom_xmlrpc_methods
 509  
 510  /**
 511  * Represents a map of methods available to the server
 512  *
 513  * @package dom-xmlrpc
 514  * @author John Heinstein <johnkarl@nbnet.nb.ca>
 515  */
 516  class dom_xmlrpc_methodmapper {
 517      /** @var array The method map */
 518      var $mappedmethods = array();
 519      /** @var array A dom_xmlrpc_methods instance */
 520      var $unmappedmethods;
 521  
 522      /**
 523      * Constructor: Instantiates a new methodmapper
 524      */
 525  	function dom_xmlrpc_methodmapper() {
 526          $this->unmappedmethods = new dom_xmlrpc_methods();
 527      } //dom_xmlrpc_methodmapper
 528  
 529      /**
 530      * Adds a method to the method map
 531      * @param object The method to be added
 532      */
 533  	function addMethod(&$method) {
 534          $this->unmappedmethods->addMethod($method);
 535          $this->mappedmethods[$method->name] =& $this->unmappedmethods;
 536      } //addMethod
 537  
 538      /**
 539      * Adds a method map to the method map
 540      * @param object The method map to be added
 541      */
 542  	function addMappedMethods(&$methodmap, $methodNameList) {
 543          $total = count($methodNameList);
 544  
 545          for ($i = 0; $i < $total; $i++) {
 546              $this->mappedmethods[$methodNameList[$i]] =& $methodmap;
 547          }
 548      } //addMappedMethods
 549  
 550      /**
 551      * Retrieves a method from the method map
 552      * @param string The name of the method
 553      * @return object A reference to the requested method
 554      */
 555      function &getMethod($name) {
 556          if (isset($this->mappedmethods[$name])) {
 557              $methodmap =& $this->mappedmethods[$name];
 558              return $methodmap->getMethod($name);
 559          }
 560  
 561          return null;
 562      } //getMethod
 563  
 564      /**
 565      * Retrieves a list of methods in the method array
 566      * @return array A list of methods in the method array
 567      */
 568  	function getMethodNames() {
 569          return array_keys($this->mappedmethods);
 570      } //getMethodNames
 571  } //dom_xmlrpc_methodmapper
 572  
 573  /**
 574  * Represents a server method
 575  *
 576  * @package dom-xmlrpc
 577  * @author John Heinstein <johnkarl@nbnet.nb.ca>
 578  */
 579  class dom_xmlrpc_method {
 580      /** @var string The method name */
 581      var $name;
 582      /** @var object A reference to the metho */
 583      var $method;
 584      /** @var string Help for the method */
 585      var $help = '';
 586      /** @var array The method signature */
 587      var $signature = '';
 588  
 589      /**
 590      * Constructor: Instantiates a custom method
 591      * @param array A method name, reference, signature, and help
 592      */
 593  	function dom_xmlrpc_method($paramArray) {
 594          $this->name = $paramArray['name'];
 595          $this->method =& $paramArray['method'];
 596  
 597          if (isset($paramArray['help'])) {
 598              $this->help = $paramArray['help'];
 599          }
 600  
 601          if (isset($paramArray['signature'])) {
 602              $this->signature = $paramArray['signature'];
 603          }
 604      } //dom_xmlrpc_method
 605  } //dom_xmlrpc_method
 606  
 607  /**
 608  * Abstract class for a method map
 609  *
 610  * @package dom-xmlrpc
 611  * @author John Heinstein <johnkarl@nbnet.nb.ca>
 612  */
 613  class dom_xmlrpc_methodmap {
 614      /**
 615      * Retrieves a method from the method array
 616      * @param string The name of the method
 617      * @return object A reference to the requested method
 618      */
 619      function &getMethod($methodName) {
 620          //override this method
 621      } //getMethod
 622  } //dom_xmlrpc_methodmap
 623  
 624  
 625  /*
 626  //To invoke the server, do:
 627  $httpServer = new dom_xmlrpc_server();
 628  $httpServer->addMethod($someMethod);
 629  $httpServer->receive(); //will grab $HTTP_RAW_POST_DATA
 630  
 631  //abbreviated format, will use $postData instead of $HTTP_RAW_POST_DATA
 632  $httpServer = new dom_xmlrpc_server($methods, $postData);
 633  */
 634  
 635  ?>