Laravel Prunable Fields Laravel Package

Getting Started

• Install with composer require maize-tech/laravel-prunable-fields. On Laravel 11, require ^1.3 (1.3.0 adds Laravel 11 compatibility; no other changes are listed).
• Start with the package trait on a single model, e.g. use Maize\PrunableFields\Concerns\PrunableFields;.
• Declare the fields that may be cleared and the retention window in the model using the package’s field declaration hook (typically a prunableFields()-style method returning field names or field => interval pairs). Check the README for the exact signature in your installed version.
• Schedule the pruning command daily in app/Console/Kernel.php or routes/console.php (Laravel 11), or run it manually once to confirm behavior.
• First useful case: GDPR/data-minimisation cleanup. Keep the order/user record but null out email, phone, or fiscal_code after the retention period instead of deleting the entire row.

Implementation Patterns

• Field-level pruning, not row deletion. Use this package when the record must remain for reporting/history but sensitive columns should age out. Pair it with Laravel’s native MassPrunable only when whole records should be deleted.
• Model-level declarations. Keep the prunable-field list beside the model so retention rules are versioned with the schema. Add explicit comments for why each field is pruned and the legal/business retention period.
• Per-field windows. If the package supports field => interval maps, use different windows per field (e.g. email after 30 days, phone after 90). Otherwise split models or use multiple scheduled commands.
• Chunked execution. For large tables, confirm the command uses chunking or add a narrowed query/scope. Index the timestamp column used to decide eligibility (created_at or updated_at).
• Scheduling. Run daily during low traffic. Log the number of rows and fields affected; a no-op run should be visible in logs so you can detect misconfiguration.
• Testing. Use Carbon::setTestNow() / travel() to freeze time, create records just inside and outside the retention window, run the command, and assert that only eligible fields were nulled. Also assert that non-prunable fields and the row itself still exist.
• Anonymisation strategy. Decide whether “pruned” means NULL, an empty string, or a redacted placeholder. If downstream code assumes non-null values, prefer a placeholder or update consumers first.
• Multi-tenant apps. If pruning must be tenant-scoped, wrap the package command in your own command that iterates tenants, or use a global scope carefully—mass updates can bypass scopes if not applied consistently.

Gotchas and Tips

• Irreversible by design. Pruning fields destroys data. Take a backup or write an audit record before enabling in production, and run once with a dry-run/log-only mode if the package supports it.
• Mass updates bypass model events. Field pruning is likely implemented as a query update, so updating/updated observers will not fire. If you depend on events to sync search indexes or audit logs, trigger that work explicitly after pruning.
• Nullable columns are required. Pruning a non-nullable column will fail or write an empty value depending on the driver. Audit the schema before adding a field to the prunable list.
• Unique indexes and NULL. Nulling a unique column may be fine in MySQL/PostgreSQL (multiple NULLs allowed) but not in SQL Server. Check driver-specific behavior.
• Timestamp choice is critical. Prune based on the date that reflects the retention rule (e.g. created_at, not updated_at, if a later edit should not extend retention). Be explicit in the model declaration and tests.
• Timezone consistency. Compare dates in the app timezone and ensure the database stores timestamps consistently. Off-by-one-day behaviour around midnight is a common source of “why wasn’t this pruned?” bugs.
• Laravel 11 upgrade. 1.3.0 is a compatibility release only. There are no listed breaking changes, but on Laravel 11 ensure PHP 8.2+ and run the full test suite after upgrading. If you are still on Laravel 10, earlier versions remain valid; pin ^1.3 only if you need Laravel 11.
• Config caching. If you publish a config file, run php artisan config:cache in deployment and clear it during debugging. Config changes will not take effect until the cache is rebuilt.
• Command discovery. In Laravel 11, scheduled commands are often registered in routes/console.php rather than Kernel.php. Confirm the package command is registered and visible via php artisan list before scheduling it.