List Classes In Directory Laravel Package

Technical Evaluation

Architecture fit. wyrihaximus/list-classes-in-directory is a framework-agnostic PHP utility that sits at the code-introspection layer: given a path, it returns fully qualified class names extracted by tokenizing/parsing the files rather than by autoloading them. That distinction matters for a Laravel codebase. Because it does not trigger autoloading or instantiation, it is safe to run against classes that have constructor dependencies, side-effecting static initializers, or unresolved bindings — a real constraint if we tried to do the same thing with ReflectionClass over glob(). It has no Laravel coupling, no service provider, no config, and no facade, so it belongs in the tooling/infrastructure tier of our architecture, not the domain or HTTP layer. The realistic fit is one of: (a) build-time generation of a discovery manifest (commands, policies, observers, Livewire components, module registration), (b) an Artisan-based architecture/consistency audit, or (c) scaffolding and migration tooling. It is a poor fit as a per-request runtime dependency.

Integration feasibility. Trivially installable via Composer; the API surface is small and functional (directory and single-file entry points returning an iterable of FQCNs). The integration work is not in the wiring — it is in the caching and the abstraction we place around it. Discovery that walks the filesystem and parses files cannot run on every boot in a Laravel app of any size; it must be either a CI/build step that emits a manifest or a cached artisan command with the result persisted (config cache, generated PHP file, or cache store keyed on a hash of directory mtimes).

Technical risk. The dominant risk is not code quality — it is dependency posture. 24 stars, 0 dependents, and a single maintainer mean we are effectively self-supporting if the package stalls. Second-order risk is Composer resolution: if the package pins nikic/php-parser (or a tokenizer abstraction) at a major version that conflicts with PHPStan, Rector, Pint-adjacent tooling, or Pest plugins already in require-dev, we get a hard install failure that is annoying to unwind. Third, the package is small enough that "build vs. buy" is genuinely competitive: Symfony Finder plus token_get_all() is roughly 60 lines, and reading vendor/composer/autoload_classmap.php after composer dump-autoload -o is a zero-dependency alternative if PSR-4 compliance is guaranteed.

Key questions to resolve before adoption.

• What PHP version constraint does the current release enforce (likely 8.1+), and does that match our oldest supported Laravel runtime?
• Does it return a generator or a materialized array, and what is the memory profile on a 3,000-file app/ tree?
• Which symbol types are returned — classes only, or also interfaces, traits, and enums? Our use case determines this.
• What is the failure behavior on unparseable files (throw vs. skip silently)? Silent skipping is the dangerous mode.
• Does it follow symlinks, skip vendor/node_modules, and handle multiple class declarations per file and anonymous classes?
• Are the returned strings validated against the file's actual PSR-4 namespace, or is a namespace/class mismatch passed through undetected?

Integration Approach

Stack fit. Laravel 10/11/12 on PHP 8.2+. The package is a pure Composer addition with no publishable assets, so it fits at the lowest-friction tier. I would classify it as require-dev unless we deliberately ship runtime discovery, and even then the runtime path should consume a pre-generated manifest rather than the library directly.

Migration path. There is nothing to migrate; this is greenfield. The correct move is to introduce it behind an internal port — e.g. App\Support\Discovery\ClassDiscovery with a single iterate(string $path): iterable method — and bind the third-party implementation to that interface. That costs an hour and converts a supply-chain decision into a one-line swap if the package is abandoned, changes its API, or blocks a PHP upgrade.

Compatibility. Run composer require --dry-run and composer why-not against the current lockfile first; specifically check for transitive conflicts on any parser dependency. Confirm the package does not require an extension we don't guarantee in our base image (tokenizer is bundled, but confirm). Verify behavior under our autoloader configuration, including any non-standard PSR-4 mappings and classmap-authoritative production builds.

Sequencing.

1. Spike (0.5 day): install in a branch, point it at app/, measure wall time and memory on the largest module, and diff the output against composer dump-autoload -o's classmap to quantify false negatives.
2. Contract (0.5 day): define the internal ClassDiscovery port and a value object for results; write tests covering multiple classes per file, enums, anonymous classes, and a deliberately malformed file.
3. Caching (1 day): decide the manifest strategy — generated PHP file committed from CI, or a cache key with an mtime/commit-hash key.
4. Consumer (1 day): wire into the actual feature (an Artisan audit command, or a provider that reads the manifest). Do not let the library leak into domain code.
5. Guardrail: add an architecture test asserting the package is referenced only from the adapter namespace.

Operational Impact

Maintenance. Low surface area, MIT license, active-enough release history (most recent July 2024). But the bus factor is one. We should pin an exact version ("x.y.z" not "^x.y"), vendor-lock it, and record an internal owner. The realistic maintenance event is not a security patch or a feature request — it is a PHP minor-version bump where the maintainer is slow to widen the constraint, blocking our own upgrade. The adapter pattern is the insurance policy here.

Support. Community-only. No SLA, no commercial backing, issues answered on the maintainer's schedule. Internal documentation needs to cover the discovery contract, the caching invalidation rules, and the fallback plan, because we cannot escalate upstream.

Scaling. Cost is O(number of PHP files) with a parse per file. On a monorepo with several thousand files this is seconds, not milliseconds, which makes per-request or per-boot invocation unacceptable in production. Horizontal scaling is fine provided the manifest is baked into the deploy artifact; if discovery runs at boot, every pod pays the cost and behavior can diverge if filesystem ordering differs.

Failure modes. The dangerous ones:

• Silent empty result. Discovery returns nothing, so commands/policies/observers simply never register. No exception, no log line — features just quietly disappear. Mitigate with an assertion that discovery over a known directory returns a non-empty set, enforced in CI.
• Drift between environments. Files present in dev but excluded from the production build (or vice versa) yield different registries. Bake the manifest at build time from the same source tree that gets deployed.
• Namespace/class mismatch. Token parsing can report a symbol that isn't the one PSR-4 would autoload, producing a class name that fails at instantiation. Validate against the autoloader, not just the parser.
• Parser lag. Newer PHP syntax not understood by a pinned tokenizer produces skipped or partial results.
• Duplicate FQCNs. Two files declaring the same class returns both entries; downstream registration must dedupe.

Ramp-up. Hours for a mid-level engineer. Documentation is README-scale, so the internal adapter and its tests become the real onboarding artifact.

Recommendation. Adopt conditionally, not by default. The library is sound, small, and does one thing without side effects, which is exactly what you want from a utility. But with 24 stars, zero dependents, and a ~60-line equivalent reachable via Symfony Finder plus token_get_all(), this is a build-vs-buy call where buying saves little and imports an unowned dependency. Approve it only if (1) Composer resolution is clean against our existing dev toolchain, (2) it sits behind an internal interface, and (3) discovery output is generated at build time and cached. If any of those three fail, implement the scanner in-house — the maintenance delta is negligible and the risk transfer is zero.