Download the PHP package kaveraa/data-lifecycle without Composer

Data Lifecycle

English - Français

The GDPR asks you not to keep personal data longer than needed (article 5.1.e). In real life almost nobody does it: you would have to find the idle accounts, warn the people, disable without breaking anything, leave a way back, then anonymise or delete. And be able to show it.

This package does that journey, with one declaration per entity, for Laravel and for Symfony / Doctrine.

• The whole journey: warn, disable, leave a grace period, then anonymise or delete. Not only delete.
• Observe mode: lifecycle:report says exactly how many rows would be touched, and which ones, without a single write. This is what you run in production for weeks before daring the rest.
• Reversible: while the grace period lasts, a person who comes back finds the account untouched, and the clock restarts.
• No schema is forced: a policy only reads the columns it needs. A simple policy works with a single date column.
• Two frameworks, one package: the cycle is written once, in plain PHP; Laravel and Doctrine are only drivers.
• Testable: the clock can be replaced (FrozenClock), so three years pass in three lines of test.
• Light: two PSR interfaces, nothing else.

Table of contents

• The problem
• Requirements
• Installation
• Write a policy
• The columns to add
• Run the cycle
• Observe mode
• Warn the person
• When the person comes back
• Anonymise
• The activity signal
• Where a row stands
• All the options
• What this package does not do
• Development

The problem

A database keeps everything, forever, by default. Accounts left behind six years ago are still there, with their address, their name, their history. It is a risk if data leaks, and it goes against the GDPR.

The usual answer is a home-made script, run once, that deletes in bulk. It is frightening, so nobody runs it. This package replaces that script with something you dare to run:

Requirements

• PHP 8.2 or more.
• Laravel 12+, or Symfony 7.2+ with Doctrine ORM 3+.
• One date column per entity: the last sign of life (last_active_at, last_order_at, sent_at, your choice).

Installation

Laravel

The command publishes config/data-lifecycle.php and an example migration. The service provider is found on its own.

Symfony

Add the bundle in config/bundles.php:

Then write config/packages/data_lifecycle.yaml:

Write a policy

Two ways, as you like. Attributes read better, configuration is handier when the rule changes with the environment. If both exist for the same class, configuration wins.

With attributes

An entity can have only a start and an end:

Then say where to look for these classes, in discover:

With configuration

Durations are written in plain words: 3 years, 18 months, 30 days, 48 hours. The ISO 8601 form (P30D) works too.

The columns to add

You only add the columns your policy needs.

So a #[KeepFor] + #[ThenDelete] policy needs only the date column. The names can be changed, globally or policy by policy:

Add an index on the date column, and on disabled_at: they carry the queries.

Run the cycle

With Symfony the same commands are bin/console lifecycle:run and bin/console lifecycle:report.

Once a day is enough. Laravel:

Symfony, with cron:

A run is made to be stopped and resumed: --limit bounds every step, and the next run carries on where it stopped.

The first run

On a database that was never cleaned, the whole backlog comes out at once: thousands of rows are already past the deadline. They get their first reminder, then are disabled in the same run, which leaves nobody time to react. Two precautions:

1. Run lifecycle:report first, and look at the numbers.
2. Catch up gently: play --step=warn alone for the length of your reminder (30 days if you warn 30 days before), and only then the full command.

Observe mode

This is the front door of the package. Nothing is written, no event is sent, and the report says what would happen:

A row that is very late can show up twice, in warn and in disable: in observe mode nothing is written between the two steps, so the report shows exactly what a real run would do, one step after the other.

Let it run for a few weeks in a scheduled task, watch the numbers settle, then remove --dry-run. Writing can also be blocked from the configuration while you set things up:

As long as this setting is true, lifecycle:run stays in observe mode and says so.

Warn the person

The package sends no email: it tells you when to send one, and you write the message. There are five events, listened to like any event of your framework.

No event is sent in observe mode.

When the person comes back

This is the whole point of the grace period: disabling is not deleting.

reactivate() returns false on a row that is already anonymised: what is gone does not come back.

Anonymise

Anonymising instead of deleting keeps your counts right (orders, statistics, invoices) while the person disappears.

Every field gets a strategy. Without one, Strategy::Auto chooses from the name: a field that contains mail gets an address, everything else gets [removed].

Strategy::Hash helps when you need to know that two rows came from the same person, without knowing who. The replacement texts can be changed in the configuration.

The activity signal

Everything rests on a date you can trust. Writing last_active_at on every request costs one write per request: not acceptable. The package ships a guard that writes only once per window (15 minutes by default).

Laravel, in bootstrap/app.php:

With Symfony the listener is wired by the bundle. The window is set with activity.throttle (in minutes; 0 turns it off).

Watch out for the trap: an automatic login from a cookie, a monitoring call or a scheduled task that touches the table will reset the clock. An account that looks active because a robot goes through it is not active. Pick a deliberate action of the person as the starting point.

Where a row stands

With Laravel, the HasLifecycle trait puts the same answers on the model, plus scopes:

All the options

What this package does not do

• This is not legal advice. The durations are yours: they depend on your activity and your duties (an invoice is kept ten years, a rejected job application two years). The package applies the duration you decide.
• It does not hold your record of processing activities and does not answer access or portability requests.
• It does not touch your backups or your logs: a row anonymised in the database is still readable in yesterday's backup. Think about how long you keep your backups.
• It does not guess your relations: anonymising a user does not empty the linked tables. Write one policy per entity, or clean up in a listener of SubjectAnonymised.

Development

To suggest a change, read the CONTRIBUTING.md guide. See the CHANGELOG for the history of versions.

To report a vulnerability, open a private security advisory rather than a public issue.

License

MIT. See LICENSE.