Class Explorer Laravel Package

Getting Started

Install the package with Composer and confirm whether its service provider is auto-discovered. If the package publishes configuration, publish it first and review the scan paths, cache settings, and default recursive value before writing any discovery code.

The first place to look is the package README and its config file. The key entry point added in v1.1.0 is getClassMap, which returns the classes found in a given location together with the files they live in. That makes the first useful use case straightforward: build a class-to-file map for a directory such as app/, then filter or instantiate the classes you care about.

use Vendor\Package\ClassMap;

$map = app(ClassMap::class)->getClassMap(
    path: app_path(),
    recursive: true,
);

foreach ($map as $class => $file) {
    // $class is the fully qualified class name
    // $file is the path on disk
}

Start with a narrow path and recursive: false while experimenting, then enable recursion once you understand what the package is picking up. In a Laravel app, the most immediate wins are auto-registration of services, discovery of classes implementing a marker interface, or building an internal inventory of application classes for an Artisan command.

Implementation Patterns

Service provider registration. The most common day-to-day pattern is to call getClassMap during application boot or in a dedicated discovery service, then filter by namespace, interface, or attribute before registering anything with the container.

$classes = collect(app(ClassMap::class)->getClassMap(app_path('Services'), recursive: true))
    ->keys()
    ->filter(fn (string $class) => is_subclass_of($class, Contract::class));

foreach ($classes as $class) {
    $this->app->singleton($class);
}

Cache aggressively in production. Class discovery is filesystem work, so treat the map as expensive. Warm it during deployment with a custom Artisan command and let the package cache serve subsequent requests. In local development, prefer disabling the cache or clearing it as part of your workflow so newly created classes appear immediately.

Use recursive scans deliberately. Use recursive: true for broad discovery across app/ or a module directory, and recursive: false when you only want the immediate directory. After v1.1.0, the cache key accounts for this parameter, so recursive and non-recursive scans no longer collide.

Filter before reflecting. Build the map first, then narrow by namespace or interface, and only then use reflection. This keeps reflection costs down and avoids instantiating or inspecting unrelated classes.

Integrate with existing Laravel discovery. The class map is a good fit for packages that need their own event, route, policy, or component discovery. Rather than hard-coding class lists, scan a known directory and feed the resulting class names into Laravel’s registration APIs.

Expose it through an Artisan command. A small app:class-map command that dumps the map is useful for debugging, onboarding, and CI checks. It also gives you a quick way to verify what the package sees after configuration changes.

Gotchas and Tips

• Clear the cache after upgrading to v1.1.0. The cache key now includes the recursive parameter. Existing cached entries created before the fix may still return the wrong shape, so run your cache clear command after upgrading.
• Watch for stale maps in development. If you add or remove classes and the map does not change, the cache is the first suspect. Disable caching locally or clear it whenever you create a new class.
• Be explicit about recursion. If you call getClassMap both recursively and non-recursively against the same path, v1.1.0 handles the cache separation correctly. On older versions, those calls could poison each other’s results.
• Exclude vendor and test paths. Broad recursive scans can pick up far more than intended. Scope the path and use the package’s filtering or your own namespace/interface filters.
• Do not confuse filesystem discovery with Composer autoloading. getClassMap reports classes and files it finds on disk; it does not replace Composer’s autoloader. If a class is not autoloadable, discovering its file is not enough to use it.
• Check symlink and case-sensitivity behavior. Containers, mounted volumes, and case-insensitive filesystems can produce surprising paths. Verify the map in the same environment where the application runs.
• Use getClassMap as the debugging primitive. When discovery behaves unexpectedly, dump the raw map first. It tells you whether the problem is path selection, recursion, filtering, or caching.
• Prefer a dedicated discovery service. Wrapping the package in your own service makes it easier to swap implementations later and keeps package-specific calls out of controllers and models.
• No breaking changes are indicated in v1.1.0. The new getClassMap method is additive, and the cache-key fix is a bug fix. The main upgrade action is clearing stale caches and confirming that any code relying on cached recursive results now behaves correctly.