Passage — легкий API Proxy Gateway для Laravel

Passage — це Laravel-пакет від Morcen Chavez, який дозволяє вашому застосунку стати посередником між клієнтом і зовнішнім API. Ви зберігаєте повний контроль над автентифікацією, заголовками та трансформацією даних, використовуючи звичну систему роутингу та middleware Laravel.

Типовий сценарій використання: вам потрібно звернутися до стороннього API з фронтенду, але ви не хочете розкривати API-ключі, прагнете нормалізувати дані або централізувати логіку валідації. Замість розробки власного проксі-сервісу з нуля, Passage пропонує структурований підхід із мінімумом шаблонного коду.

# Визначення роутів

Роути реєструються через фасад Passage разом із вашими звичайними маршрутами. Параметр {path?} перехоплює будь-який підшлях і передає його на upstream-сервіс:

use Morcen\Passage\Facades\Passage;
 
Passage::get('github/{path?}', GithubPassageController::class);
Passage::post('stripe/{path?}', StripePassageController::class);
Passage::any('payments/{path?}', PaymentsPassageController::class);

Підтримуються стандартні методи HTTP: get, post, put, patch, delete та any.

# Створення обробника (Handler)

Кожен роут веде до класу-обробника, який керує пересиланням запитів та поверненням відповідей. Створити його можна командою:

php artisan passage:controller GithubPassageController

Обробники наслідують PassageHandler і можуть реалізовувати три методи:

• getOptions() — встановлює базовий URI та налаштування Guzzle (тайм-аути, заголовки тощо).
• getRequest() — трансформує запит або додає облікові дані перед відправленням.
• getResponse() — змінює відповідь від API перед тим, як вона потрапить до клієнта.

Мінімальний обробник виглядає так:

class GithubPassageController extends PassageHandler
{
    public function getOptions(): array
    {
        return [
            'base_uri' => 'https://api.github.com/',
        ];
    }
 
    public function getRequest(Request $request): Request
    {
        return $this->withBearerToken($request, config('services.github.token'));
    }
}

Зверніть увагу на слеш у кінці base_uri — він необхідний для коректної переадресації шляхів.

# Вбудовані інструменти автентифікації

Passage містить три трейти для роботи з автентифікацією в getRequest():

• Bearer token — $this->withBearerToken($request, $token)
• API key (у заголовку або параметрах запиту) — $this->withApiKey($request, $key) або $this->withApiKeyQuery($request, $key, 'api_key')
• HMAC signing — $this->withHmacSignature($request, $secret)

Також можна згенерувати контролер із уже готовою логікою авторизації:

php artisan passage:controller StripePassageController --with-auth=apikey
php artisan passage:controller PaymentsPassageController --with-auth=hmac

# Безпека

Passage автоматично видаляє конфіденційні заголовки клієнта (cookies, authorization, proxy-authorization) перед пересиланням запиту. Якщо потрібно пропустити певні заголовки, реалізуйте інтерфейс AcceptsClientHeaders і визначте метод allowedClientHeaders() для створення білого списку:

class GithubPassageController extends PassageHandler implements AcceptsClientHeaders
{
    public function allowedClientHeaders(): array
    {
        return ['authorization'];
    }
}

Ви також можете обмежити список хостів для проксіювання, встановивши PASSAGE_ENFORCE_ALLOWED_HOSTS=true у файлі оточення.

# Валідація та стійкість

Обробники можуть перевіряти вхідні запити ще до їхнього відправлення на зовнішній сервіс через інтерфейс ValidatesInboundRequest. Опишіть правила у методі rules(), і в разі помилки Passage поверне статус 422 без запиту до API.

use Morcen\Passage\Contracts\ValidatesInboundRequest;
 
class StripePassageController extends PassageHandler implements ValidatesInboundRequest
{
    public function getOptions(): array
    {
        return ['base_uri' => 'https://api.stripe.com/'];
    }
 
    public function rules(): array
    {
        return [
            'amount'   => ['required', 'integer', 'min:1'],
            'currency' => ['required', 'string', 'size:3'],
        ];
    }
}

Для підвищення надійності метод withRetry() додає автоматичні повторні спроби з експоненціальною затримкою:

class PaymentsPassageController extends PassageHandler
{
    public function getOptions(): array
    {
        return array_merge(
            ['base_uri' => 'https://payments.example.com/'],
            $this->withRetry(3, 200), // 3 спроби, початкова затримка 200мс
        );
    }
}

Passage також підтримує кешування для GET/HEAD роутів та потокову передачу (streaming) великих даних.

# Корисні команди Artisan

• php artisan passage:list — список усіх зареєстрованих проксі-роутів.
• php artisan passage:health — перевірка зв'язку з upstream-сервісами.

Вимкнути проксіювання можна глобально в .env за допомогою PASSAGE_ENABLED=false.

Passage — це елегантне рішення для створення легкого API-проксі всередині Laravel без потреби розгортати складні корпоративні шлюзи. Дізнатися більше та переглянути вихідний код можна на GitHub.