PHPXMLRPC

The library supports several reserved system.* methods for server introspection:

• system.getCapabilities: Lists the server's supported extensions.
• system.listMethods: Returns an array of strings containing the names of all implemented methods.
• system.methodSignature: Returns an array of possible signatures (types) for a specific method. If no signature is defined, it returns a non-array value.
• system.methodHelp: Returns a documentation string (may contain HTML) for a method.
• system.multicall: Allows executing multiple method calls in a single request by passing an array of request structs (each containing methodName and params).

To transfer PHP object instances, use PhpXmlRpc\Encoder::encode and PhpXmlRpc\Encoder::decode with specific options:

1. Sender side: Use the option 'encode_php_objs'. This creates an XML-RPC struct with an extra php_class attribute.
2. Receiver side: Use the option 'decode_php_objs'. This converts the struct back into an object of the original class.

WARNING: Enabling 'decode_php_objs' is a security risk. It invokes the object's constructor without parameters, which can allow a remote client to trigger uncontrolled code execution. Only use this with completely trusted remote servers.

Before using phpxmlrpc, ensure your environment meets the following criteria:

• PHP Version: 5.4.0 or later.
• curl extension: Required if you need to communicate with remote servers using HTTPS, HTTP2, HTTP 1.1, or NTLM Auth.
• mbstring extension (Optional): If installed, allows handling requests/responses in character sets other than ASCII, LATIN-1, or UTF-8.
• zlib extension (Optional): If installed, allows sending compressed requests and receiving compressed responses (even without the curl extension).
• xmlrpc native extension (Optional): If the native PHP xmlrpc extension is installed, it will not interfere with this library.

The recommended way to run tests is via the provided Docker containers using the vm.sh helper script.

Note: The test suite is not included in the default Composer installation. To include it, install using the --prefer-install=source flag.

Test Workflow

Execute the following sequence:

./tests/ci/vm.sh build
./tests/ci/vm.sh start
./tests/ci/vm.sh runtests
./tests/ci/vm.sh stop
./tests/ci/vm.sh cleanup

Advanced Testing

• Code Coverage: Run ./tests/ci/vm.sh runcoverage to generate a report.
• Custom Environment: Set PHP_VERSION and UBUNTU_VERSION environment variables before the build step to change the runtime environment.

If you are running the demo files separately from the main PHPXMLRPC library, you must ensure the class autoloading configuration is correct so the demos can locate the library's source files. You can achieve this in one of two ways:

1. Move the folder: Move the demo folder to the root directory of the phpxmlrpc library (placing it next to debugger, doc, lib, and src).
2. Edit include paths: Manually update the include paths in the following files:
   • client/_prepend.php
   • server/_prepend.php

Change the line include_once __DIR__ . '/../../src/Autoloader.php'; to point to the absolute or relative path of your phpxmlrpc/src folder.

// Edit this line in client/_prepend.php and server/_prepend.php
include_once __DIR__ . '/../../src/Autoloader.php';

The recommended method for installing the PHPXMLRPC library is using Composer. For detailed installation steps and a list of system requirements, refer to the INSTALL.md file in the repository.

If you want to include the code examples located in the demo/ directory in your local installation, use the --prefer-install=source flag with Composer.

Security Note: Ensure that the demo/ folder is not directly accessible from the internet (i.e., it should not be within your webserver's root directory).

composer require phpxmlrpc/phpxmlrpc

# To include demo files locally:
composer require phpxmlrpc/phpxmlrpc --prefer-install=source

For advanced XML-RPC server features, refer to the phpxmlrpc/extras package. The demos in that package showcase capabilities such as:

• Automatically generating HTML documentation for all exposed XML-RPC methods.
• Acting as a reverse proxy.
• Generating JavaScript code to facilitate calling exposed XML-RPC methods.

The library includes a web-based debugger for development and testing.

Security Warning: To prevent your webserver from becoming an open relay, keep the debugger folder outside your webserver's document root in production.

Basic Setup

To run the debugger, your webserver must serve the /debugger folder. The simplest method is using the PHP CLI web server with the experimental multi-process setup:

cd debugger; PHP_CLI_SERVER_WORKERS=2 php -S 127.0.0.1:8081

Then access it via http://127.0.0.1:8081.

Enable Visual Editor

To use the JSXMLRPC visual editor for constructing payloads, you must install it separately. If the provided taskfile fails, use npm:

# Option 1: Using taskfile
./taskfile setup_debugger_visualeditor

# Option 2: Using npm
cd debugger && npm install @jsxmlrpc/jsxmlrpc

If you cannot use Composer, you can install the library manually:

1. Download the zip or tarball from GitHub and unzip it.
2. Copy the contents of the src/ folder to your application's required location.
3. Configure your application's autoloader (PSR-4 compliant) to load classes in the PhpXmlRpc namespace from that location. If you do not have an autoloader, use the one provided in src/Autoloader.php.
4. Include your autoloader in your script.

Security Warning: Ensure the phpxmlrpc root directory is not directly accessible from the internet.

// File example: script.php
require_once __DIR__.'my_autoloader.php';

use PhpXmlRpc\Value;
use PhpXmlRpc\Request;
use PhpXmlRpc\Client;

$client = new Client('https://some/server');
$response = $client->send(new Request('method', array(new Value('parameter'))));

When upgrading from version 3 or earlier to version 4, you have two options:

1. Adapt your code: Update your implementation to match the new API. Detailed changes are documented in the official API changes guide.
2. Use the compatibility layer: Utilize the provided layer to maintain existing code functionality.

In version 4, manual file inclusion (e.g., xmlrpc.inc) is no longer required. It is recommended to use class autoloading.

Using Composer

Declare the dependency in your composer.json:

"require": {
    "phpxmlrpc/phpxmlrpc": "~4.0"
}

Without Composer

Use the provided autoloader located in src/Autoloader.php:

include_once <path to library> . "/src/Autoloader.php";
PhpXmlRpc\Autoloader::register();

Note: If you continue to manually include xmlrpc.inc, xmlrpcs.inc, or xmlrpc_wrappers.inc, the library will include all source files automatically and you won't need to set up an autoloader.