Filagora Logs Laravel Package

Getting Started

1. Install the package and run migrations:

   composer require <vendor>/mail-log
   php artisan migrate
   

2. Publish the config (if you need to change defaults) and set the new retention knob in config/mail-log.php or .env:

   MAIL_LOG_RETENTION_DAYS=60
   

   0 disables pruning entirely — logs are kept indefinitely.
3. Look first at the EmailLog model (forRecipient() is the canonical lookup) and the package config, then at the service provider registrations for privacy contributors if you use filagora-compliance.
4. First use case: send mail normally, then inspect rows:

   EmailLog::forRecipient('[email protected]')->latest()->first();
   

   From v0.2.2 you also get GDPR export/erase/prune for free when the compliance package is installed — no changes needed in your own logging code.

Implementation Patterns

• Daily log inspection: use EmailLog::forRecipient($address) for “what did we send this person?” support tickets, and standard Eloquent scopes/where clauses on subject, status, and timestamps for dashboards.
• Compliance wiring: EmailLogContributor is auto-registered with the host’s registries. Export/erase/prune flows go through the compliance package; your app doesn’t call the contributor directly. This keeps the mail-log package usable standalone while becoming GDPR-aware when filagora-compliance is present.
• Retention as configuration, not cron code: the logs.email_logs retention rule deletes rows older than mail_log_retention_days. Schedule the compliance prune command in routes/console.php/Kernel as you do for other retention rules; the mail-log package itself doesn’t need a scheduled command.
• Anonymisation ordering: the contributor reads the recipient address before the account is anonymised and matches rows the same way forRecipient() does. If you have custom anonymisation jobs, run them after the compliance erase/export step, or ensure the address is captured first, otherwise the contributor can’t find the rows.
• Multi-channel / multi-recipient mail: for to/cc/bcc fan-out, expect one row per recipient address (matching forRecipient() semantics); query per address rather than per message when handling erasure requests.
• Testing: assert on EmailLog::forRecipient(...) in feature tests, and freeze time to verify retention boundaries (retention_days - 1 kept, retention_days + 1 deleted). Set mail_log_retention_days=0 in test envs if you need logs to persist across long test suites.

Gotchas and Tips

• 0 means keep forever. It does not mean “delete immediately”. Use a large number or disable the rule explicitly if you want a hard stop.
• Default is 60 days — a silent behaviour change for anyone upgrading: logs older than 60 days will now be pruned once the compliance prune runs. Set the value explicitly before deploying.
• Nothing runs without filagora-compliance. The contributor and retention rule are inert otherwise; retention is not enforced by the mail-log package alone. Don’t rely on mail_log_retention_days as a data-protection guarantee unless the compliance package is installed and its prune is scheduled.
• Address must exist at erase time. Because the contributor resolves the address before anonymisation, custom flows that null out email first will orphan rows and break erasure. Treat anonymisation of the user record as a downstream step.
• Matching semantics are shared with forRecipient() — if you’ve customised that scope (case sensitivity, trimming, hashing), the contributor follows it. Any change there changes what gets exported/erased; review both together.
• Extension points: register additional contributors/retention rules through the core registries rather than editing the package; keep retention values in config/env so per-environment policies (e.g. longer retention in staging) don’t require code changes.
• Debugging: if export/erase misses rows, check (a) compliance package installed, (b) address captured before anonymisation, (c) forRecipient() matching (case/whitespace), and (d) whether the row was already pruned by the retention rule — pruning and erasure can race, and pruned rows are unrecoverable.