Filer Bundle Laravel Package

Getting Started

Start by confirming which version you actually have installed — v1.0.4 changed how the package finds its definition files, so the first step is to know whether you are on the XML-based loader or the PHP file locator:

composer show <vendor>/<package>
php artisan about          # config/cache status matters more than usual here

Then:

1. Publish and read the config. php artisan vendor:publish --tag=<package>-config, then open config/<package>.php. This is where the locator's search paths now live. In the XML era, discovery was driven by a manifest; with v1.0.4 the paths in this file are the source of truth.
2. Inventory your existing XML. If you upgrading from ≤1.0.3, find every *.xml file you (or the package) relied on:

   find . -path ./vendor -prune -o -name '*.xml' -print
   

   Anything the package used to read must now exist as an equivalent PHP file inside a locator path.
3. Clear and re-resolve. php artisan config:clear && php artisan cache:clear && composer dump-autoload. Stale cached manifests are the single most common cause of "the release changed nothing" reports.
4. First real use case: put one trivial PHP definition file in the configured path, run the package's discovery/compile command (check php artisan list for the vendor-prefixed command), and confirm the resolved list includes your file. Once that works, migrate the rest in batches.

If you are starting fresh on v1.0.4 you can skip step 2 entirely — there is no XML to port.

Implementation Patterns

Declare paths explicitly, don't rely on convention. The locator will scan configured directories, but production behaviour should never depend on "it happened to find it under app/". List each root in the config file, and keep the list short and ordered. If the locator supports priority or namespacing, use it: deterministic resolution beats a recursive glob that silently picks up a stray file in a test fixture.

Treat the resolved file list as a build artifact. Resolve it during deploy, not during the request:

# deploy script
composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan <package>:compile   # or whatever the discovery command is named
php artisan view:cache

Warming the list at deploy time turns a filesystem walk plus include of N files into a single cache read. If the package does not ship a compile command, resolve once into a bootstrap/container singleton or a Repository-style class and inject that.

Wrap the locator, don't call it from everywhere. Bind a thin resolver in a service provider and depend on that:

$this->app->singleton(DefinitionResolver::class, fn ($app) => new DefinitionResolver(
    $app->make(FileLocator::class),
    $app['config']->get('<package>.paths'),
));

This is your extension point when the locator's behaviour changes again (it just did, once) and your seam for tests.

Testing. Point the config at a temporary fixture directory per test and re-resolve; do not share a single global path list across the suite. If the package exposes a fake or in-memory locator, prefer it over touching the real filesystem. Always assert on the resolved set, not on the presence of files on disk.

Package/extension development. If you ship your own definitions, register your path from your own service provider's register() (not boot()), so it is available before anything else resolves the list. Guard against double registration when the provider is loaded twice in feature tests.

Gotchas and Tips

• The cache is the bug 90% of the time. Upgrading 1.0.3 → 1.0.4 with a warm cache means the old XML-derived manifest may still be read, or a now-missing file path may still be referenced. Always config:clear + cache:clear after the update, and add cache clearing to your deploy script between composer install and config:cache.
• Leftover XML fails silently. The new loader ignores *.xml rather than erroring. That is convenient for a staged migration but dangerous: you can ship with half your definitions simply not loaded. Verify by diffing the resolved definition count before and after the upgrade.
• Filesystem ordering is not guaranteed. Directory scans on ext4, APFS and in Docker overlayfs return different orders. If two definitions target the same key, last-one-wins behaviour will differ between your laptop and CI. Give every definition an explicit name/priority and fail loudly on duplicate keys.
• Symlinks. public/storage, monorepo vendor paths and path repository symlinks are frequently not followed by PHP file locators (RecursiveDirectoryIterator needs FOLLOW_SYMLINKS). If definitions live behind a symlink, point the config at the real path.
• Case sensitivity and separators. A file that resolves on macOS (Foo.php vs foo.php) will not on Linux. Also watch Windows-style \ separators — normalise paths with DIRECTORY_SEPARATOR-agnostic handling before comparing cached keys, otherwise you invalidate the cache on every platform switch.
• opcache and realpath_cache. Long-running workers (Octane, queue workers, Swoole) will not see files added after boot. Restart workers on deploy; do not rely on the locator re-scanning per request.
• Permission errors look like "not found". A locator that swallows UnexpectedValueException from unreadable directories will report zero files rather than an error. When debugging, var_dump the resolved root list and is_readable() each one before blaming the package.
• Debugging recipe: log the resolved absolute file list at boot in non-production, then diff it against git ls-files for the expected paths. Almost every "my definition isn't loading" report resolves to a path typo, a symlink, or a stale cache rather than a loader bug.
• Public API surface. v1.0.4 is a loader swap, not a feature release. Treat anything that let you reach into the XML layer (custom parsers, schema validators, XPath-based overrides) as removed. Grep your app for XML parsing, DOMDocument, SimpleXML, and package-specific parser classes before you merge the bump.