- How do I install and set up swagger-php in a Laravel project?
- Install it with composer require zircote/swagger-php; it requires PHP 8.2 or newer. There is no Laravel service provider, so you either run the bundled openapi CLI binary or invoke the Generator class programmatically from an artisan command or service provider. You then annotate your controllers and DTOs with OpenAPI attributes and point the generator at your source directories.
- Does swagger-php work with Laravel 10 and 11?
- Yes. swagger-php is framework-agnostic and works in any PHP 8.2 application, including modern Laravel versions. Its attribute-based approach fits Laravel's existing attribute usage such as route attributes, and it resolves advanced type hints used by DTOs and form requests. You just need to wire up generation yourself since there is no native Laravel integration.
- What PHP version does swagger-php require?
- swagger-php requires at least PHP 8.2. That version floor exists because the library relies on modern attribute support and advanced type resolution. If you are on an older PHP release, you would need to upgrade before adopting the package.
- Can swagger-php build schemas from DTOs and PHP type hints?
- Yes. The library uses symfony/type-info to resolve advanced type hints such as generics and unions, which reduces manual schema definitions. You can annotate request and response objects with OA Property attributes to describe validation rules and payload shapes, and it also extracts information from existing phpdoc comments.
- How do I switch between OpenAPI 3.0, 3.1, and 3.2 output?
- Generated specs default to OpenAPI 3.0.0. Use the --version command line option to target 3.1.0 or 3.2.0, or call Generator::setVersion() when generating programmatically. This lets you keep one codebase while emitting specs for different consumer requirements.
- Does swagger-php support shared tags and security across a base controller?
- Yes. Since version 6.11.0, Specification::buildPathItemHierarchy() resolves which PathItems govern a class by walking its ancestors, including controller prefixes, tags, and security. That means Tag and SecurityScheme metadata declared once on a base controller is inherited by child controllers instead of being duplicated per class. This maps cleanly onto Laravel's base-controller inheritance pattern.
- Are doctrine annotations still supported in swagger-php?
- They still work but are deprecated as of 6.11.0, and parsing a docblock annotation triggers a runtime deprecation notice once per Generator run. Support remains unchanged through v7 and is removed in 8.0. Since version 4.8 the doctrine/annotations library is optional and no longer installed by default, so attributes are the recommended path.
- How do I run swagger-php from the CLI or in a CI pipeline?
- Install the package locally or globally and use the openapi executable, or call the Generator programmatically from a build script. Because generation is decoupled from any framework, you can regenerate documentation on every push or as part of your deployment pipeline. The CLI also provides contextual error hints to help debug large codebases.
- What breaking changes are in swagger-php v7 and how should I prepare?
- Classic code is removed in v7, including Generator::UNDEFINED and Generator::isDefault(), which classic processors and hand-built annotation objects depend on. Custom processors and augmenters written against the old API reach end-of-life in that release. The project follows a written upgrade contract in which each deprecation marker names the version that removes it, so you can audit the src markers to plan your migration mechanically.
- How is swagger-php different from darkaonline/l5-swagger?
- swagger-php is the underlying OpenAPI generation library, while l5-swagger is a Laravel wrapper that adds a service provider, config, and routes for serving Swagger UI. swagger-php has no native Laravel integration, so you handle setup and doc serving yourself but gain flexibility for CLI usage, CI integration, and generating specs for multiple API versions from one codebase.