zircote/swagger-php
49.9
Weak · 17 November 2026
31.7k
lines of production code
PHP
primary language
5
measurements over time
What this system is
Features
Initial release of the OpenAPI Annotations library
This change introduces the \src/Annotations\ directory, providing the foundational annotation classes for generating OpenAPI specifications. It includes the \AbstractAnnotation\ base class for handling nested structures and serialization, along with concrete annotations for OpenAPI components such as \Info\, \Schema\, \PathItem\, \Parameter\, \Response\, \SecurityScheme\, and \Components\. The implementation supports OpenAPI versions 3.0.x, 3.1.x, and 3.2.0, enabling users to document API endpoints, schemas, and metadata using PHP annotations or attributes.
src/Annotations · high confidence
Introduce custom PHP CS Fixer rules for OpenApi code style
The CSFixer tool now includes new custom fixers that enforce project-specific coding standards: the SpecNamespaceAliasFixer rewrites imports of the OpenApi\\Spec namespace to use the OA alias, the ScopedLicenseFixer ensures all PHP files have the Apache 2.0 license header, and the ScopedDeclareStrictTypesFixer manages strict types declarations. These changes standardize how the OpenApi library's code is formatted and linted.
tools/src/CSFixer · high confidence
Introduces PHP 8 Attributes as a parallel API to existing Annotations
The library now provides a complete set of PHP 8 Attributes (e.g., \\#\[OA\\Get\]\, \\#\[OA\\Schema\]\) that mirror the existing Annotation classes. These new attributes allow users to define OpenAPI specifications using modern PHP syntax, supporting the same properties and nesting structures as the legacy annotations. The implementation includes dedicated attribute classes for all major OpenAPI components, such as Operations, Schemas, Parameters, and Responses, ensuring feature parity with the annotation-based approach.
src/Attributes · high confidence
Introduces a new spec-attribute pipeline alongside the classic annotation pipeline
The library now supports a new generation mode driven by PHP attributes and a dedicated \Assembler\ and \Specification\ container, accessible via \Builder::setMode(Builder\\Mode::SPEC)\. This new pipeline collects attributes into a flat \Specification\ object, resolves references using a \Resolver\ (with a built-in \Reflection\ resolver that auto-collects referenced classes), and compiles the result using a \Compiler\. A \HybridBridge\ is also provided to convert existing classic annotations into this new spec format, enabling a \HYBRID\ mode for gradual migration. The classic \Generator\ and \Parser\ classes remain available in \CLASSIC\ mode, but the new architecture provides a more structured, attribute-first approach to OpenAPI generation.
src · high confidence
New Augmenter pipeline replaces the legacy processing model
The \src/Augmenter\ directory has been completely rewritten to use a new \PipeInterface\-based pipeline architecture, replacing the previous monolithic processing logic. This change introduces a series of specialized augmenters that handle specific specification tasks in distinct phases (Resolve, Augment, Reduce). Key capabilities now include automatic cleanup of unreferenced components (\Cleanup\), default media type assignment (\DefaultMediaType\), docblock-based metadata population (\Docblocks\), PHP enum expansion (\Enums\, \EnumDescriptions\), inheritance resolution (\Inheritance\), and operation ID generation (\OperationIds\, \OperationIdTemplates\). The new structure also adds path filtering (\PathFilter\), path item hierarchy resolution (\PathItems\), and component naming inference (\Names\), providing a more modular and extensible foundation for OpenAPI specification generation.
src/Augmenter · high confidence
New CollectingLogger and DefaultLogger implementations
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.
src/Loggers · high confidence
New Spec attribute classes for OpenAPI definitions
The \src/Spec\ directory now contains a comprehensive set of new PHP attribute classes (e.g., \OpenApi\, \Info\, \Schema\, \Operation\, \Parameter\, \Response\, \MediaType\, \Components\) that allow users to define OpenAPI specifications using native PHP attributes. These classes provide a structured, type-safe way to declare API metadata, paths, operations, and reusable components, replacing or supplementing the previous annotation-based approach with modern PHP 8+ attribute syntax. Also in this area: Support bare Schema in RequestBody and Response content; Support for multiple HTTP methods and nestable attribute fan-out in spec declarations.
src/Spec, src/Spec/Flow, src/Spec/Parameter · high confidence
New TypeAlias expansion tool for resolving PHPStan type aliases
A new \AliasExpander\ class has been added to the \tools/src/TypeAlias\ directory to handle the expansion of \@phpstan-type\ aliases and \@phpstan-import-type\ imports within docblocks. This utility parses alias declarations and substitutes them into type strings, which is necessary for static-analysis tools and documentation generators that need to resolve these names verbatim, as they are not resolved at runtime. The tool supports resolving imports from parent classes and traits, ensuring that inherited type aliases are correctly expanded.
tools/src/TypeAlias · high confidence
New documentation generator and classic-to-spec migration tooling
Added \tools/docgen.php\ to automatically generate reference documentation for OpenAPI attributes, processors, augmenters, extension points, mergers, and examples, writing the output to the \reference/\ and \guide/\ directories. Also added \tools/rector-map.php\ to generate the class mapping required for the classic-to-spec migration set, handling explicit renames and structural changes between the \OpenApi\\Attributes\ and \OpenApi\\Spec\ namespaces.
tools · high confidence
New utility classes for pipeline processing, reflection, and source scanning
The \src/Utils\ directory now includes a suite of new utility classes that support the library's pipeline and specification-based processing architecture. \Pipeline\ and \PipeInterface\ provide a structured way to execute processing steps with optional grouping and configuration via the \Config\ attribute. \AttributeFactory\ handles the creation and resolution of spec attributes from PHP reflectors, while \SourceScanner\ and \SourceFinder\ manage the resolution of source inputs into file paths and reflectors. Additional utilities include \DocBlockParser\ for parsing PHPDoc comments, \TokenScanner\ for static code analysis of class structures, \ClassReflector\ for safe reflection of potentially unloadable classes, and \JsonPointer\ for handling JSON Pointer escaping. \ServerVariableEnum\ ensures server variable enums are normalized to strings, and \SourceLocation\ provides detailed source context for errors. Also in this area: Improved PHP declaration inference and operation ID template handling; Support for multi-method operations and deep-copy isolation in the Augmenter.
src/Utils · high confidence
Support for PHP class inheritance in OpenAPI operations and schemas
The Augmenter now automatically resolves PHP class hierarchies to generate correct OpenAPI documentation. For schemas, it walks parent classes, traits, and interfaces to merge member properties or apply allOf references, ensuring that inherited fields appear in the final spec. For operations, it clones methods defined in abstract or non-annotated parent classes into concrete child controllers, allowing prefix, tag, and security composition to apply correctly to inherited endpoints. Also in this area: Improved PHP declaration inference and operation ID template handling; Support for multi-method operations and deep-copy isolation in the Augmenter.
src/Augmenter/Inheritance · high confidence
Removals
Removed petstore-simple example using Swagger v1 annotations
The petstore-simple example file (pets.php) has been removed. This file previously demonstrated the use of Swagger v1 annotations (e.g., @SWG\\Get). Its removal aligns with the ongoing rewrite to support the Swagger v2.0 specification, indicating that this specific example is no longer valid or maintained under the new standard.
Examples · high confidence
Behavioural changes
16 commits (0 fixes) modifying src/Contracts
A change to existing behaviour in src/Contracts — 16 commits, 11 files: “refactor(Spec): give attributes that carry a ref an interface (\#2343)”; “refactor(Builder): hand the namer and attribute factory out by interface (\#2353)”; “refactor(Spec): create \Contracts\ namespace for all spec related interfaces (\#2129)”; and 13 more (refs \#2343, \#2353, \#2129, \#2220, \#2161, …).
(repo-wide) · medium confidence · unverified
17 commits (2 fixes) modifying src/Console
A change to existing behaviour in src/Console — 17 commits (2 fixs), 3 files: “Mark the bridge and mode selection deprecated for 8.0”; “feat(Builder): let plugins configure the builder (\#2360)”; “Fix CLI version override (\#1992)”; and 14 more (refs \#2360, \#1992, \#2084, \#2225, \#2039, …).
src/Console · medium confidence · unverified
58 commits (23 fixes) modifying src/Compiler
A change to existing behaviour in src/Compiler — 58 commits (23 fixs), 4 files: “fix(Compiler): emit only the operation methods each version defines (\#2270)”; “feat(Spec): a \Format\ enum, and 3.0 formats for \contentEncoding\ and \contentMediaType\ (\#2248)”; “refactor(Spec): use \Undefined::UNDEFINED\ for every mixed property (\#2150)”; and 55 more (refs \#2270, \#2248, \#2150, \#2387, \#2154, …).
src/Compiler · medium confidence · unverified
Field-level folding for merging OpenAPI operations and tags
The merge system now supports field-by-field folding for operations and tags, rather than simply keeping one declaration and discarding the other. An opt-in \Operations\ merger combines two operations for the same path and method by merging their fields (such as parameters, responses, and requestBody) according to a configurable mode (Last, First, or NonOverlapping), while the default \Tags\ merger now similarly folds tag declarations. This allows contributions from multiple sources to be combined intelligently, with conflicts logged, instead of one source silently overwriting the other.
src/Merge · high confidence
Introduce extensible attribute translation pipeline for OpenAPI spec generation
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. Also in this area: Support for operations declared on invokable classes via \_\_invoke; Support for multi-method operations and deep-copy isolation in the Augmenter.
src/Assembler · high confidence
Migrate CLI to Symfony Console
The \bin/openapi\ entry point has been rewritten to use the Symfony Console component, replacing the previous implementation. This change introduces a new \GenerateCommand\ and configures logging to stderr to prevent diagnostic messages from mixing with the generated OpenAPI document on stdout. It also explicitly removes Symfony's built-in \--version\ and \--no-interaction\ options to avoid conflicts with the tool's own \--version\ (spec version) and \--pattern\ arguments.
bin · high confidence
New processor concern traits for annotation handling and inheritance
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
Refactored type resolution with new core components and improved schema generation
The type resolution system has been restructured to improve accuracy and maintainability. A new \TypeResolver\ core now leverages Symfony TypeInfo and PHPStan's phpdoc-parser to resolve PHP types into a \SchemaType\ value object, which is consumed by both the new \TypeInfoTypeResolver\ and the existing \LegacyTypeResolver\. This change introduces better handling for composite types (oneOf, allOf, anyOf), PHPDoc array shapes (mapped to object schemas with properties), and generic types. It also fixes several behavioral issues: PHP \mixed\ types no longer emit invalid OpenAPI \type: mixed\, \\\stdClass\ is correctly resolved to an object type, and explicit \additionalProperties: false\ is no longer incorrectly dereferenced as a schema. A new \TypeMapper\ centralizes native PHP-to-OpenAPI type mapping. Also in this area: Fix DateTimeInterface mapping and add utility methods in Type module; Improved handling of invalid references and case-insensitive docblock types. Also in this area: 1 commit (0 fixes) modifying src/Specification, src/Type; 3 commits (0 fixes) modifying src/Type.
src/Type · medium confidence · unverified
Repository tooling and configuration overhaul
The project has standardized its development environment by introducing EditorConfig and .gitattributes for consistent line endings and whitespace, replacing Travis CI with GitHub Actions, and adopting php-cs-fixer and Rector for code style enforcement. Static analysis is now managed via PHPStan with a baseline file, and generated OpenAPI specs are validated using Redocly. Additionally, the legacy Travis configuration and old README have been removed, and the license file has been renamed to comply with GitHub's expectations.
(repo-wide) · high confidence
Rewritten processor pipeline with new analysis and augmentation logic
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
Unified component indexing and path hierarchy resolution
The specification engine now uses a centralized \ComponentIndex\ to resolve \$ref\ values, supporting both standard OpenAPI paths (e.g., \\#/components/schemas/Foo\) and fully qualified class names. A new \ComponentName\ class enforces a single \component\ key field for all reusable attributes, normalizing legacy per-type spellings (like \schema\ or \parameter\) and issuing deprecation warnings for version 6.12. Additionally, \PathItemHierarchy\ replaces the previous four-step ancestor walk with a single chain traversal to correctly compose path prefixes and aggregate parameters from parent classes, ensuring that subclass operations inherit the correct path context and parameter definitions. Also in this area: 1 commit (0 fixes) modifying src/Specification, src/Type; 3 commits (0 fixes) modifying src/Type.
src/Specification · medium confidence · unverified
Fixes
8 commits (5 fixes) fixing rector/set
A fix in rector/set — 8 commits (5 fixs), 2 files: “fix(Rector): rewrite a parameter's style arguments and list what the set leaves (\#2319)”; “feat(Rector): rewrite security requirement arrays to Security\\Requirement (\#2262)”; “feat(Rector): a classic to spec migration set, and a guide for what it leaves (\#2234)”; and 5 more (refs \#2319, \#2262, \#2234, \#2255, \#2320, …).
rector/set, rector/src · medium confidence · unverified
Test coverage
1 commit adding/updating tests in tests/Fixtures/ClassDescriptions, tests/Fixtures/ComponentName; 1 commit adding/updating tests in tests/Fixtures/PHP/GroupedImports; 11 commits adding/updating tests in rector/tests; 12 commits adding/updating tests in tests/Builder; 14 commits adding/updating tests in src/Spec/Security; 2 commits adding/updating tests in tests/Compiler; 4 commits adding/updating tests in tests/Assembler; 4 commits adding/updating tests in tests/Benchmarks; 5 commits adding/updating tests in src/Spec/Concerns; Added Augmenter test fixtures for PHP 8.2+ features and schema composition; Added comprehensive test suite for annotation validation and attribute synchronization; Added parser test fixtures for traits, interfaces, and attributes; Added scratch test fixtures for attribute inheritance, security schemes, and component references; Added test coverage for Analysis, Assembler, Builder, and Compiler components; 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 Assembler merge and attachable behavior; 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 fan-out attribute feature; Added tests for Augmenter pipeline components; Added tests for Spec attribute targets, component arguments, and fan-out behavior; Added tests for Specification component indexing, naming, and path hierarchy; Added tests for TypeMapper and TypeResolver; Added tests for code style fixer and documentation generation logic; Added tests for multi-method operation handling; Added tests for new HTTP method shorthand operation classes; Added tests for the new attribute-based analysis infrastructure; Added tests for the new opt-in Operations merger and Tag merging logic; 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.
Dependencies
Upgrade to PHP 8.2+ and migrate to OpenAPI 3.1.0 with VitePress documentation
The library now requires PHP 8.2 or higher and has migrated its namespace from \Swagger\ to \OpenApi\ to support the OpenAPI 3.1.0 specification. Core dependencies have been updated to \nikic/php-parser\ and \phpstan/phpdoc-parser\, while the documentation site has been upgraded to VitePress. The CLI entry point has changed from \bin/swagger\ to \bin/openapi\, and the project now includes dev tools for Redocly validation and automated documentation generation.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 51.5 → 49.9 (-1.6)
- Rubric changed (rubric-2026.11.2 → rubric-2026.11.4) — scores are not directly comparable.
Lenses
- Code Health 56.1 → 53.4 (-2.7)
- Architecture 84.4 → 55.3 (-29.1)
- Maturity 69.6 → 82.3 (+12.7)
- Readiness 65.5 → 65.2 (-0.3)
- Security 38.7 → 38.7 (0.0)
- Performance 95.0 (new)
Resolved (10)
- Classify ADR enforcement: ADR-001: Context Keys and Annotation Lifecycle (docs/adr/001-context-keys-and-annotation-lifecycle.md)
- Classify ADR enforcement: ADR-002: Analysis Registries and Tree Structure (docs/adr/002-analysis-registries-and-tree-structure.md)
- DocGenerator.collectOptions (cognitive 17) (tools/src/Docs/DocGenerator.php)
- DocGenerator.parseDocblock (cognitive 38) (tools/src/Docs/DocGenerator.php)
- DocGenerator.parseDocblock (cyclomatic 16) (tools/src/Docs/DocGenerator.php)
- Off-boarding risk: anonymized user #1
- OpenApi31Compiler.validate (cyclomatic 16) (src/Compiler/OpenApi31Compiler.php)
- ParametersSection.render (cognitive 25) (tools/src/Docs/Sections/ParametersSection.php)
- Projects may be oversized for their cohesion
- Resolver.collectFromReflectors (cognitive 16) (src/Resolver.php)
New (46)
- ADR not followed: ADR-001: Context Keys and Annotation Lifecycle (docs/adr/001-context-keys-and-annotation-lifecycle.md)
- ADR not followed: ADR-002: Analysis Registries and Tree Structure (docs/adr/002-analysis-registries-and-tree-structure.md)
- Circular dependency (rector/set/classic-to-spec-classes.php)
- ClassTooLong: OpenApi31Parser (src/Compiler/OpenApi31Parser.php)
- Duplicated block (8 lines × 2) (src/Utils/SourceInspector.php)
- Edited copies of one member (3 members, 9+ corresponding lines) (src/Compiler/OpenApi31Parser.php)
- Edited copies of one member (4 members, 12+ corresponding lines) (src/Compiler/OpenApi31Parser.php)
- Edited copy of a member (10 corresponding lines) (src/Augmenter/Inheritance/Schemas.php)
- Edited copy of a member (11 corresponding lines) (src/Annotations/Schema.php)
- Edited copy of a member (11 corresponding lines) (src/Compiler/OpenApi31Parser.php)
- Edited copy of a member (13 corresponding lines) (rector/src/FanOutRector.php)
- Edited copy of a member (13 corresponding lines) (rector/src/MoveSchemaKeywordsRector.php)
- Edited copy of a member (13 corresponding lines) (src/Annotations/Examples.php)
- Edited copy of a member (14 corresponding lines) (src/Resolver.php)
- Edited copy of a member (16 corresponding lines) (src/Compiler/OpenApi31Parser.php)
- Edited copy of a member (19 corresponding lines) (src/HybridBridge.php)
- Edited copy of a member (32 corresponding lines) (rector/src/EncodingKeyRector.php)
- Edited copy of a member (35 corresponding lines) (src/Processors/MergeJsonContent.php)
- Edited copy of a member (37 corresponding lines) (src/Analysis.php)
- Edited copy of a member (7 corresponding lines) (src/Annotations/AbstractAnnotation.php)
- …and 26 more
Changes since last survey
- 44 commits — 33 feature/other, 11 fixes
By area
- (root) — 9 commits
- docs/guide — 6 commits
- src/Type — 6 commits
- src/Compiler — 5 commits
- src/Utils — 3 commits
- tests/Fixtures — 3 commits
- docs/dev — 2 commits
- src/Spec — 2 commits
- tests/Benchmarks — 2 commits
- docs/examples — 1 commit
- docs/snippets — 1 commit
- rector/src — 1 commit
- rector/tests — 1 commit
- src/Augmenter — 1 commit
- tests/Augmenter — 1 commit
Notable commits
- fix: fix(Classic): keep example values typed (#2368)
- fix: fix(Compiler): name the declaration in 3.0 schema warnings (#2370)
- fix: fix(Compiler): warn about schema keywords dropped beside a $ref (#2362)
- fix: fix(Compiler): write the extensions of components and properties (#2405)
- fix: fix(Composer): drop the symfony/process conflict (#2395)
- fix: fix(Rector): add fan: Fan::All where classic copied an attribute into several
- fix: fix(Resolver): chase only the types of documented properties (#2361)
- fix: fix(Spec): log an error where the document is invalid or input is lost (#2375)
- fix: fix(Spec): word messages subject first and location last (#2377)
- fix: fix(TokenScanner): resolve grouped class imports (#2392)
- fix: fix(Type): report any docblock the type resolver fails on (#2393)
- change: chore(Augmenter): drop the docblocks on the aware setters (#2384)
- change: chore(Config): ignore phpbench's result store (#2369)
- change: chore(Config): keep the tool caches in .cache/ (#2378)
- change: chore(Config): run the test suites with a 256M memory limit (#2390)
- change: chore(Utils): deprecate TokenScanner (#2388)
- change: chore(Utils): drop the @internal tag on SourceInspector::tokens() (#2379)
- change: chore(deps-dev): bump @redocly/cli (#2380)
- change: chore(deps-dev): bump @redocly/cli (#2409)
- change: chore(deps-dev): update friendsofphp/php-cs-fixer requirement (#2381)
- …and 24 more
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
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.
About this page
- The score is its most recent published measurement, taken on 17 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit bd7b6cfb36d0a01b644a076a1cac79702b76d598 — the exact code this score is about.
- Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.85+preprod-eba6548ac50f.