CapableServer.php

<?php
/*
 * This file is part of XRL, a simple XML-RPC Library for PHP.
 *
 * Copyright (c) 2012, XRL Team. All rights reserved.
 * XRL is licensed under the 3-clause BSD License.
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace fpoirotte\XRL;

class CapableServer
{
    protected $server;

    protected $whitelist;

    protected function __construct(\fpoirotte\XRL\Server $server, array $whitelist = null)
    {
        $this->server       = $server;
        $this->whitelist    = $whitelist;
    }

    public static function enable(\fpoirotte\XRL\Server $server, array $whitelist = null)
    {
        $wrapper = new static($server, $whitelist);
        $server->expose($wrapper, 'system');
        return $server;
    }

    protected static function extractTypes($doc)
    {
        $doc    = trim(substr($doc, 3, -2), " \t\r\n*");
        $doc    = str_replace(array("\r\n", "\r"), "\n", $doc);
        $lines  = explode("\n", $doc . "\n");

        $tag    = null;
        $tags   = array(
            'params'    => array(),
            'retval'    => 'null',
        );
        $buffer = '';

        foreach ($lines as $line) {
            $line = trim($line, " \r\n\t*");

            if ($tag !== null && $line === '') {
                switch ($tag) {
                    case 'param':
                        $type = (string) substr($buffer, 0, strcspn($buffer, " \r\n\t"));
                        $buffer = ltrim(substr($buffer, strcspn($buffer, " \r\n\t")));
                        if (strncmp($buffer, '$', 1)) {
                            break;
                        }

                        $name = (string) substr($buffer, 1, strcspn($buffer, " \r\n\t") - 1);
                        $tags['params'][$name] = $type;
                        break;

                    case 'retval':
                        $type = (string) substr($buffer, 0, strcspn($buffer, " \r\n\t"));
                        $tags['retval'] = $type;
                        break;
                }

                $tag    = null;
                $buffer = '';
                continue;
            }

            if ($tag === null) {
                // \command or @command.
                if (!strncmp($line, '\\', 1) || !strncmp($line, '@', 1)) {
                    $tag    = (string) substr($line, 1, strcspn($line, " \r\n\t") - 1);
                    $buffer = ltrim(substr($line, strcspn($line, " \r\n\t")));
                }
            } else {
                // Continuation of previous paragraph.
                $buffer .= "\n$line";
            }
        }
        return $tags;
    }

    protected static function adaptType($type)
    {
        switch ($type) {
            case 'integer':
                return 'int';

            case 'float':
                return 'double';

            case 'null':
                return 'nil';

            case 'DateTime':
                return 'dateTime.iso8601';

            case 'boolean':
                return 'bool';

            case 'int':
            case 'double':
            case 'string':
            case 'bool':
            case 'array':
                return $type;
        }
        return null;
    }

    public function getCapabilities()
    {
        return array(
            'xmlrpc' => array(
                'specUrl'       => 'http://www.xmlrpc.com/spec',
                'specVersion'   => 1,
            ),

            'introspect' => array(
                'specUrl'       => 'http://xmlrpc-c.sourceforge.net/xmlrpc-c/introspection.html',
                'specVersion'   => 1,
            ),

            'faults_interop' => array(
                'specUrl'       => 'http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php',
                'specVersion'   => 20010516,
            ),
        );
    }

    public function listMethods()
    {
        $methods = array_keys($this->server->getIterator()->getArrayCopy());
        if ($this->whitelist !== null) {
            $methods = array_values(array_intersect($methods, $this->whitelist));
        }
        return $methods;
    }

    public function methodSignature($method)
    {
        if (!is_string($method) || !isset($this->server[$method])) {
            throw new \InvalidArgumentException('Invalid method');
        }

        $reflector  = $this->server[$method]->getReflector();
        $doc        = $reflector->getDocComment();
        if ($doc === false) {
            return 'undef';
        }

        $tags       = static::extractTypes($doc);
        $returnType = static::adaptType($tags['retval']);
        if ($returnType === null) {
            return 'undef';
        }

        $params     = array();
        foreach ($reflector->getParameters() as $param) {
            if (!isset($tags['params'][$param->getName()])) {
                return 'undef';
            }
            $type       = static::adaptType($tags['params'][$param->getName()]);
            if ($type === null) {
                return 'undef';
            }
            $params[]   = $type;
        }

        return array(array_merge(array($returnType), $params));
    }

    public function methodHelp($method)
    {
        if (!is_string($method) || !isset($this->server[$method])) {
            throw new \InvalidArgumentException('Invalid method');
        }

        $reflector  = $this->server[$method]->getReflector();
        $doc        = $reflector->getDocComment();
        if ($doc === false) {
            return '';
        }

        // Remove comment delimiters.
        $doc    = substr($doc, 2, -2);

        // Normalize line endings.
        $doc    = str_replace(array("\r\n", "\r"), "\n", $doc);

        // Trim leading/trailing whitespace and '*' for every line.
        $help   = array_map(
            function ($l) {
                return trim(trim($l), '*');
            },
            explode("\n", $doc)
        );

        // Count number of empty columns on non-empty lines
        // before the actual start of the text.
        $cols = min(
            array_map(
                function ($l) {
                    return strspn($l, " \t");
                },
                array_filter($help, 'strlen')
            )
        );

        // Remove those columns from the result.
        $help = array_map(
            function ($l) use ($cols) {
                return (string) substr($l, $cols);
            },
            $help
        );

        // Produce the final output.
        return implode("\n", $help);
    }

    public function multicall(array $requests)
    {
        $responses = array();
        foreach ($requests as $request) {
            try {
                if (!is_array($request)) {
                    throw new \BadFunctionCallException('Expected struct');
                }
                if (!isset($request['methodName'])) {
                    throw new \BadFunctionCallException('Missing methodName');
                }
                if (!isset($request['params'])) {
                    throw new \BadFunctionCallException('Missing params');
                }
                if (!is_array($request['params'])) {
                    throw new \BadFunctionCallException('Invalid params');
                }
                if ($request['methodName'] === 'system.multicall') {
                    throw new \BadFunctionCallException('Recursive call');
                }

                $result = $this->server->call($request['methodName'], $request['params']);
                // Results are wrapped in an array to make it possible
                // to distinguish between faults and regular structs.
                $responses[] = array($result);
            } catch (\Exception $error) {
                $responses[] = $error;
            }
        }
        return $responses;
    }
}