Annotation Reader Laravel Package

Product Decisions This Supports

• Metadata strategy: docblocks vs. PHP 8 attributes vs. config files. Informs where configuration-driven behavior (routing metadata, validation rules, serialization groups, ORM/DI hints, feature flags) should live. This package represents only the legacy docblock option — the realistic decision is usually "attributes or explicit config," so treat this as a data point on the sunsetting end of that spectrum, not a forward-looking bet.
• Build vs. buy for metadata parsing. Reinforces that hand-rolling a docblock parser is rarely justified. The actual comparison set is doctrine/annotations (deprecated), phpdocumentor/reflection-docblock, roave/better-reflection, or native ReflectionAttribute — not this package. With 0 stars and 0 dependents, it is not a viable "buy" either.
• Legacy modernization roadmap. Useful as a transitional compatibility shim when auditing PHP 7.x codebases that still depend on annotation-driven frameworks, admin generators, or internal code-gen tooling, and need a scoped, time-boxed bridge to attributes.
• Use cases it can support in a contained form: internal scaffolding/code generators, plugin or handler discovery, form/admin builders that read metadata off classes, and config-from-code patterns (e.g., a FeatureFlags class read at boot).
• Dependency governance. The decision this best supports is scope and contain, not adopt and extend. It serves as a concrete example for a dependency-review policy: no active maintenance, no dependents, no community pressure for fixes means high ownership burden for low value.

When to Consider This Package

Consider only when:

• You are maintaining a legacy PHP 7.x application that already relies on docblock annotations and needs a small parser to bridge existing code, and no supported alternative is compatible yet.
• The annotation surface area is small, internal-only, and not security- or customer-facing.
• You are prepared to vendor or fork it and own maintenance: patches, PHP-version compatibility, security review, and documentation.
• You can isolate it behind an application-owned interface (e.g., MetadataReader) with aggressive caching keyed by class plus file mtime, so a later swap to attributes is a one-file change.

Look elsewhere when:

• You are greenfield or on PHP 8+ — use native attributes with ReflectionAttribute; the annotation layer is unnecessary.
• You need active maintenance, CVE response, documented upgrade paths, or community support (0 stars / 0 dependents is a strong negative signal).
• You need performance at scale or standards-compliant parsing — prefer phpdocumentor/reflection-docblock or roave/better-reflection.
• The feature is on a critical path (routing, authorization, serialization, billing), where silent misparses and cache-invalidation bugs are unacceptable.
• You would need to build and own a Laravel adapter (service provider, config, error handling) — that cost usually exceeds the value versus writing a thin native-attributes reader.

How to Pitch It (Stakeholders)

Executive summary: ibrows/annotation-reader is a low-maturity, effectively unmaintained PHP library for reading docblock annotations (0 stars, 0 dependents, negligible health score). It is not a strategic dependency and should not be adopted for new work. Its only defensible role is a short-lived compatibility shim inside a legacy PHP 7.x codebase, funded alongside an explicit migration to native PHP 8 attributes or a maintained reflection library.

For engineering: Treat any existing usage as tech debt. Wrap it behind an internal interface so no controller, model, or service calls the package directly; register it as a singleton and cache parsed metadata (parsing via reflection costs milliseconds per class and dominates requests that touch many models). Expect to own the adapter, the boot-time validation of annotations, and PHP-upgrade compatibility, and plan to fork if the upstream stalls. Note the classic failure modes: annotation autoloading (AnnotationRegistry::registerLoader('class_exists')), silent misparses on whitespace/quoting errors, and opcache or formatters stripping docblocks. Quarantine the real parser behind one or two integration tests; fake the reader everywhere else.

Recommended decision: Contain, don't adopt. Approve only as a transitional bridge with a defined exit criterion (migration to attributes or a maintained reflection library), a named internal owner, a pinned version, and a place on the deprecation backlog. Reject for greenfield, customer-facing, or performance-sensitive work.