Symfony Laravel Package

Getting Started

• Install with composer require scalar/symfony:^0.2.0. This is a Symfony bundle, not a Laravel package; Laravel applications should use Scalar’s standalone HTML/JS integration or a Laravel-specific wrapper rather than expecting a service provider or publishable Laravel config.
• Confirm runtime compatibility first: PHP 8.2+ and Symfony 6.4, 7.2+, or 8.x, subject to Symfony’s PHP requirements.
• Register the bundle as described in the README, import the bundle routes, and point the configuration at an existing OpenAPI document.
• First useful integration: expose a /api/docs route that renders an existing OpenAPI JSON/YAML URL, so teams get interactive API reference pages without changing the API itself.
• For migration from alex-frolov/scalar-symfony, read the migration guide before upgrading. The package is now scalar/symfony and the namespace is Scalar\Symfony; bundle, route, and configuration names are preserved.

Implementation Patterns

• Use configuration for new projects. It accepts serializable Scalar options and is the intended replacement for the deprecated scalar_options compatibility alias.
• Support multiple documentation sources in one application:
  • Remote OpenAPI URLs for externally hosted or separately deployed specs.
  • Inline JSON/YAML for small, self-contained definitions.
  • Local files for specs committed alongside the application.
  • Multiple OpenAPI documents for versioned or domain-specific APIs.
• Prefer local files when specs are part of the deploy artifact; prefer URLs when specs are owned by another service or updated independently.
• Configure the default Symfony theme and light/dark mode through Scalar options. Keep theme selection in configuration rather than hard-coding it in templates.
• Pin an explicit Scalar CDN URL in production if deterministic builds or CSP allowlists matter. The default client URL is now unversioned and receives updates independently of Composer releases; existing explicit CDN settings are preserved.
• During migration, keep existing bundle, route, and configuration names where possible, then update the Composer package and namespace references. Replace scalar_options usage with configuration incrementally.
• Use separate routes or route parameters when exposing multiple API versions, so each reference page has a clear, stable URL.

Gotchas and Tips

• This package is Symfony-specific. Laravel developers can reuse the configuration concepts and Scalar client behavior, but cannot install this bundle directly into a Laravel app without adaptation.
• scalar_options remains as a deprecated compatibility alias. New code should use configuration; plan to remove scalar_options usage before a future major release.
• The unversioned default CDN URL can change independently of Composer. Pin a versioned CDN URL when reproducibility, offline behavior, or strict CSP is required.
• The package-name and namespace changes are the main migration risk. Search for AlexFrolov\ScalarSymfony or equivalent old namespace references and update them to Scalar\Symfony.
• Configuration and route names are preserved for migration convenience, but still verify bundle registration and route imports after upgrading.
• Validate OpenAPI documents before wiring them into the renderer. Invalid or unreachable specs usually surface as blank or broken reference pages rather than clear configuration errors.
• For remote spec URLs, check CORS and Content-Security-Policy settings. A working local file does not guarantee a remote URL will load in the browser.
• Clear the Symfony cache after changing bundle configuration or routes. Production deployments should be tested with the production cache and asset settings, not only in dev.
• If using local files on Windows, verify path handling carefully. The release notes mention Windows compatibility checks, but filesystem paths and permissions remain a common source of rendering failures.
• Use the project’s regression, browser, fresh Flex installation, and production installation checks as a template for your own deployment validation.