Web service first version.

git-svn-id: http://piwigo.org/svn/trunk@1698 68402e56-0260-453c-a942-63ccdbb3a9ee

1 files changed, 611 insertions, 0 deletions

diff --git a/include/ws_core.inc.php b/include/ws_core.inc.php
new file mode 100644
index 000000000..61c94b295
--- /dev/null
+++ b/include/ws_core.inc.php
@@ -0,0 +1,611 @@
+<?php
+// +-----------------------------------------------------------------------+
+// | PhpWebGallery - a PHP based picture gallery                           |
+// | Copyright (C) 2003-2007 PhpWebGallery Team - http://phpwebgallery.net |
+// +-----------------------------------------------------------------------+
+// | branch        : BSF (Best So Far)
+// | file          : $URL: svn+ssh://rvelices@svn.gna.org/svn/phpwebgallery/trunk/action.php $
+// | last update   : $Date: 2006-12-21 18:49:12 -0500 (Thu, 21 Dec 2006) $
+// | last modifier : $Author: rvelices $
+// | revision      : $Rev: 1678 $
+// +-----------------------------------------------------------------------+
+// | This program is free software; you can redistribute it and/or modify  |
+// | it under the terms of the GNU General Public License as published by  |
+// | the Free Software Foundation                                          |
+// |                                                                       |
+// | This program is distributed in the hope that it will be useful, but   |
+// | WITHOUT ANY WARRANTY; without even the implied warranty of            |
+// | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU      |
+// | General Public License for more details.                              |
+// |                                                                       |
+// | You should have received a copy of the GNU General Public License     |
+// | along with this program; if not, write to the Free Software           |
+// | Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, |
+// | USA.                                                                  |
+// +-----------------------------------------------------------------------+
+
+/**** WEB SERVICE CORE CLASSES************************************************
+ * PwgServer - main object - the link between web service methods, request
+ *  handler and response encoder
+ * PwgRequestHandler - base class for handlers
+ * PwgResponseEncoder - base class for response encoders
+ * PwgError, PwgNamedArray, PwgNamedStruct - can be used by web service functions
+ * as return values
+ */
+
+
+define( 'WS_PARAM_ACCEPT_ARRAY',  0x010000 );
+define( 'WS_PARAM_FORCE_ARRAY',   0x030000 );
+define( 'WS_PARAM_OPTIONAL',      0x040000 );
+
+define( 'WS_ERR_INVALID_METHOD',  1001 );
+define( 'WS_ERR_MISSING_PARAM',   1002 );
+define( 'WS_ERR_INVALID_PARAM',   1003 );
+
+define( 'WS_XML_ATTRIBUTES', 'attributes_xml_');
+define( 'WS_XML_CONTENT', 'content_xml_');
+
+/**
+ * PwgError object can be returned from any web service function implementation.
+ */
+class PwgError
+{
+  var $_code;
+  var $_codeText;
+
+  function PwgError($code, $codeText)
+  {
+    $this->_code = $code;
+    $this->_codeText = $codeText;
+  }
+
+  function code() { return $this->_code; }
+  function message() { return $this->_codeText; }
+}
+
+/**
+ * Simple wrapper around an array (keys are consecutive integers starting at 0).
+ * Provides naming clues for xml output (xml attributes vs. xml child elements?)
+ * Usually returned by web service function implementation.
+ */
+class PwgNamedArray
+{
+  /*private*/ var $_content;
+  /*private*/ var $_itemName;
+  /*private*/ var $_xmlAttributes;
+
+  /**
+   * Constructs a named array
+   * @param arr array (keys must be consecutive integers starting at 0)
+   * @param itemName string xml element name for values of arr (e.g. image)
+   * @param xmlAttributes array of sub-item attributes that will be encoded as
+   *      xml attributes instead of xml child elements
+   */
+  function PwgNamedArray(&$arr, $itemName, $xmlAttributes=array() )
+  {
+    $this->_content = $arr;
+    $this->_itemName = $itemName;
+    $this->_xmlAttributes = array_flip($xmlAttributes);
+  }
+}
+/**
+ * Simple wrapper around a "struct" (php array whose keys are not consecutive
+ * integers starting at 0). Provides naming clues for xml output (what is xml
+ * attributes and what is element)
+ */
+class PwgNamedStruct
+{
+  /*private*/ var $_content;
+  /*private*/ var $_name;
+  /*private*/ var $_xmlAttributes;
+
+  /**
+   * Constructs a named struct (usually returned by web service function
+   * implementation)
+   * @param name string - containing xml element name
+   * @param content array - the actual content (php array)
+   * @param xmlAttributes array - name of the keys in $content that will be
+   *    encoded as xml attributes (if null - automatically prefer xml attributes
+   *    whenever possible)
+   */
+  function PwgNamedStruct($name, $content, $xmlAttributes=null, $xmlElements=null )
+  {
+    $this->_name = $name;
+    $this->_content = $content;
+    if ( isset($xmlAttributes) )
+    {
+      $this->_xmlAttributes = array_flip($xmlAttributes);
+    }
+    else
+    {
+      $this->_xmlAttributes = array();
+      foreach ($this->_content as $key=>$value)
+      {
+        if (!empty($key) and (is_scalar($value) or is_null($value)) )
+        {
+          if ( empty($xmlElements) or !in_array($key,$xmlElements) )
+          {
+            $this->_xmlAttributes[$key]=1;
+          }
+        }
+      }
+    }
+  }
+}
+
+
+/**
+ * Replace array_walk_recursive()
+ *
+ * @category    PHP
+ * @package     PHP_Compat
+ * @link        http://php.net/function.array_walk_recursive
+ * @author      Tom Buskens <ortega@php.net>
+ * @author      Aidan Lister <aidan@php.net>
+ * @version     $Revision: 1.7 $
+ * @since       PHP 5
+ * @require     PHP 4.0.6 (is_callable)
+ */
+if (!function_exists('array_walk_recursive')) {
+    function array_walk_recursive(&$input, $funcname)
+    {
+        if (!is_callable($funcname)) {
+            if (is_array($funcname)) {
+                $funcname = $funcname[0] . '::' . $funcname[1];
+            }
+            user_error('array_walk_recursive() Not a valid callback ' . $user_func,
+                E_USER_WARNING);
+            return;
+        }
+
+        if (!is_array($input)) {
+            user_error('array_walk_recursive() The argument should be an array',
+                E_USER_WARNING);
+            return;
+        }
+
+        $args = func_get_args();
+
+        foreach ($input as $key => $item) {
+            if (is_array($item)) {
+                array_walk_recursive($item, $funcname, $args);
+                $input[$key] = $item;
+            } else {
+                $args[0] = &$item;
+                $args[1] = &$key;
+                call_user_func_array($funcname, $args);
+                $input[$key] = $item;
+            }
+        }
+    }
+}
+
+/**
+ * Abstract base class for request handlers.
+ */
+class PwgRequestHandler
+{
+  /** Virtual abstract method. Decodes the request (GET or POST) handles the
+   * method invocation as well as response sending.
+   */
+  function handleRequest(&$server) { assert(false); }
+}
+
+/**
+ *
+ * Base class for web service response encoder.
+ */
+class PwgResponseEncoder
+{
+  /** encodes the web service response to the appropriate output format
+   * @param response mixed the unencoded result of a service method call
+   */
+  function encodeResponse($response) { assert(false); }
+
+  /** default "Content-Type" http header for this kind of response format
+   */
+  function getContentType() { assert(false); }
+
+  /**
+   * returns true if the parameter is a 'struct' (php array type whose keys are
+   * NOT consecutive integers starting with 0)
+   */
+  function is_struct(&$data)
+  {
+    if (is_array($data) )
+    {
+      if (range(0, count($data) - 1) !== array_keys($data) )
+      { # string keys, unordered, non-incremental keys, .. - whatever, make object
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * removes all XML formatting from $response (named array, named structs, etc)
+   * usually called by every response encoder, except rest xml.
+   */
+  function flattenResponse(&$response)
+  {
+    PwgResponseEncoder::_mergeAttributesAndContent($response);
+    PwgResponseEncoder::_removeNamedArray($response);
+    PwgResponseEncoder::_removeNamedStruct($response);
+    if (is_array($response))
+    { // need to call 2 times (first time might add new arrays)
+      array_walk_recursive($response, array('PwgResponseEncoder', '_remove_named_callback') );
+      array_walk_recursive($response, array('PwgResponseEncoder', '_remove_named_callback') );
+    }
+//print_r($response);
+    PwgResponseEncoder::_mergeAttributesAndContent($response);
+  }
+
+  /*private*/ function _remove_named_callback(&$value, $key)
+  {
+    do
+    {
+      $changed = 0;
+      $changed += PwgResponseEncoder::_removeNamedArray($value);
+      $changed += PwgResponseEncoder::_removeNamedStruct($value);
+  //    print_r('walk '.$key."<br/>\n");
+    }
+    while ($changed);
+  }
+
+  /*private*/ function _mergeAttributesAndContent(&$value)
+  {
+    if ( !is_array($value) )
+      return;
+/*    $first_key = '';
+    if (count($value)) { $ak = array_keys($value); $first_key = $ak[0]; }
+
+    print_r( '_mergeAttributesAndContent is_struct='.PwgResponseEncoder::is_struct($value)
+      .' count='.count($value)
+      .' first_key='.$first_key
+      ."<br/>\n"
+      );*/
+    $ret = 0;
+    if (PwgResponseEncoder::is_struct($value))
+    {
+      if ( isset($value[WS_XML_ATTRIBUTES]) )
+      {
+        $value = array_merge( $value, $value[WS_XML_ATTRIBUTES] );
+        unset( $value[WS_XML_ATTRIBUTES] );
+        $ret=1;
+      }
+      if ( isset($value[WS_XML_CONTENT]) )
+      {
+        $cont_processed = 0;
+        if ( count($value)==1 )
+        {
+          $value = $value[WS_XML_CONTENT];
+          $cont_processed=1;
+        }
+        else
+        {
+          if (PwgResponseEncoder::is_struct($value[WS_XML_CONTENT]))
+          {
+            $value = array_merge( $value, $value[WS_XML_CONTENT] );
+            unset( $value[WS_XML_CONTENT] );
+            $cont_processed=1;
+          }
+        }
+        $ret += $cont_processed;
+        if (!$cont_processed)
+        {
+          $value['_content'] = $value[WS_XML_CONTENT];
+          unset( $value[WS_XML_CONTENT] );
+          $ret++;
+        }
+      }
+    }
+
+    foreach ($value as $key=>$v)
+    {
+      if ( PwgResponseEncoder::_mergeAttributesAndContent($v) )
+      {
+        $value[$key]=$v;
+        $ret++;
+      }
+    }
+    return $ret;
+  }
+
+  /*private*/ function _removeNamedArray(&$value)
+  {
+    if ( strtolower( get_class($value) ) =='pwgnamedarray')
+    {
+      $value = $value->_content;
+      return 1;
+    }
+    return 0;
+  }
+
+  /*private*/ function _removeNamedStruct(&$value)
+  {
+    if ( strtolower( get_class($value) ) =='pwgnamedstruct')
+    {
+      if ( isset($value->_content['']) )
+      {
+        $unknown = $value->_content[''];
+        unset( $value->_content[''] );
+        $value->_content[$value->_name] = $unknown;
+      }
+      $value = $value->_content;
+      return 1;
+    }
+    return 0;
+  }
+}
+
+
+
+class PwgServer
+{
+  var $_requestHandler;
+  var $_requestFormat;
+  var $_responseEncoder;
+  var $_responseFormat;
+
+  var $_methods;
+  var $_methodSignatures;
+
+  function PwgServer()
+  {
+    $methods = array();
+  }
+
+  /**
+   *  Initializes the request handler.
+   */
+  function setHandler($requestFormat, &$requestHandler)
+  {
+    $this->_requestHandler = &$requestHandler;
+    $this->_requestFormat = $requestFormat;
+  }
+
+  /**
+   *  Initializes the request handler.
+   */
+  function setEncoder($responseFormat, &$encoder)
+  {
+    $this->_responseEncoder = &$encoder;
+    $this->_responseFormat = $responseFormat;
+  }
+
+  /**
+   * Runs the web service call (handler and response encoder should have been
+   * created)
+   */
+  function run()
+  {
+    if ( is_null($this->_responseEncoder) )
+    {
+      @header("HTTP/1.1 500 Server error");
+      @header("Status: 500 Server error");
+      @header("Content-Type: text/plain");
+      echo ("Cannot process your request. Unknown response format.
+Request format: ".@$this->_requestFormat." handler:".$this->_requestHandler."
+Response format: ".@$this->_responseFormat." encoder:".$this->_responseEncoder."
+    ");
+      var_export($this);
+      die(0);
+    }
+
+    if ( is_null($this->_requestHandler) )
+    {
+      $this->sendResponse(
+        new PwgError(500, 'Unknown request format')
+        );
+      return;
+    }
+
+    $this->addMethod('reflection.getMethodList',
+        array('PwgServer', 'ws_getMethodList'),
+        null, '' );
+    $this->addMethod('reflection.getMethodDetails',
+        array('PwgServer', 'ws_getMethodDetails'),
+        array('methodName'),'');
+
+    trigger_action('ws_add_methods', array(&$this) );
+    uksort( $this->_methods, 'strnatcmp' );
+    $this->_requestHandler->handleRequest($this);
+  }
+
+  /**
+   * Encodes a response and sends it back to the browser.
+   */
+  function sendResponse($response)
+  {
+    $encodedResponse = $this->_responseEncoder->encodeResponse($response);
+    $contentType = $this->_responseEncoder->getContentType();
+
+    @header('Content-Type: '.$contentType);
+    print_r($encodedResponse);
+  }
+
+  /**
+   * Registers a web service method.
+   * @param methodName string - the name of the method as seen externally
+   * @param callback mixed - php method to be invoked internally
+   * @param params array - map of allowed parameter names with optional default
+   * values and parameter flags. Example of $params:
+   * array( 'param1' => array('default'=>523, 'flags'=>WS_PARAM_FORCE_ARRAY) ) .
+   * Possible parameter flags are:
+   * WS_PARAM_ALLOW_ARRAY - this parameter can be an array
+   * WS_PARAM_FORCE_ARRAY - if this parameter is scalar, force it to an array
+   *  before invoking the method
+   * @param description string - a description of the method.
+   */
+  function addMethod($methodName, $callback, $params=array(), $description, $include_file='')
+  {
+    $this->_methods[$methodName] = $callback;
+    $this->_methodDescriptions[$methodName] = $description;
+
+    if (!is_array($params))
+    {
+      $params = array();
+    }
+
+    if ( range(0, count($params) - 1) === array_keys($params) )
+    {
+      $params = array_flip($params);
+    }
+
+    foreach( $params as $param=>$options)
+    {
+      if ( !is_array($options) )
+      {
+        $params[$param] = array('flags'=>0);
+      }
+      else
+      {
+        $flags = isset($options['flags']) ? $options['flags'] : 0;
+        if ( array_key_exists('default', $options) )
+        {
+          $flags |= WS_PARAM_OPTIONAL;
+        }
+        $options['flags'] = $flags;
+        $params[$param] = $options;
+      }
+    }
+    $this->_methodSignatures[$methodName] = $params;
+  }
+
+  function hasMethod($methodName)
+  {
+    return isset($this->_methods[$methodName]);
+  }
+
+  function getMethodDescription($methodName)
+  {
+    $desc = @$this->_methodDescriptions[$methodName];
+    return isset($desc) ? $desc : '';
+  }
+
+  function getMethodSignature($methodName)
+  {
+    $signature = @$this->_methodSignatures[$methodName];
+    return isset($signature) ? $signature : array();
+  }
+
+  /*static*/ function isPost()
+  {
+    return isset($HTTP_RAW_POST_DATA) or !empty($_POST);
+  }
+
+  /*static*/ function makeArrayParam(&$param)
+  {
+    if ( $param==null )
+    {
+      $param = array();
+    }
+    else
+    {
+      if (! is_array($param) )
+      {
+        $param = array($param);
+      }
+    }
+  }
+
+  /**
+   *  Invokes a registered method. Returns the return of the method (or
+   *  a PwgError object if the method is not found)
+   *  @param methodName string the name of the method to invoke
+   *  @param params array array of parameters to pass to the invoked method
+   */
+  function invoke($methodName, $params)
+  {
+    $callback = @$this->_methods[$methodName];
+
+    if ( $callback==null )
+    {
+      return new PwgError(WS_ERR_INVALID_METHOD, 'Method name "'.$methodName.'" is not valid');
+    }
+
+    // parameter check and data coercion !
+    $signature = @$this->_methodSignatures[$methodName];
+    $missing_params = array();
+    foreach($signature as $name=>$options)
+    {
+      $flags = $options['flags'];
+      if ( !array_key_exists($name, $params) )
+      {// parameter not provided in the request
+        if ( !($flags&WS_PARAM_OPTIONAL) )
+        {
+          $missing_params[] = $name;
+        }
+        else if ( array_key_exists('default',$options) )
+        {
+          $params[$name] = $options['default'];
+          if ( ($flags&WS_PARAM_FORCE_ARRAY) )
+          {
+            $this->makeArrayParam( $params[$name] );
+          }
+        }
+      }
+      else
+      {// parameter provided - do some basic checks
+        $the_param = $params[$name];
+        if ( is_array($the_param) and ($flags&WS_PARAM_ACCEPT_ARRAY)==0 )
+        {
+          return new PwgError(WS_ERR_INVALID_PARAM, $name.' must be scalar' );
+        }
+        if ( ($flags&WS_PARAM_FORCE_ARRAY) )
+        {
+          $this->makeArrayParam( $the_param );
+        }
+        $params[$name] = $the_param;
+      }
+    }
+    if (count($missing_params))
+    {
+      return new PwgError(WS_ERR_MISSING_PARAM, 'Missing parameters: '.implode(',',$missing_params));
+    }
+
+    $result = call_user_func_array($callback, array($params, &$this) );
+    return $result;
+  }
+
+  /**
+   * WS reflection method implementation: lists all available methods
+   */
+  /*static*/ function ws_getMethodList($params, &$service)
+  {
+    return array('methods' => new PwgNamedArray( array_keys($service->_methods),'method' ) );
+  }
+
+  /**
+   * WS reflection method implementation: gets information about a given method
+   */
+  /*static*/ function ws_getMethodDetails($params, &$service)
+  {
+    $methodName = $params['methodName'];
+    if (!$service->hasMethod($methodName))
+    {
+      return new PwgError(WS_ERR_INVALID_PARAM,
+            'Requested method does not exist');
+    }
+    $res = array(
+      'name' => $methodName,
+      'description' => $service->getMethodDescription($methodName),
+      'params' => array(),
+    );
+    $signature = $service->getMethodSignature($methodName);
+    foreach ($signature as $name => $options)
+    {
+      $param_data = array(
+        'name' => $name,
+        'optional' => ($options['flags']&WS_PARAM_OPTIONAL)?true:false,
+        );
+      if (isset($options['default']))
+      {
+        $param_data['defaultValue'] = $options['default'];
+      }
+      $res['params'][] = $param_data;
+    }
+    return $res;
+  }
+}
+?>