Nova Mailman Laravel Package

Getting Started

1. Upgrade and re-publish assets. This release splits the Vue tool into separate components and recompiles the SCSS, so previously published assets will be stale:

   composer update vendor/package
   php artisan vendor:publish --tag=package-assets --force
   php artisan config:clear && php artisan route:clear
   

2. Look here first:
   • The package config file (config/...php) — for the enabled/middleware/gate keys and the storage driver.
   • php artisan route:list | grep mail — confirm the new destroy route is registered and see exactly which middleware protects it.
   • The migration/table (or filesystem path) backing the mail list, so you know what deletion actually removes.
3. First use case: in local, send a throwaway mail and confirm the full loop works end to end:

   Mail::raw('hello', fn ($m) => $m->to('[email protected]')->subject('smoke test'));
   

   Open the tool, verify the mail renders, check the new YYYY-MM-DD HH:MM:SS timestamp column, then use the new remove action and confirm the row disappears and the list refreshes without a page reload.

Implementation Patterns

• Gate the tool per environment. Register the service provider only outside production, or set the package's enabled flag from an env var. The new destroy route makes this non-optional — a mail viewer is now a mail deleter.
• Authorize deletion explicitly. Don't rely on the package's default middleware. Add your own guard in the config (gate/ability or auth + role middleware) so the destroy endpoint isn't reachable by every authenticated user:

  'middleware' => ['web', 'auth', 'can:viewMailTool'],
  

• Use the destroy route as a pruning primitive. Beyond the UI button, you can hit the endpoint (or the underlying model/repository) from a scheduled command to expire old mails:

  // app/Console/Commands/PruneMails.php
  // iterate stale records and delete via the package's model/route
  

  This is the cleanest way to keep the store from growing unbounded in staging.
• Test the delete path, not just the view. In feature tests, assert the record is gone rather than asserting a redirect:

  $this->delete(route('mail.destroy', $mail))->assertSuccessful();
  $this->assertDatabaseMissing('mails', ['id' => $mail->id]);
  

• Treat the timestamp as display-only. With the format now fixed at YYYY-MM-DD HH:MM:SS, sort/filter server-side (or on the raw model attribute) rather than parsing the rendered string.
• Keep local overrides minimal. Components are now split, so if you've published and edited views, diff your overrides against the new published set after every upgrade rather than re-publishing blind.

Gotchas and Tips

• Deletion is destructive and possibly incomplete. Verify whether removing a mail also removes attachments/storage files or only the database row. If it's row-only, add a cleanup listener or scheduled sweep for orphaned files.
• Stale assets after upgrade. The SCSS fix means the previous 500 error on the tool's index was a compiled-CSS problem. If you applied a local workaround (custom stylesheet, disabled asset publishing, manual npm run build), remove it — otherwise you'll be layering a fix on top of a fix and re-introducing the 500.
• config:cache in deployed environments. If config is cached, the new route and any changed middleware won't take effect until php artisan config:cache is re-run as part of your deploy.
• Timestamp format change is a visible behavior change. Any test asserting relative times ("2 minutes ago"), any snapshot test of the index view, or any front-end code that parsed the old string will break. Grep for the old format before deploying.
• Timezone surprises. The fixed format drops relative-time context, so a mail shown as 2024-05-01 09:00:00 is in whatever timezone the app renders in — confirm app.timezone matches what your team expects, otherwise debugging "when was this sent?" gets harder, not easier.
• Component split breaks published-view overrides. If you customized the monolithic Vue tool, your override is now orphaned. Check the published views/assets path after upgrading and confirm the UI actually loads the new components.
• New sidebar icon is cosmetic — but it signals the nav/registration markup changed. If you injected links into the tool's sidebar, re-verify placement.
• Debugging a 500 on the tool: in order — config:clear, re-publish assets with --force, check storage/logs/laravel.log for a missing compiled CSS/JS manifest, then confirm the destroy route is present in route:list.