README

Simple clientSDK builder for any json-RPC servers

See the Documentations

New in version 5.0

🔌 Extensible asynchronous transports

• Async procedures use Ufo\Component\TransportContracts\AsyncTransportFactory from ufo-tech/component-transport-contracts to select a transport resolver by DSN scheme. Transport contracts, resolvers, and their configuration are maintained in that package.
• Multiple named async transports are supported. Select one with the transportName constructor argument; generated configuration uses a separate {transportName_secret} placeholder for each transport.
• SDK generation detects async transports by the RpcTransport::ASYNC_PREFIX prefix.

⚙️ Request configuration

• Added fluent withHeaders() to merge additional HTTP headers into synchronous procedure requests.
• Updated ufo-tech/rpc-objects to ^3.7.

🔄 Breaking changes

• Async procedure constructors now require Ufo\Component\TransportContracts\AsyncTransportFactory instead of Symfony's TransportFactoryInterface. The new transportName argument precedes requestId; update positional arguments accordingly.
• SdkConfigs::getApiEndpoint() now requires an explicit transport name instead of an optional boolean. Use RpcTransport::SYNC_PREFIX and RpcTransport::ASYNC_PREFIX instead of the removed SdkConfigs::SYNC and SdkConfigs::ASYNC constants.
• Transport classes have moved from Ufo\RpcSdk\Procedures\AsyncTransportResolvers to Ufo\Component\TransportContracts; RPCAsyncTransportFactory is now AsyncTransportFactory. Update custom resolver imports and catch Ufo\Component\TransportContracts\Exceptions\TransportNotFoundException instead of the SDK exception.
• The legacy async configuration key is no longer supported. Regenerate your SDK and update transport configuration and secret placeholders when upgrading.

New in version 4.4

⚙️ Automatic runtime initialization

• The DTO Transformer is initialized automatically before preparing an RPC call if it has not been initialized yet.
• Synchronous procedures use built-in response handlers for enums, collections, union types, and DTOs when the handler list is empty.
• A non-empty list of custom response handlers is preserved.

New in version 4.3

🔧 SDK generation fixes

• Fixed resolution of $ref in array items for non-object components, including enums.
• Added component resolution inside oneOf, including nested schema.oneOf definitions.
• Fixed generated @param documentation for union types such as null|string.

Regenerate your SDK to apply these generation fixes.

⚙️ Generator startup

• The CLI generator initializes the DTO Transformer automatically.
• Composer autoload detection supports both a standalone checkout and installation as a dependency.
• An empty API vendor name defaults to SDK.

📦 Dependencies and packaging

• Updated ufo-tech/dto-transformer from ^2 to ^3.0.4 and adapted enum conversion to its new API.
• Updated ufo-tech/rpc-objects from ^3.4 to ^3.6.
• Excluded tests and development configuration from exported package archives.
• Removed the Docker configuration's dependency on the external tm network.

If your application uses the DTO Transformer API directly, check its compatibility with version 3 when upgrading.

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

🚫 Prohibited

📎 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