Laravel Migration Paths Laravel Package

Getting Started

• Install with composer require as usual, then publish the config if the package ships one (php artisan vendor:publish --tag=...). The config file is the first place to look: it defines the base roots the resolver is allowed to work from.
• The release note for 1.2.0 is the key context: the package now supports paths outside the Laravel application directory. Prior to this, base_path()-relative resolution was effectively the boundary. If you previously hit errors resolving a sibling directory, a monorepo package, or a shared assets folder, upgrade and retest that case first.
• The first practical use case is resolving a directory that lives next to, not inside, your app — for example a shared assets/, a monorepo packages/ directory, or a mounted volume in a container. Configure that root once, then ask the package for subpaths rather than concatenating ../ yourself.
• Confirm behaviour early in php artisan tinker by resolving a known external directory and comparing it to realpath() output. This tells you whether the resolver returns canonical paths, preserves symlinks, or returns a normalized-but-not-canonical path.

Implementation Patterns

• Named roots in config, resolution in code. Define external locations (shared storage, monorepo siblings, mounted volumes) as named roots in the package config. Application code should ask for a name plus a relative subpath, not embed absolute paths or ../../ traversals.
• Config-driven environments. Because paths outside the app differ between local, CI, and production, keep the root definitions in environment-specific config (config/...php reading env()), and let the package handle joining and normalization.
• Service provider / container usage. If the package binds a resolver into the container, inject it rather than using the facade in classes you want to unit test. Resolve and cache the base path once per request if you call it in a loop.
• Filesystem integration. Use the resolved path when configuring local disks in config/filesystems.php, when generating storage links, or when pointing at externally published assets. This is the common integration seam.
• Blade and asset publishing. Resolve external directories at render or publish time via a small helper/view composer rather than in templates directly; it keeps the resolution logic testable and avoids repeated filesystem calls.
• Testing. Write tests that resolve into a temp directory outside the application root — that is precisely the case 1.2.0 unlocks. Assert on both the resolved path and the failure mode for a non-existent directory, so you know whether the resolver throws or silently returns a path.
• Migration from workarounds. If you had been doing dirname(base_path()) . '/shared' or manual realpath() juggling to escape the app root, replace it with the package's resolver now that 1.2.0 fixes it. This is a bug-fix/minor release, so no code changes should be needed beyond deleting those workarounds.

Gotchas and Tips

• Trailing slashes and .. segments. Normalization rules for foo/../bar, duplicate separators, and trailing slashes may not match realpath(). Don't compare resolved strings to hand-built paths in tests; compare canonicalized forms.
• Symlinks. If the resolver canonicalizes, a path through a symlinked directory will come back as its target. That matters for deployment layouts that symlink releases (Envoyer/Deployer style) — verify the resolved path is the one you expect in the current release directory.
• Non-existent directories. Many resolvers only canonicalize existing paths. If the fixed behaviour depends on the directory existing, create it before resolving, or accept the non-canonical result. Test both.
• Permissions and PHP restrictions. Directories outside the app often sit outside the web user's expected tree. Check ownership and open_basedir/disable_functions settings; a resolution fix does not grant read access.
• Config caching. After adding or changing an external root, run php artisan config:clear (and remember config:cache in deploy scripts). A stale cache will make the new root appear unsupported and look like a regression.
• Deployment parity. The external path must exist in every environment. Guard with an existence check and a clear exception message rather than letting a null/null-ish path propagate into Storage or file_get_contents.
• Debugging. Dump the raw input and the resolved output side by side, and compare against realpath($input). If they diverge, the issue is normalization or existence, not the package's root handling.
• Extension points. If resolution still misbehaves for an unusual layout, look for a custom resolver binding or a macroable facade before forking — swapping the resolver implementation is usually cleaner than patching vendor code, and it survives upgrades.
• Upgrade note. Treat 1.2.0 as a safe upgrade: it is a bug fix for directory resolution outside the app. Pin the version if you have tests asserting on the previously broken behaviour, since those assertions will now fail for the right reason.