Php Lib Laravel Package

Getting Started

• composer require spotlibs/php-lib:^1.8 (or pin 1.8.2 exactly — see Gotchas). The package targets Laravel/PHP; if it ships a service provider, package discovery registers it automatically, so check composer.json → extra.laravel.providers before manually adding anything to config/app.php.
• Look first at the repo, not the changelog. The release notes for v1.8.2 are a single line (fix : revert to old allFiles), so the only reliable source of truth is src/ (the class exposing allFiles), the tests/ directory (each test there documents intended behaviour better than the README), and the diff of v1.8.1...v1.8.2. Read the diff before you read the docs.
• Check for a publishable config (php artisan vendor:publish --provider="Spotlibs\...ServiceProvider") and any migrations the package ships. For a file-oriented library, storage disk names and path conventions are the two things you most often need to override.
• First use case: a file/media collection. Instantiate the class that owns allFiles (or resolve it from the container), point it at a model/storage disk, and call allFiles() to get the full set. Assert the result shape in a test immediately — per the changelog, that method's semantics are the part that just changed.
• Sanity check the install with a throwaway tinker session before wiring it into application code:

  $files = app(YourFileOwner::class)->allFiles();
  dump(get_class($files), $files->count(), $files->first());
  

Implementation Patterns

• Wrap it, don't scatter it. Because this package has already shipped a behavioural revert in a patch release, treat it as a third-party boundary. Put a thin adapter (e.g. App\Support\FileCollection) around allFiles() so a future revert or rename touches one file:

  class FileCollection
  {
      public function __construct(private YourFileOwner $owner) {}
  
      public function all(): Collection
      {
          return collect($this->owner->allFiles())->values();
      }
  }
  

• Normalise at the boundary. Whatever allFiles() returns (array, Collection, SplFileInfo[], path strings), convert to a stable, typed representation once and pass only that downstream. Ordering and keying are exactly the kind of detail that shifts between patch releases.
• Bind through the container. Register your adapter in a service provider ($this->app->bind(FileCollection::class, ...)) rather than new-ing it up. This gives you a single seam to swap behaviour in tests and to feature-flag the v1.8.1 vs v1.8.2 semantics if you need to compare.
• Version-gate the upgrade. For an app already on 1.8.1, upgrade in an isolated branch: composer require spotlibs/php-lib:1.8.2 --with-dependencies, then run the tests that touch file listing. Keep composer.lock committed; a revert is invisible in a diff review but very visible at runtime.
• Integration tip — Laravel storage. If the package reads from a disk, keep disk names in config (config/filesystems.php) and never hardcode storage_path() paths in call sites. That way test suites can point at a Storage::fake() disk and exercise the real allFiles() code path.
• Integration tip — queues. File enumeration over large trees belongs in a job, not a request. Return counts/IDs from the job and hydrate on demand — this also insulates you from ordering changes in the collection.
• Test pattern. Pin the contract with a fixture-based assertion rather than asserting on count alone: create nested dirs plus a couple of dotfiles, then assert the exact expected set. That's the test that would have caught this revert.

Gotchas and Tips

• A patch release just changed behaviour. v1.8.2 reverts allFiles to the old implementation. Anyone who adapted to v1.8.1's output — different ordering, filtering of hidden/nested files, or a changed return type — will silently regress. Semver alone will not protect you here; treat ^1.8 as optimistic and prefer an exact pin with a deliberate bump.
• Read the diff, not the title. The changelog says "fix", which implies v1.8.1 was considered wrong, but the diff tells you what the old behaviour was. git diff v1.8.1 v1.8.2 -- src/ is a 30-second job that saves an incident. Note the discrepancy between the changelog wording and the branch/PR numbering (#70) — verify the tag actually contains the commit you think it does (composer show spotlibs/php-lib).
• No deprecation notice was issued. Because this is a silent revert rather than a deprecation, there is no E_USER_DEPRECATED or upgrade guide to catch you. Your only signal is your own test suite — so make sure one exists before upgrading.
• Debugging a mismatch. When output looks wrong, dump the resolved class path ((new ReflectionClass($owner))->getFileName()) to confirm which vendor version Composer actually loaded — stale vendor/ or an opcache/composer dump-autoload lag is a common false alarm. Then composer why spotlibs/php-lib to check no transitive dependency is pulling a conflicting constraint.
• Extension points, in order of preference: config override → your own adapter/decorator → subclassing the package class → forking. Avoid the last two. If the package exposes macros or custom collection methods, register them in a dedicated service provider so they don't leak into unrelated collections.
• Watch for another revert. Two releases in a row have now flip-flopped allFiles. Until the maintainer stabilises it, keep your pinned version under review and add a CHANGELOG-watching note (or a Dependabot rule that opens a PR rather than auto-merging patch bumps for this package specifically).