Plume Laravel Package

Getting Started

1. Install the package with Composer and publish its assets:

   composer require <vendor>/plume
   php artisan vendor:publish --provider="<Vendor>\Plume\PlumeServiceProvider"
   

   Assets land in public/vendor/plume; any config is exposed as config/plume.php.
2. Read the Installation docs page first — it is the canonical source for the publish tags, the config keys, and (as of v0.10.5) the recommended deploy sequence.
3. First practical use case: after any composer install / composer update that changes the package version, run:

   php artisan plume:update-assets
   

   This deletes the previously published files under public/vendor/plume and republishes the current ones, so stale content-hashed filenames stop accumulating.

Implementation Patterns

Deploy script (the intended workflow). The command is designed to be a single line in your release pipeline, immediately after dependency installation:

composer install --no-dev --optimize-autoloader
php artisan plume:update-assets
php artisan migrate --force
php artisan config:cache && php artisan route:cache && php artisan view:cache

Placing it after Composer and before your cache-warming steps means the freshly published manifest/hashed files are what get referenced once caches are rebuilt.

Composer hook for local development. If you don't want to remember the command, wire it into composer.json — but scope it to updates of this package so it doesn't run on every unrelated dependency bump:

"scripts": {
    "post-update-cmd": [
        "@php artisan plume:update-assets --ansi"
    ]
}

Version-gated invocation. The command only exists from v0.10.5 onward. If staging/production may run older versions during a rolling deploy, guard it so a missing command doesn't fail the build:

php artisan list plume | grep -q plume:update-assets \
  && php artisan plume:update-assets \
  || echo "plume:update-assets not available, skipping"

Container/immutable-image builds. If your runtime filesystem is read-only or rebuilt from an image, run plume:update-assets at image build time (after composer install), not at container start — the command writes to public/vendor/plume.

Pair it with a cache purge. Republishing assets produces new hashed filenames; if you front the app with a CDN or aggressive reverse proxy, purge or invalidate the affected paths as a follow-up step so clients pick up the new references.

Gotchas and Tips

• Never hand-edit files in public/vendor/plume. The command recursively removes the directory before republishing, so any local hotfix, custom CSS, or override placed there will be silently destroyed. Put overrides in resources/ and publish-to-a-different-path, or document them explicitly.
• Run it as the correct user. Publishing creates files owned by whoever invokes Artisan. Running the deploy as root or as a CI user while the web server reads as www-data can produce permission errors or unreadable assets later. Use sudo -u www-data or fix ownership/permissions after the step.
• Ordering matters relative to artisan optimize. Run the command before config:cache/view:cache so any cached references point at the newly published files. If you cache first, clear and re-warm afterwards.
• Stale assets are the whole reason this exists. The classic symptom of skipping it is 404s on hashed asset URLs after upgrading, or two generations of files building up in public/vendor/plume. If users report missing styles/scripts right after a release, this is the first thing to check.
• Browser and CDN caching still applies. Deleting and republishing server-side does not invalidate clients. Hashed filenames handle this if your templates reference the manifest; hardcoded paths will not be cache-busted.
• Keep public/vendor/plume out of version control. It's generated output. If it is committed today, add it to .gitignore and let the command own the directory — otherwise merges will reintroduce the stale files the command just cleaned up.
• Debugging: if the command reports success but the site still serves old assets, confirm the web root actually resolves to the public/ directory you're writing to (symlinked current/ releases are a common culprit), and check for an opcache or realpath cache holding onto deleted paths.