Getting Started

Minimal Steps to Begin

Installation
```
composer require laminas/laminas-xmlrpc:^3.0
```
- Note: This is a major version upgrade (3.0.0). Verify compatibility with PHP 8.1+ and Laravel’s dependencies.
- Check composer.json for version constraints (strict semantic versioning now enforced).
First Use Case: Client Request (Updated for 3.0.0)
```
use Laminas\XmlRpc\Client;

$client = new Client('http://example.com/RPC2');
$response = $client->call('example.method', ['param1', 'param2']);
print_r($response);
```
- Key Change: Removed dependency on laminas/laminas-http (now uses native PHP streams).
- Verify the endpoint supports XML-RPC (e.g., WordPress, legacy APIs).

First Use Case: Server Setup (Updated for 3.0.0)

use Laminas\XmlRpc\Server;

$server = new Server();
$server->register('add', fn($a, $b) => $a + $b); // Closure syntax now preferred
$server->handle(file_get_contents('php://input')); // Explicit input handling

Laravel Integration:

Route::post('/xmlrpc', function () {
    $server = new Server();
    $server->register('laravel.method', [MyService::class, 'handleRpc']);
    return $server->handle(file_get_contents('php://input'));
});

Note: handle() no longer auto-detects request body; pass raw input explicitly.

Implementation Patterns

Client Workflows (Updated for 3.0.0)

Authentication Use native PHP stream context for headers:

$client->setOptions([
    'stream_context' => stream_context_create([
        'http' => [
            'header' => "Authorization: Bearer $token\r\n"
        ]
    ])
]);

Error Handling (Enhanced)

try {
    $response = $client->call('method', [$param]);
} catch (\Laminas\XmlRpc\Client\FaultException $e) {
    log_error(sprintf(
        'XML-RPC Fault [%d]: %s',
        $e->getFaultCode(),
        $e->getFaultString()
    ));
}

Batch Requests (Unchanged)

$client->setOptions(['batch' => true]);
$client->callMultiple([
    ['method' => 'method1', 'params' => [$p1]],
    ['method' => 'method2', 'params' => [$p2]],
]);

Server Patterns (Updated for 3.0.0)

Laravel Integration (Simplified)

// app/Http/Controllers/XmlRpcController.php
public function handle() {
    $server = new Server();
    $server->register('laravel.method', fn($data) => app(MyService::class)->handle($data));
    return $server->handle(file_get_contents('php://input'));
}

Dependency Injection (Improved) Use closures with fn() syntax or bound services:

$server->register('user.create', fn() => app(UserService::class)->createFromRpc());

Validation (Unchanged)

$server->register('secure.method', function ($data) {
    $validator = Validator::make($data, ['email' => 'required|email']);
    if ($validator->fails()) {
        throw new \Laminas\XmlRpc\Server\FaultException(-32600, $validator->errors());
    }
    // ...
});

Advanced Use Cases (Updated for 3.0.0)

Custom Types (Enhanced) Native types (e.g., DateTime, bool) are now automatically handled. For custom types:

$server->registerType('app.date', new class implements \Laminas\XmlRpc\Server\TypeInterface {
    public function serialize($value) { /* ... */ }
    public function unserialize($value) { /* ... */ }
});

Logging (Native PHP) Use stream_filter_append for request/response logging:

stream_filter_append($client->getStream(), 'log', STREAM_FILTER_READ);

Gotchas and Tips

Pitfalls (Updated for 3.0.0)

PHP 8.1+ Requirement
- Fix: Upgrade PHP if using older versions (e.g., 7.4). Test with PHP 8.1+.
- Note: Some legacy XML-RPC servers may not support newer PHP features.

Removed laminas-http Dependency

Impact: Custom HTTP clients (e.g., with proxies) must now use native PHP streams.

Fix: Update middleware to use stream_context_create():

$client->setOptions([
    'stream_context' => stream_context_create([
        'http' => [
            'proxy' => 'tcp://proxy.example.com:8080',
        ]
    ])
]);

Strict Type Handling
- Issue: Native PHP types (DateTime, bool) are now strictly serialized. Custom objects must implement TypeInterface.
- Fix: Use json_encode()/json_decode() for complex objects or register a custom type.
Fault Codes (Updated)
- New Standard: Follow RFC 4889 strictly. Common codes:
  - -32600: Invalid request
  - -32500: Unauthorized
  - -32700: Server error

Debugging (Updated for 3.0.0)

Enable Verbose Output (Native)
```
$client->setOptions(['verbose' => true]);
```
- Output: Raw XML requests/responses logged to stderr (check Laravel logs).

Stream Debugging

$client->setOptions([
    'stream_context' => stream_context_create([
        'http' => [
            'debug' => true,
        ]
    ])
]);

Configuration Quirks (Updated for 3.0.0)

Server Input Handling

Breaking Change: handle() no longer auto-parses $_POST or $_GET. Always pass raw input:

$server->handle(file_get_contents('php://input')); // Laravel
$server->handle($request->getContent()); // Symfony-like

Native Type Support
- Automatic Handling: bool, int, double, string, DateTime, and arrays are now auto-converted.
- Custom Objects: Must implement TypeInterface (no longer auto-serialized).
Batch Request Limits
- Default: 10 requests per batch (configurable via setOptions(['batch_limit' => 20])).

Extension Points (Updated for 3.0.0)

Middleware (Native PHP) Decorate the server with closures:

$server = new Server();
$server = function ($server) {
    return function ($method, $params) use ($server) {
        if (!$this->isAuthenticated()) {
            throw new \Laminas\XmlRpc\Server\FaultException(-32500, 'Unauthorized');
        }
        return $server($method, $params);
    };
}($server);

Event Listeners (Laravel) Use Laravel’s events to hook into RPC calls:
```
event(new \Laminas\XmlRpc\Event\RpcCalled($method, $params));
```
- Note: Requires custom event classes (not bundled in 3.0.0).

Custom Stream Handlers Extend functionality with PHP stream filters:

stream_filter_register('xmlrpc_compress', \MyCompressionFilter::class);
$client->setOptions(['stream_filters' => ['xmlrpc_compress']]);

Laminas Xmlrpc Laravel Package