Параметри методів

Параметри RPC-методу — це параметри PHP-методу. Бандл бере їхні назви, типи й значення за замовчуванням із сигнатури та PHPDoc, будує з них JSON Schema для документації і перед викликом перетворює вхідні значення на потрібні типи.

Скалярні типи

string, int, float, bool, array, mixed та їхні nullable/union-варіанти передаються як є. Параметр зі значенням за замовчуванням (зокрема null) необов'язковий.

public function search(string $query, int $limit = 20, ?string $sort = null): array

Неправильний тип чи відсутній обов'язковий параметр повертає помилку -32602 з переліком проблем по кожному параметру — див. Обробка помилок.

Точні типи з PHPDoc

Якщо нативного типу недостатньо (array), точний тип береться з @param. Імена класів розв'язуються через use-імпорти класу процедури.

/**
 * @param OrderItemDto[] $items
 * @param array<string, int|string> $meta
 */
public function save(array $items, array $meta = []): bool

DTO

Параметр, тип якого — клас, автоматично створюється з JSON-об'єкта:

final class CreateOrderDto
{
    public function __construct(
        public string $sku,
        public int $qty = 1,
    ) {}
}

public function create(CreateOrderDto $order): int

{"jsonrpc": "2.0", "id": 1, "method": "Order.create", "params": {"order": {"sku": "A-1", "qty": 2}}}

• Колекція DTO описується в PHPDoc (@param CreateOrderDto[] $orders) — кожен елемент масиву стає об'єктом.
• Для union-типів (FooDto|BarDto) береться перший DTO, який вдалося створити.
• Значення, з якого не вдається створити DTO, повертає помилку валідації, а не сирий масив.
• У схемі DTO властивості зі значенням за замовчуванням отримують default, а в required потрапляють лише властивості без нього.

Автоматична конвертація

Для параметрів з такими типами значення конвертується без додаткових атрибутів:

enum OrderStatus: string
{
    case NEW = 'new';
    case PAID = 'paid';
}

/**
 * @param OrderStatus[] $statuses
 */
public function find(OrderStatus $status, array $statuses = []): array

// {"method": "Order.status", "params": {"order": 42}} — Order завантажиться за id
public function status(Order $order): string

DoctrineEntityConverter реєструється лише тоді, коли ввімкнено DoctrineBundle.

У відповіді ці типи перетворюються назад на скаляри: enum → значення, дата → рядок (Y-m-d H:i:s), UUID → рядок, сутність → ідентифікатор (або __toString() для Stringable).

#[RPC\Param]

Атрибут явно задає, які скалярні типи приймає параметр і яким конвертором перетворювати значення. Потрібен, коли тип не підтримується автоматично або треба інший конвертор.

public function __construct(
    int $type,                 // бітова маска Param::STRING | Param::INT | Param::FLOAT | Param::NULL
    bool $collection = false,  // значення — масив, конвертується кожен елемент
    array $context = [],       // наприклад, [Param::C_CONVERTOR => MyConvertor::class]
)

use Ufo\RpcObject\RPC;

public function charge(
    #[RPC\Param(RPC\Param::STRING, context: [RPC\Param::C_CONVERTOR => MoneyConvertor::class])]
    Money $amount,
): bool

Готові маски: Param::NUMBER, Param::NULLABLE_STRING, Param::NULLABLE_NUMBER, Param::MIXED.

Власний конвертор

Реалізуйте Ufo\JsonRpcBundle\ParamConvertors\IParamConvertor. З autoconfigure клас автоматично отримує тег rpc.param_convertor, і параметри підтримуваного типу конвертуються без атрибута.

use Ufo\JsonRpcBundle\ParamConvertors\IParamConvertor;
use Ufo\RpcObject\RPC\Param;

final class MoneyConvertor implements IParamConvertor
{
    public function toScalar(object $object, array $context = [], ?callable $callback = null): array|string|int|float|null
    {
        return $object->amount;
    }

    public function toObject(int|string|float|null $value, array $context = [], ?callable $callback = null): ?object
    {
        return new Money((int) $value);
    }

    public function supported(string $classFQCN): bool
    {
        return $classFQCN === Money::class;
    }

    public function getParamAttr(string $classFQCN): Param
    {
        return new Param(Param::INT, context: [Param::C_CONVERTOR => self::class]);
    }
}

Спеціальні параметри $rpc

Об'єкт $rpc у params не передається в метод, а керує виконанням запиту:

{"jsonrpc": "2.0", "id": 1, "method": "Orders.get", "params": {"id": 10, "$rpc": {"ignoreCache": true}}}