json-rpc-client-sdk

Simple clientSDK builder for any json-RPC servers

See the Documentations

New in version 4.2

⚙️ Service parameters for UFO-json-rpc servers

Support for service-level RPC parameters has been added for servers implemented with UFO-json-rpc.

The SDK now allows request configuration via a fluent chain, without changing method signatures.

🔹 Basic call (as before)

$userService->list();

🔹 Cache control

$userService
    ->withoutCache()
    ->list();

🔹 Passing service metadata

$userService
    ->rayId('someRayId')
    ->list();

🔹 Async-specific parameters

For async procedures, additional execution control options are available:

$asyncUserService
    ->withCache()
    ->rayId('someRayId')
    ->timeout(30) // timeout in seconds
    ->callback('https://some.url/hook') // webhook callback
    ->list();

📌 Notes

• Service parameters are not passed as business method arguments.
• They are applied at the RPC context level and handled by the server.
• Works only with UFO-json-rpc compatible servers.
• The SDK remains type-safe — method signatures are unchanged.

New in version 4.1

🔍 Filtering methods during SDK generation

The SDK supports skipping RPC methods during generation.
This is done using the ignoredMethods option, which accepts a list of masks.

📌 Mask Rules

• * — any sequence of characters
• ! at the beginning — inversion (always generate)
• & at the beginning or after ! — indicates a sync request
• ~ at the beginning or after ! — indicates an async request
• Other characters are literals, meaning they represent themselves

✔️ Example masks

Mask	Description
AdminApi.*	ignores all methods of AdminApi class
Command.run	ignores only Command.run
#Command.run	ignores only Command.run in sync API
*.delete	ignores all delete() methods in any class
!~Comment.delete	always generates Comment.delete for async API even if *.delete blocks it
*.*Test	ignores all methods ending with Test

🚫 Prohibited

Mask	Reason
User.?pdate	? is not supported
~&User.update	~ and & in one mask is not supported
[A-Z]*.create	regex is not supported

📎 Usage Example

$configHolder = new ConfigsHolder(
    docReader: new HttpReader($apiUrl),
    projectRootDir: getcwd(),
    apiVendorAlias: $vendorName,
    ignoredMethods: [
        'AdminApi.*',
        'Command.run',
        '*.delete',
        '!Comment.delete',
        '*.*Test'
    ]
);

Masks allow you to easily remove service procedures, test methods, and unwanted CRUD operations from SDK generation.

Generate SDK

Run cli command php bin/make.php

$ php bin/make.php http://some.url/api
  > Enter API vendor name: some_vendor
  > Enter methods to ignore (comma-separated) or empty: *.delete,!Comment.delete

Or

$ php bin/make.php 

Use SDK

This example shows working with the generated SDK. IMPORTANT: You may have other procedure classes. The example only shows the concept of interaction.

<?php

use Symfony\Component\HttpClient\CurlHttpClient;
use Ufo\RpcSdk\Client\Shortener\UserProcedure;
use Ufo\RpcSdk\Client\Shortener\PingProcedure;
use Ufo\RpcSdk\Procedures\AbstractProcedure;

require_once __DIR__ . '/../vendor/autoload.php';

$headers = [
    'Ufo-RPC-Token'=>'some_security_token'
];

try {
    $pingService = new PingProcedure(
        headers: $headers
    );
    echo $pingService->ping(); // print "PONG"

// ...

    $userService = new UserProcedure(
        headers: $headers,
        requestId: uniqid(), 
        rpcVersion: AbstractProcedure::DEFAULT_RPC_VERSION,
        httpClient: new CurlHttpClient(),
        httpRequestOptions: []
    );
    $user = $userService->createUser(
        login: 'some_login', 
        password: 'some_password'
    );
    var_dump($user);
    // array(3) {
    //  ["id"]=> int(279232969)
    //  ["login"]=> string(3) "some_login"
    //  ["status"]=> int(0)
    
} catch (\Throwable $e) {
    echo $e->getMessage() . PHP_EOL;
}
// ...

Debug request and response

<?php

// ...
use Ufo\RpcSdk\Procedures\RequestResponseStack;
// ...

$fullStack = RequestResponseStack::getAll(); // get all previous requests and responses
$lastStack = RequestResponseStack::getLastStack(); // get last requests and responses

$lastRequest = RequestResponseStack::getLastRequest(); // get last request
$lastResponse = RequestResponseStack::getLastResponse(); // get last response
// ...

Profit