Class Meta Laravel Package

Product Decisions This Supports

• Internal Enumeration/Classification Systems: Enables self-documenting, metadata-rich enums (e.g., statuses, categories, or taxonomies) without external databases or config files. Reduces ambiguity in codebases where constants are reused across services.
• Build vs. Buy: Avoids reinventing annotation-based metadata systems (e.g., Doctrine Extensions) for lightweight use cases. Ideal for teams already using PHP/Laravel and needing a simple, annotation-driven solution.
• Roadmap for Developer Experience:
  • Phase 1: Replace hardcoded constants with annotated enums (e.g., InvoiceStatus::DRAFT → InvoiceStatus::DRAFT with name="Draft").
  • Phase 2: Extend to dynamic metadata (e.g., localization, API response formatting) via annotations.
  • Phase 3: Integrate with Laravel’s service container to auto-register metadata for dependency injection.
• Use Cases:
  • Localization: Attach translation keys to constants (e.g., @Meta(data={"en":"Draft", "es":"Borrador"})).
  • API Contracts: Embed OpenAPI/Swagger metadata directly in enums for auto-generated docs.
  • Validation Rules: Define custom validation logic per constant (e.g., @Meta(data={"min_value":100})).

When to Consider This Package

• Adopt if:
  • Your team uses PHP/Laravel and needs a lightweight, annotation-based way to attach metadata to classes/constants.
  • You’re maintaining enums, statuses, or taxonomies that require human-readable labels or additional context (e.g., descriptions, weights).
  • You want to avoid external config files or databases for static metadata.
  • Your use case is simple (no need for complex query-building or ORM integration).
• Look elsewhere if:
  • You need runtime metadata modification (this is compile-time/annotation-only).
  • Your project requires active maintenance (last release: 2019; consider forking or alternatives like phpDocumentor or Doctrine Extensions).
  • You’re using non-PHP languages or frameworks with built-in solutions (e.g., TypeScript enums, Python’s Enum with _fields_).
  • You need database-backed metadata (use Laravel’s config or a dedicated package like spatie/laravel-enum).
  • Your team lacks PHP annotation experience (may require education on DocBlock usage).

How to Pitch It (Stakeholders)

For Executives: "This package lets us reduce technical debt by embedding human-readable metadata (e.g., labels, descriptions) directly into our codebase—no databases or config files needed. For example, instead of guessing what InvoiceStatus::PAID means, developers and support teams see @Meta(name="Paid") in the IDE. It’s a low-cost, high-impact way to improve code clarity and maintainability, especially for enums like statuses, categories, or permissions. Since it’s annotation-based, it integrates seamlessly with our existing PHP/Laravel stack and avoids vendor lock-in."

For Engineers: *"ClassMeta is a minimalist way to add structured metadata to classes/constants via DocBlock annotations. Think of it as self-documenting enums:

• Pros:
  • Zero runtime overhead (annotations parsed at load time).
  • Works with any Laravel/PHP project.
  • IDE-friendly (metadata visible in autocomplete/tooltips).
  • Extensible (can add custom metadata keys like priority, localized_names).
• Cons:
  • Unmaintained (last update: 2019; fork or vet before production use).
  • Limited to static metadata (no dynamic updates).
• Use it for: Statuses, taxonomies, or any constants needing labels/descriptions. Avoid for complex systems—consider spatie/laravel-enum or a custom solution instead."*

For Developers: *"Need to make UserRole::ADMIN more readable? Add @Meta(name="Administrator", description="Full system access") above the constant. Then access it via $manager->getMeta('UserRole::ADMIN')['name']. It’s like Javadoc for PHP constants—perfect for:

• Localization (attach translation keys).
• API docs (embed OpenAPI metadata).
• Validation hints (e.g., @Meta(min_value=100)). How to start:

1. Install: composer require ashleydawson/class-meta.
2. Annotate your enums (see README).
3. Use ClassMetaManager to fetch metadata. Warning: Package is stale; test thoroughly or fork for updates."*