Volet Laravel Package

Getting Started

Volet is a drop-in translation manager for Laravel: it gives you a UI (and supporting backend) for browsing and editing your app's translation strings instead of hand-editing lang/**/*.php. v2.2.3 is a patch release — dependency bumps plus a rebuilt frontend bundle (the jQuery/terser conflict fix) — so nothing in the install flow changes.

1. composer require mydnic/volet
2. Publish what the service provider exposes: php artisan vendor:publish --provider="Mydnic\Volet\VoletServiceProvider" (use --tag= variants for config, assets, migrations if you only want one).
3. Open config/volet.php first — that's the source of truth for the route prefix, middleware stack, and where translations are read from/written to.
4. If the package ships migrations, run php artisan migrate.
5. Visit the configured route (typically /volet) in your browser and confirm the UI loads — if you get a blank page or 404 on the compiled asset, the assets weren't published (see Gotchas).

First use case: open the UI in your local environment, pick a locale you already have files for, and edit one string. Save it, then hit the page that renders that key. This single loop tells you three things at once: where Volet persists translations (files vs DB), whether your cache is being invalidated on save, and whether the middleware you configured actually protects the route.

Where to look next, in order: config/volet.php → the published views (if you published them) → the package's route registration in the service provider. Those three cover 90% of "why isn't this behaving" questions.

Implementation Patterns

Gate it to non-production by default. The most common setup is to expose Volet only where it's safe:

// config/volet.php
'middleware' => ['web', 'auth'],  // or a dedicated Gate

Better: register an enabled / environment check so the routes aren't even registered in production, or protect with a Gate::define('manage-translations', ...) bound to an admin role. Translation editing is a write surface — treat it like any admin panel.

Keep files as the source of truth, DB as an override, or pick one. Decide early whether Volet writes back into lang/ files or into a table. File-based means changes are diffable and ship with deploys, but concurrent edits collide and you can't edit in a read-only filesystem (e.g. some container setups). DB-based means runtime edits without a deploy, but you now own backup, seeding, and cache invalidation. Most teams use Volet as an editing surface in local/staging and commit the resulting file changes through PRs.

Seed/import before you edit. Point Volet at your existing lang/ directory and let it enumerate keys first, so the UI shows missing-vs-present strings per locale rather than starting empty. That missing-key view is the highest-value thing in the package day-to-day — it turns "the French translation is stale" into a checklist.

Cache discipline. If translations are cached (Laravel's trans cache or a package-level cache), wire the save action to forget the relevant cache keys, and add a deploy step that clears it. A stale translation cache is the #1 "I saved it but the site still shows the old string" cause.

Localize your workflow: one developer owns merges to lang/, everyone else edits in the Volet UI against a feature branch. This avoids the classic three-way conflict inside a 900-line messages.php.

Upgrading: composer update mydnic/volet then re-publish assets and clear compiled views. v2.2.3 specifically ships a rebuilt JS bundle, so an upgrade without republishing assets leaves you running the old bundle.

Gotchas and Tips

• v2.2.3 rebuilt frontend assets. The "Fix jquery conflict with terser" change alters the compiled bundle, not PHP. If you published assets, force-republish (--force) and run php artisan view:clear. If you serve assets from the package's vendor/ path, just hard-refresh the browser — the filename may not be hashed, so browser cache will happily serve the broken old bundle.
• Config is cached. After touching config/volet.php, run php artisan config:clear (or config:cache in deploy). A surprising number of "middleware change did nothing" reports are stale config cache.
• Blank UI / 404 on JS. Usually unpublished assets, a public/vendor/... path that isn't writable in your container, or an APP_URL/asset-url mismatch behind a proxy. Check the network tab before suspecting the package.
• Route collision. If your app already uses the configured prefix, change it in config rather than patching routes.
• Don't let it run in production unprotected. Even if you gate it, add the environment guard — a middleware config mistake shouldn't equal public write access to your copy.
• File permissions / read-only filesystems. File-backed writes will fail silently or partially on read-only deploys (e.g. some serverless setups). Test the save path in the environment closest to production, not just locally.
• Diff noise. File-backed saves may rewrite whole files (formatting, ordering, declare(strict_types=1), return type hints). Run your formatter (Pint) after a bulk edit session before committing, or your PR will be unreadable.
• Extension points: publish and override the package views for branding, override the route middleware in config, and wrap the whole thing in your own route group if you need a different guard. If you need custom persistence, that's the point to fork rather than fight the config.
• Version drift: this release's CI bumped laravel/framework to 13.x and refreshed Symfony/Guzzle internals. If you're pinned to an older Laravel, check the package's composer.json constraints before assuming the bump is free — dependency-only releases can still move your resolved lockfile.
• No breaking changes here. v2.2.3 is safe to take on a patch upgrade; there's nothing to migrate and no API deprecations to plan around.