Finam SDK (Laravel)

Неофициальный SDK для работы с Finam Trade API (REST) с удобной интеграцией в Laravel 8+.

Документация API: https://tradeapi.finam.ru/docs/about/

---

Содержание

• Зачем этот пакет

• Возможности

• Требования

• Установка

  • Из Packagist

• Настройка

• Быстрый старт

• Публикация конфига

• Тесты и статический анализ

• Версионирование

• Безопасность

• Contributing

• License

---

Зачем этот пакет

Цель — дать удобный, типизированный, расширяемый SDK для взаимодействия с Finam Trade API из PHP/Laravel проектов.

Фокус:

• простой старт;
• аккуратный транспортный слой (REST);
• нормальные исключения и предсказуемое поведение;
• удобная интеграция в контейнер Laravel.

Возможности

На текущем этапе пакет предоставляет базовую инфраструктуру:

• автоподключение Service Provider (Laravel package auto-discovery);
• конфигурация через config/finam.php и переменные окружения;
• базовый REST-клиент на Guzzle с таймаутами и простыми ретраями;
• тестовый стенд (Orchestra Testbench) для package-level тестов.

Важно: это SDK. Бизнес-логика торговли, риск-менеджмент и «правильные решения» не входят в пакет.

Требования

• PHP: >= 8.0
• Laravel: >= 8.0
• ext-json

Установка

Из Packagist

composer require masyasmv/finam-sdk-laravel

После этого:

composer update

Настройка

Пакет читает настройки из config('finam.*').

Рекомендуемый минимум в .env:

FINAM_BASE_URL=https://trade-api.finam.ru
FINAM_TOKEN=your_token_here

FINAM_HTTP_TIMEOUT=10
FINAM_HTTP_CONNECT_TIMEOUT=5
FINAM_HTTP_RETRIES=0
FINAM_HTTP_RETRY_DELAY_MS=200
FINAM_HTTP_USER_AGENT=finam-sdk-laravel

Примечание: конкретный формат авторизации (например, Bearer <token>) и точный base url должны соответствовать требованиям Finam Trade API. Если формат отличается — правится в транспортном слое клиента.

Аутентификация

SDK поддерживает два драйвера авторизации, управляется через FINAM_AUTH_DRIVER:

• token — статический токен (по умолчанию). Использует FINAM_TOKEN для формирования заголовка авторизации;
• oauth — получение access_token через Auth Service (client_credentials), кэширование access_token через кеш Laravel для уменьшения обращений к Auth API.

Пример конфигурации для OAuth-драйвера в .env:

FINAM_AUTH_DRIVER=oauth

FINAM_AUTH_BASE_URL=https://trade-api.finam.ru
FINAM_AUTH_TOKEN_ENDPOINT=/auth/oauth2/v1/token
FINAM_AUTH_CLIENT_ID=your_client_id
FINAM_AUTH_CLIENT_SECRET=your_client_secret
FINAM_AUTH_GRANT_TYPE=client_credentials
FINAM_AUTH_SCOPE=""

FINAM_AUTH_CACHE_KEY=finam:auth:access_token
FINAM_AUTH_CACHE_TTL=300

Параметры cache_key и cache_ttl управляют кешированием access_token (Redis/array). Если требуется отключить кеш — установи TTL в 0.

Быстрый старт

Получить клиента из контейнера Laravel

use MasyaSmv\FinamSdk\Client\FinamClient;

$client = app(FinamClient::class);

// Пример GET
$response = $client->get('/some/endpoint', [
    'param' => 'value',
]);

// Пример POST
$response = $client->post('/some/endpoint', [
    'foo' => 'bar',
]);

$body = (string) $response->getBody();

Через алиас контейнера

$client = app('finam.sdk');

Публикация конфига

Если хочешь скопировать конфиг пакета в приложение:

php artisan vendor:publish --tag=finam-config

Файл появится как config/finam.php.

Тесты и статический анализ

Запуск тестов:

composer test

Запуск PHPStan:

composer analyse

Если ты используешь GitHub Actions, workflow CI обычно запускает и тесты, и статический анализ.

Версионирование

Пакет следует семантическому версионированию (SemVer):

• 0.x — активная разработка, API может меняться;
• 1.0.0 — стабилизация публичного API.

Безопасность

• Никогда не коммить токены/секреты в репозиторий.
• Храни токены только в .env / секретах CI.
• При логировании ошибок не выводи токен целиком.

Если ты нашёл уязвимость или утечку секретов — создай приватное уведомление (security advisory) или issue без секретов.

Contributing

PR приветствуются.

Рекомендации:

• добавляй тесты на новые сценарии;
• держи публичный API стабильным;
• избегай жёсткой привязки к конкретному приложению (SDK должен оставаться универсальным).

License

MIT. См. файл LICENSE.