Registry Laravel Package

Product Decisions This Supports

• Build vs. buy for discovery infrastructure: v1.1.0 strengthens the case for adopting this package instead of maintaining a bespoke definition-discovery/registry layer. The release fixes duplicate class-declaration fatals across refresh, cache rebuild, cache verification, and Composer-autoloaded paths — exactly the edge cases a homegrown scanner tends to miss.
• Modular/package architecture roadmap: Supports auto-discovery of DefinitionProvider classes across packages and roots, including packages that share folders. This enables plugin-style extension points without forcing every package to manually register providers.
• Octane and queue-worker readiness: The package now detects class-declaring entrypoints that changed after load in long-running processes and raises DefinitionLoadException asking for a restart, rather than silently serving stale classes. This is a product-quality signal for teams running Laravel Octane or long-lived workers.
• Developer experience improvements: Class entrypoints can omit return Foo::class; when a file declares exactly one DefinitionProvider, reducing boilerplate in package/module definition files.
• Cache safety and operational confidence: Duplicate class declarations across entrypoints are reported as DefinitionLoadException instead of fatal errors, and files matched by multiple roots go to the registered kind whose contract accepts the definition. This makes cache rebuild/verification safer to expose in CI or deployment pipelines.
• Use cases: package auto-discovery, modular monolith definition registration, extension/plugin systems, cached definition registries, and environments where definitions are discovered from files rather than explicitly listed.

When to Consider This Package

Consider adoption when:

• You have multiple packages/modules contributing definition providers and want convention-based discovery over manual registration.
• You run Laravel Octane, queue workers, or other long-running processes and need safe behavior when definition files change.
• You cache discovered definitions and need refresh, rebuild, and verification paths that do not produce fatal “cannot declare class” errors.
• You want to simplify definition files with class entrypoints that declare a single DefinitionProvider.
• You have packages sharing directory roots and need deterministic routing to the correct registered kind.
• You need an API surface like DiscoveredFile::$alternatives, withAlternative(), and roots() for advanced discovery scenarios.

Look elsewhere when:

• Your application has a small, static set of providers and explicit registration is simpler.
• You do not discover definitions from files or need no caching layer.
• You cannot accept restart semantics for class-declaring entrypoints that change in long-running processes.
• You need hot-reload of changed classes without process restarts.

How to Pitch It (Stakeholders)

For executives: v1.1.0 is a stability and developer-experience release for the definition-discovery layer. It reduces fatal-error risk in cache rebuilds and long-running processes, supports package ecosystems that share folders, and lowers boilerplate for module authors. There are no indicated breaking changes; files that declare no classes behave exactly as before.

For engineering: This release makes class-declaring definition files safe across Registry::refresh(), cache rebuilds, cache verification, cache resolution, and Composer-autoloaded files. It adds class entrypoints, duplicate-class detection via DefinitionLoadException, restart guidance for changed classes in Octane/workers, and root-aware routing for packages sharing folders. The new DiscoveredFile::$alternatives, withAlternative(), and roots() APIs give us extension points without forking the package.

Recommendation: Adopt or retain this package where definition discovery is already part of the architecture. Treat v1.1.0 as a low-risk upgrade that closes operational edge cases and improves package-author ergonomics.