Flyfinder Laravel Package

Product Decisions This Supports

• Build vs. buy for file discovery. FlyFinder answers a single recurring question — "which files in this filesystem match these criteria?" — with composable predicates (IsHidden, HasExtension, InPath, Glob, plus and/or/not combinators). The build alternative is 100–200 lines of RecursiveDirectoryIterator glue plus per-adapter special-casing. The buy cost is one MIT dependency, so this is a low-stakes decision best made on fit, not on cost.
• Feature enablement where file selection is a prerequisite, not the product. Documentation generators, static analyzers, linters, asset/config scanners, migration and scaffolding utilities, cache warmers, and "package only these files" export flows all embed the same scan-and-filter step. Adopting this package keeps that step out of your critical path.
• Cross-adapter consistency. The package operates on a Flysystem Filesystem, so the same query returns the same results over local disks, in-memory adapters, S3, or SFTP. This matters if your roadmap includes remote or pluggable storage: a hand-rolled local-only walker becomes a rewrite the day a non-local adapter appears.
• Compliance and hygiene defaults. Hidden-file exclusion, extension allowlists, and path scoping (wildcards supported via InPath/Glob) are exactly the controls used to avoid scanning .git/node_modules, avoid publishing dotfiles, or restrict a scan to an allowlisted subtree. Encoding these as named specifications makes the policy readable and testable rather than buried in an if ladder.
• Scope realism on the roadmap. This is infrastructure, not a differentiator. Treat it as an enabler that saves days, not a capability that sells the product. It should not appear in a roadmap narrative to customers.
• Reuse signal for phpDocumentor-adjacent tooling. If your product sits in the documentation/analysis space, adopting the same primitive the reference tool uses reduces divergence in how files are discovered and filtered.

When to Consider This Package

Consider adopting when:

• The project is already on Flysystem 3 (this is the supported baseline; the 2.0 line is the port, and 1.x supported Flysystem 1/2). If you are not on Flysystem, the package adds an abstraction you do not need.
• You need predicate-style file queries — extension sets, hidden-file rules, path scoping with wildcards — and you want them composable (andSpecification / orSpecification / notSpecification) rather than bespoke.
• You need the same query semantics across multiple storage backends, or expect to move to one.
• You are comfortable with small-maintainer risk and can absorb it: wrap usage behind an internal service interface, pin to ^2.0.1 (2.0.1 fixed a Glob defect that could write into Flysystem 3 attributes — a data-integrity concern if you are on 2.0.0), and add a smoke test around Glob against a real disk.
• The consuming code is CLI or background work (Artisan commands, queue jobs, build steps) where a per-invocation lifecycle and no long-running state are acceptable.

Look elsewhere or build in-house when:

• A single local disk with straightforward patterns. PHP's native glob()/RecursiveDirectoryIterator or Symfony Finder covers this with a far larger user base, more documentation, and no additional dependency. Symfony Finder is the default answer unless remote/multi-adapter storage is on the table.
• You need directories in the results. FlyFinder returns files only; directory enumeration is out of scope. Do not adopt it and then patch around this.
• You need metadata-heavy operations (mtime windows, size thresholds, content predicates). Only hidden/extension/path/glob criteria exist; anything else is your code on top.
• You need vendor support, an SLA, a security disclosure process, or a documented maintenance cadence. None are published. Popularity is low (~30 stars, zero dependents), and contributor breadth is narrow.
• Performance on very large trees or remote disks is a hard requirement. There are no published benchmarks; throughput against network-backed adapters is unmeasured. If you plan to scan tens of thousands of entries per run, benchmark first or choose a tool with known characteristics.
• Your Laravel/PHP version constraints are tight and unverified. Confirm the PHP floor and Flysystem constraint against your target framework before committing; transitive constraint conflicts are the most likely integration failure.

Decision rule: adopt if Flysystem 3 is already in the stack and you need composable, adapter-agnostic file queries. Otherwise, use Symfony Finder or native iteration and revisit only when a second storage backend appears.

How to Pitch It (Stakeholders)

To executives: "We have a recurring, low-glamour engineering task: finding the right files inside a storage location so a feature can act on them. Today each team writes that scan themselves, slightly differently, and it breaks when storage changes. FlyFinder is a small, MIT-licensed, zero-cost library that standardizes that step. It carries no license fee, no runtime service, and no vendor relationship, and its blast radius is contained because we will wrap it behind our own interface. Expected value is measured in days of engineering saved per integration and in avoided rework if we add remote storage — not in new customer-facing capability. The risk is maintenance, not functionality: the project is small and single-maintainer, so we adopt it with a pinned version and a documented exit path rather than as a foundational dependency."

To engineering:

• composer require phpdocumentor/flyfinder:^2.0.1 — pin at or above 2.0.1; 2.0.0 had a Glob bug that wrote into Flysystem 3 attributes.
• Usage is two lines: construct Finder with an existing Flysystem Filesystem, then compose specifications — $inPath->andSpecification($hasExtension)->andSpecification($isHidden->notSpecification()). InPath accepts wildcards; Glob gives more flexible matching.
• Contract to design around: files only, never directories; criteria are limited to hidden, extension, path, glob. Anything richer is our code on top.
• Requires Flysystem 3. Confirm the PHP floor and Flysystem constraint in composer.json against our Laravel version before adoption — that compatibility check, not learning the API, is the real ramp-up cost (under a day either way).
• Integration standard: wrap in a single internal service class so the dependency is swappable, add one test that exercises Glob against a real disk, and benchmark once against your largest expected tree or any remote adapter before putting it on a hot path.