Власні API методи

Будь-який клас застосунку стає API-сервісом, якщо реалізує інтерфейс Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService. Інтерфейс не нав'язує логіки — він лише позначає клас тегом ufo.rpc.service, за яким бандл збирає карту методів під час компіляції контейнера.

Кожен публічний нестатичний метод такого класу (крім конструктора) стає JSON-RPC методом з назвою <назва класу>.<метод>.

<?php

namespace App\Api;

use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
use Ufo\RpcObject\RPC;

#[RPC\Info('Messenger')]
class MessengerApi implements IRpcService
{
    public function __construct(private Mailer $mailer) {}

    /**
     * A method for sending an email message
     * @param string $email The email address
     * @param string $text Message body
     * @param string $subject Optional message subject parameter
     */
    public function sendEmail(string $email, string $text, string $subject = 'Message without subject'): bool
    {
        return $this->mailer->send($email, $subject, $text);
    }
}

У прикладі з'явиться метод Messenger.sendEmail:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "Messenger.sendEmail",
    "params": {
        "email": "user@example.com",
        "text": "Hello!"
    }
}

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": true
}

Параметри можна передавати й позиційно: "params": ["user@example.com", "Hello!"].

Іменування

Без атрибута назвою класу в API буде коротке ім'я класу (MessengerApi.sendEmail). Атрибут #[RPC\Info] задає псевдонім (Messenger.sendEmail), символ-роздільник і версію API.

Опис методів і параметрів

Документація будується з усього, що відомо про метод: назв, нативних типів, значень за замовчуванням і докблоків. Опис методу й параметрів береться з PHPDoc, а точний тип — з @param / @return, якщо нативного типу недостатньо:

/**
 * Creates an order
 * @param OrderItemDto[] $items
 * @return array<string, OrderItemDto>
 */
public function create(array $items, ?string $comment = null): array

Параметр з null за замовчуванням або зі значенням за замовчуванням необов'язковий. Детально про типи — на сторінці Параметри методів, про результат — Формат відповіді.

Назву (summary) і опис методу в документації можна перекласти, не змінюючи код — див. Документація API.

Застарілі методи

Метод з @deprecated у докблоці або з атрибутом #[\Deprecated] позначається в OpenRPC як "deprecated": true, але продовжує працювати.

/**
 * @deprecated use Orders.create
 */
public function createOrder(array $items): array

Приховати метод з API

Публічний метод, який не має бути методом API, позначте #[RPC\IgnoreApi]: його немає ні в карті методів, ні в документації.

#[RPC\IgnoreApi]
public function rebuildIndex(): void

Сервіси в аргументах методу

Окрім ін'єкції через конструктор, сервіс можна отримати прямо в аргументі методу через #[Autowire]. Такий аргумент не є RPC-параметром: його немає в документації, і клієнт його не передає.

use Symfony\Component\DependencyInjection\Attribute\Autowire;

public function report(int $id, #[Autowire(service: 'app.report_builder')] ReportBuilder $builder): array

RPC атрибути

Усі атрибути — з пакета ufo-tech/rpc-objects (простір імен Ufo\RpcObject\RPC).