zircote/swagger-php

This is a PHP library that generates OpenAPI specification documents (versions 3.0, 3.1, and 3.2) by analyzing PHP source code. It supports defining API metadata using both modern PHP 8 attributes and legacy docblock annotations, automatically resolving complex type hints, class inheritance, and trait compositions. The system processes these definitions through a configurable pipeline to produce valid JSON or YAML output, with dedicated compilers ensuring strict adherence to specific OpenAPI version constraints.

15 changes.

The project underwent a major overhaul to migrate from legacy Swagger annotations to native PHP 8 attributes and align with the OpenAPI 3.1 specification. This involved rewriting the core processor pipeline, introducing a new Builder entry point, and upgrading the entire toolchain to PHP 8.2 with modern static analysis and CI practices.

13 changes.

The project introduced a comprehensive PHP 8 attribute system for OpenAPI annotations, replacing legacy docblock parsing with a pluggable factory architecture. This period also featured a major refactor of the type resolution engine to leverage Symfony TypeInfo for accurate handling of modern PHP types, supported by extensive new test fixtures and helper utilities.

23 changes.

The project introduced a comprehensive spec-based attribute system, replacing legacy annotation approaches with modern PHP attributes for defining OpenAPI schemas, operations, and security schemes. This architectural shift included a unified builder with multiple generation modes, a pluggable assembler pipeline, and version-specific compilers to support OpenAPI 3.0 through 3.2. Extensive utility classes and test coverage were added to support the new processing pipeline, inheritance resolution, and documentation generation.

This location introduces the PHP attribute classes that allow developers to declare security configurations directly in code. The \Requirement\ attribute defines which security schemes apply to an operation (supporting both single-scheme shorthand and multi-scheme AND logic via scopes), while the \Scheme\ attribute and its typed subtypes (\Http\, \ApiKey\, \OAuth2\, \OpenIdConnect\, \MutualTls\) define the specific security scheme details (such as type, location, flows, or bearer format) to be registered in the OpenAPI components.

src/Spec/Security · high confidence

The library now provides a complete set of PHP 8 attributes in the \OpenApi\\Attributes\ namespace (e.g., \Schema\, \Info\, \PathItem\, \Parameter\) that mirror the existing annotation classes. These attributes allow developers to define OpenAPI specifications using native PHP 8 syntax instead of docblock annotations. The implementation introduces an \Undefined\ sentinel class to distinguish between explicitly set null values and omitted properties, ensuring accurate serialization of the generated OpenAPI JSON/YAML.

src/Attributes · high confidence

The library now provides a comprehensive set of PHP annotations and attributes (e.g., \@OA\\OpenApi\, \@OA\\Schema\, \@OA\\Info\) to define API specifications directly in code. This change introduces the core \AbstractAnnotation\ base class and specific annotation classes for all OpenAPI 3.0 and 3.1 components, including schemas, parameters, responses, and security schemes. Users can now use these structured annotations to generate OpenAPI documents, replacing or augmenting previous methods, with support for nested structures, validation, and serialization to JSON/YAML.

src/Annotations · high confidence

The Builder component now supports three generation modes—Classic, Hybrid, and Spec—defined in the new Mode enum, allowing users to choose between traditional annotation processing and newer specification-based approaches. A new Result class encapsulates the output of these builds, providing a unified interface to access generated files, logs, warnings, and errors, as well as methods to export the result as JSON, YAML, or save it directly to a file. This change introduces a structured way to handle build outcomes and switch between different specification strategies within the Builder.

src/Builder · high confidence

The src/Loggers directory now includes two new logger classes: CollectingLogger, which wraps an existing logger to capture log entries for inspection, and DefaultLogger, which maps log levels to PHP's trigger\_error function while suppressing debug messages. These additions provide users with built-in utilities for testing (via collection) and default error handling behavior.

src/Loggers · high confidence

The \src/Spec\ directory now contains a comprehensive set of PHP attributes (e.g., \OpenApi\, \Info\, \Schema\, \Operation\, \Parameter\, \Response\, \MediaType\) that allow developers to define OpenAPI specifications directly in code. These classes provide a structured, type-safe way to declare API metadata, paths, operations, and components, replacing or supplementing previous annotation-based approaches with modern PHP attributes.

src/Spec · high confidence

The \src/Contracts\ directory now introduces four new interfaces that define the core abstractions for the OpenAPI specification pipeline. \AttributeInterface\ standardizes how spec attributes (like Schema or Operation) relate to each other via root detection, merging, and containment logic. \AttributeTranslatorInterface\ provides a contract for translating raw PHP reflection attributes into these spec objects, allowing stateful processing across structural levels. \CompilerInterface\ defines how a Specification is compiled into a versioned OpenAPI document and validated. Finally, \ResolverInterface\ allows the assembler to resolve fully qualified class names (FQCNs) that are referenced but not yet defined in the specification. These changes establish the foundational contracts for the spec assembly and compilation process.

src/Contracts · high confidence

The CSFixer tooling now includes new custom fixers: \SpecNamespaceAliasFixer\ enforces importing \OpenApi\\Spec\ via the \OA\ alias (rewriting individual imports and references), \ScopedLicenseFixer\ ensures all PHP files have an \@license Apache 2.0\ docblock before the namespace, and \ScopedDeclareStrictTypesFixer\ applies strict types declarations within scoped paths. These fixers share a \ScopedTrait\ that allows them to be restricted to specific directory paths, and an \AbstractFixer\ base class standardizes their interface.

tools/src/CSFixer · high confidence

A new \tools/docgen.php\ script has been added to automate the generation of documentation reference pages. This tool utilizes specific generators (for attributes, spec-attributes, processors, augmenters, examples, and extension points) to produce Markdown files in the \reference/\ and \guide/\ directories, allowing users to regenerate documentation content based on the codebase.

tools · high confidence

The library now supports a new generation mode (accessible via Builder::setMode) that uses a spec-attribute pipeline instead of the classic annotation processor pipeline. This introduces new core classes in src: Assembler (collects spec attributes from reflectors), Specification (a flat container for collected attributes), Resolver (resolves unresolved FQCNs to components), and HybridBridge (converts classic annotations into the new spec structure). The Builder class serves as the unified entry point, wrapping the Generator and allowing configuration of sources, version, compiler, and augmenters. The old Parser and Logger classes have been removed, and the Analysis class now provides structured definitions for classes, interfaces, traits, and enums.

src · high confidence

The \src/Utils\ directory now includes a suite of new utility classes that support the library's internal processing pipelines and source analysis. \Pipeline\ and \PipeInterface\ introduce a grouped, configurable execution model for processing steps, while \AttributeFactory\ handles the creation and resolution of spec attributes from PHP reflectors. Source resolution is now managed by \SourceScanner\ and \SourceFinder\, which locate and resolve file paths and reflectors. Additional utilities include \TokenScanner\ for PHP token-based code analysis, \DocBlockParser\ for parsing PHPDoc comments, \ClassReflector\ for safe class reflection, \JsonPointer\ for RFC 6901 compliant reference escaping, and \ServerVariableEnum\ for normalizing enum values to strings. A deprecated \TypeMapper\ wrapper is also present for backward compatibility.

src/Utils · high confidence

The Augmenter now automatically resolves PHP class hierarchies to generate correct OpenAPI definitions. For schemas, it expands parent classes, traits, and interfaces by merging their properties into the child schema or linking them via allOf references. For operations, it clones methods defined in abstract or non-annotated parent classes into concrete child controllers, ensuring that prefix, tag, and security compositions apply correctly to the inherited endpoints.

src/Augmenter/Inheritance · high confidence

The petstore-simple example file (pets.php) has been removed. This file previously demonstrated the use of Swagger v1-style annotations (e.g., @SWG\\Get), which are being phased out in favor of compatibility with the Swagger v2.0 specification.

Examples · high confidence

The \src/Analysers\ component has been restructured to support a pluggable annotation/attribute system. New interfaces \AnalyserInterface\ and \AnnotationFactoryInterface\ define the contract for analysers and their factories. Two concrete factory implementations, \AttributeAnnotationFactory\ and \DocBlockAnnotationFactory\, handle PHP 8 attributes and DocBlock annotations respectively, allowing the system to work with either or both depending on runtime support. The \ReflectionAnalyser\ now orchestrates these factories to build definitions from classes, methods, and properties. Additionally, \TokenScanner\ has been moved to the \OpenApi\\Utils\ namespace, with the old location kept only as a deprecated alias for backward compatibility.

src/Analysers · high confidence

The \bin/openapi\ entry point has been migrated to use the Symfony Console component, replacing the previous implementation. This change introduces a new command-line interface structure that resolves conflicts with built-in Symfony options (such as \--version\ and \--no-interaction\) to allow custom usage for OpenAPI specification versioning and pattern matching. Users will now interact with the tool through a standardized Symfony Console application, which may affect how arguments and options are parsed or displayed.

bin · high confidence

The Assembler now uses a pluggable \AttributeTranslatorInterface\ to process PHP attributes, allowing users to customize how attributes are reflected and translated into OpenAPI spec elements. A default implementation handles standard OpenAPI attributes, while a new \OptionalPropertyAttributeTranslator\ automatically injects an implicit \OA\\Property\ wrapper when a property or constructor parameter has an \OA\\Schema\ or \OA\\Encoding\ but lacks an explicit \OA\\Property\, simplifying the definition of schema properties and encodings.

src/Assembler · high confidence

The CLI entry point has been rewritten to use Symfony Console, introducing a new \--mode\ option that allows users to select between \classic\, \hybrid\, and \spec\ generation behaviors. This change also adds \--add-processor\ and \--remove-processor\ options for customizing the processing pipeline, alongside existing options for configuration, output formatting, and bootstrap files.

src/Console · high confidence

The Augmenter component has been refactored into a configurable pipeline of specialized processing steps (pipes) that transform the OpenAPI specification. This introduces new capabilities including automatic cleanup of unreferenced components with warnings for orphaned status-code-named responses, population of summary/description/deprecated fields from PHP docblocks, and generation of descriptions for enum-based properties. The pipeline also handles the resolution of PHP enums into schema values, infers component names from class reflectors, generates operation IDs, and resolves FQCN-based references to JSON pointers. Existing behaviors are preserved through these new dedicated stages, such as PathItems resolving prefixes and cloning metadata, and Types inferring schema details from PHP declarations.

src/Augmenter · high confidence

Added four new traits in the \src/Processors/Concerns\ namespace to support OpenAPI processing logic: \AnnotationTrait\ provides a method to recursively remove annotations from the analysis; \DocblockTrait\ delegates docblock parsing and extraction tasks to a centralized \DocBlockParser\ utility; \MergePropertiesTrait\ handles the inheritance and merging of schema properties from parent classes, interfaces, and traits; and \RefTrait\ offers helper methods for generating and validating JSON Reference keys. These traits consolidate common processor behaviors into reusable components.

src/Processors/Concerns · high confidence

The type resolution system in \src/Type\ has been restructured to introduce a new \TypeInfoTypeResolver\ that leverages Symfony TypeInfo and PHPStan's phpdoc-parser for more accurate reflection of PHP types, including support for composite types (oneOf, allOf, anyOf), array shapes, and generic types. This new resolver is backed by a \SchemaType\ value object that encapsulates resolved schema details (type, format, nullable, items, additionalProperties, etc.) and a shared \TypeResolver\ core. The legacy \LegacyTypeResolver\ is retained but marked deprecated, ensuring backward compatibility while providing a migration path. The \TypeMapper\ utility handles native PHP-to-OpenAPI type mapping, and \AbstractTypeResolver\ provides a common base for both resolvers. Users will see improved handling of complex PHP types in generated OpenAPI schemas, with the new resolver becoming the recommended approach.

src/Type · high confidence

The project has replaced legacy CI and configuration files with modern tooling: Travis CI has been removed in favor of GitHub Actions, and the old README has been replaced by a comprehensive new README, AGENTS.md, CLAUDE.md, CONTEXT.md, CONTRIBUTING.md, and ROADMAP.md. Code style is now enforced via php-cs-fixer (with custom rules) and Rector, static analysis via PHPStan, and spec validation via Redocly. The project now requires PHP 8.2, supports OpenAPI 3.0, 3.1, and 3.2, and introduces a beta 'Spec' attributes pipeline alongside the classic mode. Doctrine annotations are now optional (installed separately if needed). Configuration files include .editorconfig, .gitattributes, phpstan.neon.dist, rector.php, redocly.yaml, and an updated phpunit.xml.dist.

(repo-wide) · high confidence

The processor layer in src/Processors has been completely rewritten to operate on a new Analysis object, replacing the previous implementation. This change introduces a suite of new processors (such as AugmentDiscriminators, AugmentItems, AugmentMediaType, AugmentParameters, AugmentProperties, AugmentRefs, AugmentRequestBody, AugmentSchemas, AugmentTags, BuildPaths, CleanUnmerged, CleanUnusedComponents, DocBlockDescriptions, ExpandClasses, ExpandEnums, ExpandInterfaces, ExpandTraits, MergeIntoComponents, and MergeIntoOpenApi) that handle schema augmentation, inheritance expansion, path building, and component cleanup. The new logic improves how properties, references, and enums are resolved and merged into the final OpenAPI output, ensuring better compatibility with OpenAPI specifications and more robust handling of complex type structures.

src/Processors · high confidence

The logic for parsing and expanding \@phpstan-type\ aliases within docblocks has been moved into a new, dedicated \AliasExpander\ class. This change isolates the static-analysis type resolution behavior, making the codebase easier to maintain and ensuring that type aliases are correctly substituted in contexts like documentation generation and type resolution tests.

tools/src/TypeAlias · high confidence

The Specification module now centralizes how component keys are determined and how $ref values are resolved. A new ComponentName class provides a single source of truth for deriving component keys (e.g., schema name, response code) from their underlying attributes, ensuring that the compiler and the index use identical logic. The new ComponentIndex class lazily builds per-bucket indexes that map both canonical JSON Pointer names and fully qualified class names (FQCNs) to their objects, allowing the system to resolve references correctly even when FQCNs have not yet been rewritten. Additionally, a new Walker class offers safe, deduplicated traversal of the specification tree, including special handling for discriminator mappings and security requirements, which supports more reliable processing of nested structures and references.

src/Specification · high confidence

The compiler now uses dedicated classes for each OpenAPI version to handle specification differences. OpenApi30Compiler enforces OpenAPI 3.0.x constraints, such as requiring the 'paths' key, omitting unsupported features like webhooks and mutualTLS, and translating JSON Schema draft-04 semantics (e.g., using 'nullable' instead of 'null' in types). OpenApi31Compiler handles OpenAPI 3.1.x, supporting webhooks, mutualTLS, and JSON Schema draft 2020-12 features like 'examples' arrays and 'if/then/else'. OpenApi32Compiler extends 3.1 to support version 3.2.x additions, including tag 'summary', 'parent', and 'kind' fields. This ensures generated documents strictly adhere to the target version's specification.

src/Compiler · high confidence

Added comprehensive test coverage for the new Builder, Assembler, and Compiler components; Added comprehensive test suite for OpenAPI annotations and attributes; Added parser test fixtures for traits, interfaces, and attributes; Added scratch test fixtures for attribute inheritance, security schemes, and custom attributes; Added spec validation tests for attribute targets, slot consistency, and undefined defaults; Added test coverage for OpenAPI processor logic; Added test coverage for new Schema shortcut classes; Added test fixture for custom attachable attribute; Added test fixtures for Augmenter hierarchy and trait ordering; Added test fixtures for ComponentIndex edge cases; Added test fixtures for PHP 8 attributes on interfaces and traits; Added test fixtures for PHP 8+ attributes and type resolution; Added test fixtures for PHP 8.1 attributes in AnotherNamespace; Added test fixtures for annotation handling in AnotherNamespace; Added test fixtures for class expansion scenarios; Added test fixtures for the Augmenter pipeline; Added tests for Augmenter pipeline components; Added tests for ComponentIndex and Specification Walker; Added tests for TypeMapper and TypeResolver; Added tests for code style, documentation generation, and type alias expansion; Added tests for new HTTP method shorthand operation classes; Added tests for the new attribute-based analysis infrastructure; Added unit tests for the Utils subsystem; Expanded PHP test fixtures for OpenAPI attribute parsing; New test helper traits for assertions, logging, and fixture management.

The library now requires PHP 8.2 or higher and has renamed its namespace from \Swagger\ to \OpenApi\ to align with the OpenAPI 3.1.0 specification. The binary entry point has moved from \bin/swagger\ to \bin/openapi\. Documentation is now generated using VitePress, and spec validation is handled by the Redocly CLI. Development tooling has been updated to use PHPStan 2.x, Rector 2.6.5, and PHPUnit 11/12, with codestyle enforcement via PHP-CS-Fixer.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 73.

• Code Health 82
• Architecture 98
• Maturity 66
• Readiness 70
• Security 93

• 300 commits — 237 feature/other, 63 fixes

• tests/Fixtures — 57 commits
• (root) — 40 commits
• src/Processors — 19 commits
• src/Annotations — 18 commits
• .github/workflows — 17 commits
• src/Augmenter — 13 commits
• src/Spec — 12 commits
• docs/examples — 11 commits
• docs/reference — 10 commits
• src/Attributes — 10 commits
• src/Type — 10 commits
• src/Compiler — 9 commits
• docs/guide — 5 commits
• docs/snippets — 5 commits
• src/Analysers — 4 commits
• src/Console — 4 commits
• src/Generator.php — 4 commits
• src/Utils — 4 commits
• tests/Concerns — 4 commits
• tools/src — 4 commits

• fix: Fix CLI version override (#1992)
• fix: Fix CleanUnusedComponents incorrectly removing schemas referenced via JsonContent/XmlContent (#2047)
• fix: Fix getRelativePath in SourceFinder (#1918)
• fix: Fix merging of $additionalProperties (#1878)
• fix: Fix nested properties checks to include inherited properties (#1989)
• fix: Fix parameter name matching in method docblocks for LegacyTypeResolver (#1843)
• fix: Fix regression about unexpected items when augmenting parameters (#1949)
• fix: Fix version check to handle more than two versions (#1900)
• fix: Fix/clean unused components performance (#2030)
• fix: Fix/strict config keys and isvalid (#2132)
• fix: Fixed README.md (#1976)
• fix: Improve docs and fix broken link (#1825)
• fix: Rector / CS fixes (#1979)
• fix: Remove encoding BC fix and enforce use of Encoding class
• fix: Revert "fix: resolve Schema ref from parameter type in AugmentRequestBody (#2018)" (#2023)
• fix: feat(BEAT) various examples tests improvements and consistency fixes for testing (#2074)
• fix: fix(Annotations): accept mutualTLS as a SecurityScheme type (#2193)
• fix: fix(Annotations): add the Info Object's summary field (#2194)
• fix: fix(Annotations): compile a schema's examples as a list in classic too (#2176)
• fix: fix(Annotations): merge a plain MediaType into Parameter content (#2192)
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

zircote/swagger-php was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.