A modern API reference for Symfony with Scalar

Aleksander Frolov — Sun, 30 Aug 2026 07:21:55 +0000

Symfony had no official integration with Scalar — the open-source API Reference renderer that makes Swagger UI look its age. Laravel got one back in 2024: scalar/laravel has 231,862 installs on Packagist. Symfony got nothing — not a single package on Packagist, and zero in Scalar's official list of 30+ integrations (Express, FastAPI, NestJS, Spring Boot, Laravel — but no Symfony).

I work with Symfony daily, so I closed the gap: the alex-frolov/scalar-symfony bundle.

What the bundle does

It renders Scalar API Reference from any OpenAPI document. One route, zero coupling to how the spec was generated: a static openapi.yaml, swagger-php, NelmioApiDocBundle, or API Platform all work — because the bundle never parses or proxies the document; the page loads it client-side.

Install and configure in two files:

composer require alex-frolov/scalar-symfony

# config/packages/scalar_symfony.yaml
scalar_symfony:
    url: '/openapi.yaml'          # your OpenAPI document (required)
    path: '/scalar'               # route (default: /scalar)
    cdn: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.65.1'

    configuration:
        theme: 'default'
        metaData:
            title: 'API Reference'

    scalar_options:               # any Scalar option, passed through as is
        darkMode: false
        layout: 'modern'

    access_control:
        mode: public              # or 'attribute' + security attribute

That's it — the reference lives at /scalar. The config is serialized XSS-safely (JSON_HEX_TAG/APOS/AMP/QUOT), so even a malicious title can't break out of the <script> context.

Documentation that works as a client

The bundle serves the API reference of the Tender Platform (Symfony 8.1, highload auction API, OpenAPI 3.1 spec). Through Test Request I'm hitting POST /auth/register, filling the JSON body, and pressing Send:

HTTP/1.1 201 Created  (794 ms)
{
  "company_id": "0c7702c6-9667-4ea3-8caa-df4990522ee7",
  "user_id": "86a40d70-5ef9-44fd-882b-8f703e10df7e",
  "verification_status": "pending"
}

Real UUIDs, real latency, real backend: the docs page doubles as the tool you test the API with. That's what Swagger UI never delivered.

Quality bar

The first commit was small; the release survived a review against Symfony's official bundle best practices and external hardening passes.

Functional tests: 16 tests / 46 assertions — routes 200/403/404, config validation errors, XSS-escaping, real SecurityBundle integration;
Static analysis: PHPStan level max, 0 errors;
CI matrix: PHP 8.2/8.3/8.5 × Symfony 6.4/7.2/7.4/8.0, including --prefer-lowest;
Config hardening: attribute mode without Symfony Security fails cache:clear at compile time with a clear message;
Security docs: SRI (SHA-384), CSP/nonce guidance, self-hosting recipe.

The CI war story: a token that didn't fit

Half the GitHub Actions jobs failed with Your github oauth token for github.com contains invalid characters. setup-php writes the Actions GITHUB_TOKEN (prefixed ghs_) into composer's global auth.json, and Composer 2.8 only accepts ghp_/gho_/github_pat_. The fix: delete auth.json on the runner before composer validate --no-check-publish, keep the token for dependency installation.

Making it official

I opened a proposal in the Scalar organization — Discussion #9920: "Proposal: official Symfony integration (scalar/symfony)" — https://github.com/scalar/scalar/discussions/9920

If you're a Symfony developer who wants modern API docs the way Laravel has them, a reaction on the discussion helps signal maintainer attention.

Start tomorrow: composer require alex-frolov/scalar-symfony → point scalar_symfony.url at any OpenAPI document → import routes and open /scalar.

Aleksander Frolov — Senior/Staff PHP engineer, Symfony/Laravel, highload. frolov.guru · GitHub

Idempotency and Retry in a Payment Core: Operations That Can't Be Duplicated and Can't Be Forgotten

Aleksander Frolov — Sun, 16 Aug 2026 09:16:29 +0000

Idempotency and Retry in a Payment Core: Operations That Can't Be Duplicated and Can't Be Forgotten

Build operations that can't be duplicated and can't be forgotten — that's the contract for a payment core.

On the core I built for ROSSTRAFFY (20,000+ successful transactions/day, 99.99% uptime), the most dangerous failure class wasn't crashes. It was retries.

The network doesn't guarantee delivery. A request can be processed, but the response lost — the client retries, and the server can't tell "didn't arrive" from "processed, but response lost". If a retry means "run the request again", you get double charges. If it means "resume the same operation", you get exactly one outcome per key.

The contract: every payment happens exactly once — not 0, not 2 times. Zero means a lost payment and a missed discount window; two means double charges, refunds, disputes.

The approach: the payment core as a state machine

A payment operation is not a "request" that either ran or didn't. It's a path with state: created, processing, completed, rejected, in reconciliation. Every transition must be idempotent — applying the same transition twice must not change the result.

Idempotency lives at three levels, and skipping any one lets duplicates through:

API level — one idempotency key per business operation, generated once, surviving all retries.
Handler level — the operation is a state machine; every transition checks the current state before acting.
Storage level — unique constraints as the last line of defense.

What we built

Operation = state machine: every transition idempotent.
One idempotency key per business operation, generated once, surviving all retries.
Idempotency at three levels: API, handler, storage (unique constraints as the last line of defense).
Payment = two operations: hold (block funds) → capture (charge after the external system confirms), each with its own key and retry rules.
Sync leg: bounded retries, exponential backoff, timeouts, jitter, dead-letter queue.
Async leg (ГИС ГМП): queue + workers, load balancing across 5+ acquirers (Strategy pattern), failover on degradation → 99.8% acceptance reliability.
Recurring payments stay on the same acquirer (confirmed token); switching only for new payments and emergencies.
Observability: counters + latency per stage in Grafana, alerts on anomalies. "More retries, fewer successful operations" = retry is masking the problem, not fixing it.
Reconciliations as the second safety net (ClickHouse: daily financial reports in 3–5 minutes instead of hours).

Validation and results

We validated with A/B tests behind feature flags on real traffic. Effects were fractions of a percent of conversion — only real payment statistics could see them; synthetic tests couldn't.

Metric	Result
Erroneous and fraudulent operations	−25%
Payment conversion	+~10%
Median transaction processing time	−15%

Takeaways

Idempotency isn't a nice-to-have in payments. It's the contract that makes retries safe at scale — and what turns "the user paid twice" into "the user paid once, and we can prove it".

The full article with diagrams and code (EN): https://frolov.guru/en/writing/idempotency-retry/

About the author: Alexander Frolov — Senior/Staff Backend Engineer (PHP, highload) and Team Lead, 18+ years: payment cores, multi-tenant platforms at federal scale. Articles on highload PHP and architecture: frolov.guru. If you're fighting timeouts, duplicates or lost payments — that's an idempotency problem, and it's fixable. DM or aleksander@frolov.guru.

DEV Community: Aleksander Frolov

A modern API reference for Symfony with Scalar

What the bundle does

Documentation that works as a client

Quality bar

The CI war story: a token that didn't fit

Making it official

Idempotency and Retry in a Payment Core: Operations That Can't Be Duplicated and Can't Be Forgotten

Idempotency and Retry in a Payment Core: Operations That Can't Be Duplicated and Can't Be Forgotten

The approach: the payment core as a state machine

What we built

Validation and results

Takeaways