Skip to content

feat: add Assembler and AttributeFactory for spec attribute collection#8

Closed
DerManoMann wants to merge 3 commits into
feat/spec-dtofrom
feat/assembler
Closed

feat: add Assembler and AttributeFactory for spec attribute collection#8
DerManoMann wants to merge 3 commits into
feat/spec-dtofrom
feat/assembler

Conversation

@DerManoMann

@DerManoMann DerManoMann commented Jul 12, 2026

Copy link
Copy Markdown
Owner

Summary

Introduces the assembly stage of the spec pipeline — the step that scans PHP classes and collects spec attributes into a Specification container.

Source files → ReflectionClass → Assembler → Specification

Depends on zircote#2054.

Design

Two-pass assembly

The Assembler runs two distinct passes per class:

  1. Sibling merge — attributes on the same reflector compose via merge() maps. E.g., Schema merges into Property filling its $schema slot.
  2. Hierarchy resolution — attributes from inner reflectors (properties, methods, parameters, constants) flow up into enclosing-level attributes via contains() maps. E.g., Operation on
    a method absorbs Parameter from its parameters; Schema on a class absorbs Property from its members.

After both passes, only root attributes remain and are added to the Specification. Non-root attributes that survive resolution trigger an error (orphan detection).

AttributeFactory

Extracted helper that encapsulates:

  • Reading PHP 8.1+ attributes from reflectors
  • Sibling composition via merge() slot maps (same-reflector nesting)
  • Hierarchical absorption via contains() slot maps (inner → outer)

Shared between the Assembler and future augmenter pipes that need to manufacture spec objects from reflection (e.g. ExpandHierarchy for non-schema ancestor members).

Slot semantics

The merge() and contains() maps return [TargetClass => 'slotName']:

  • 'parameters[]' — collection append
  • 'requestBody' — scalar assignment

This eliminates the implicit $_nested arrays and reflection-heavy nesting logic from the classic pipeline.

Orphan detection

After hierarchy resolution, any remaining non-root attribute is an error — e.g. a Parameter on a class without a PathItem or Operation to absorb it. The Assembler throws
OpenApiException with source location context.

@DerManoMann

Copy link
Copy Markdown
Owner Author

Moved to zircote#2057 (base branch updated to master now that spec-dto is merged)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant