Pug Minify Laravel Package

Getting Started

The 1.3.0 release adds relative path support, which is the first thing to look at if you have been working around absolute-path friction in earlier versions.

1. Update the dependency and review the changelog diff:

   composer require <vendor>/<package>:^1.3
   php artisan vendor:publish --tag=<package>-config   # if a config file ships with the package
   

2. Start in the package's config file and its path-resolution service (usually a facade, helper, or singleton bound in the service provider). That is where the "relative to what?" base is decided.
3. Clear caches after upgrading, since resolved paths are commonly cached:

   php artisan config:clear && php artisan cache:clear
   

4. First use case to try: replace a hard-coded absolute path in a config value or model attribute with a path relative to your configured base directory, then confirm it resolves identically in php artisan tinker, in a queued job, and in an HTTP request.

The migration path from older versions is usually mechanical: absolute paths keep working, so you can adopt relative paths incrementally rather than as a flag-day change.

Implementation Patterns

Configure the base once, resolve everywhere. Set the base directory (project root, a storage disk root, or a tenant directory) in config and keep it out of application code. Relative paths then become portable across local, CI, and production environments where absolute paths differ.

Store relative, resolve on read. A common pattern is persisting relative paths in the database (e.g. exports/2024/report.csv) and resolving them at the point of use. This survives deployments where the app root or storage mount changes, and it makes fixtures and seeders environment-agnostic.

Per-request or per-tenant bases. If your app serves multiple tenants, bind the base directory per request (middleware or a scoped container binding) so the same relative path resolves into the correct tenant tree. Verify the binding is reset between requests under Octane.

Pair with Laravel's filesystem layer. Where the package resolves relative paths into a disk, prefer Storage::disk(...)->path() for the disk root and let the package handle the remainder. This keeps you from reimplementing path joining and gives you Storage::fake() in tests.

Validation at the boundary. If relative paths arrive from users (upload destinations, configurable directories, CLI arguments), validate them with a rule that rejects absolute paths and parent traversal, then resolve. Catching this at the request layer is far cheaper than debugging it later.

Queue and command parity. Jobs and Artisan commands historically have different working directories. After adopting relative paths, run the same operation through a queue worker and a command to confirm both resolve against your configured base rather than the process CWD.

Gotchas and Tips

• "Relative to what?" is the whole feature. Relative paths are only safe if the base is explicit. Check whether the base derives from the config, the current working directory, or the calling file — CWD-based resolution is the most common source of "works in artisan, fails in the queue" bugs.
• Path traversal. ../../etc/passwd style inputs must be rejected or normalized and confined to the base directory. Confirm the release normalizes .. segments before the containment check, not after.
• Symlinks and realpath(). After resolving, canonicalize with realpath() before comparing against the base; otherwise a symlink inside the base can point outside it.
• Leading ./, duplicate separators, and trailing slashes. Normalize inputs defensively. Windows separators (\) are a frequent edge case if you accept user-supplied paths.
• Caching. If resolved paths are memoized, a long-running worker or Octane process will hold stale results after a tenant or config change. Look for a cache-bust or use request-scoped bindings.
• Config caching in production. php artisan config:cache freezes the base directory at build time. If your base is computed dynamically, it must not live in a cached config value.
• Tests. Use Storage::fake() and point the base at a temp directory per test. Assert both the happy path and the rejection of .. and absolute inputs — relative path support is a security-adjacent change, so regression tests here are worth the effort.
• Extension point. Most packages of this shape expose a path resolver contract you can rebind in a service provider. If your base logic is non-trivial, implement that contract rather than wrapping call sites.
• Rollout. Adopt relative paths in one subsystem first and keep absolute paths working. Given 1.3.0 is a minor release, the feature is additive; treat any behavior change in existing absolute-path handling as a bug to report rather than something to code around.