Skip to content
CAI
Software that uses CAICheck a score

zircote/swagger-php

49.9

Weak · 17 November 2026

31.7k

lines of production code

PHP

primary language

5

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

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.