Console commands.

custom-fields:prune

php artisan custom-fields:prune

Deletes the values whose definition no longer exists, and nothing else.

Deleting a definition leaves its values behind, so that removing a field by mistake does not take the data with it. This command is the other half of that decision: the point at which the application says the removal was meant.

What it deletes

Orphaned is the whole test. A value row is deleted when no definition row holds its custom_field_definition_id, and left alone otherwise.

A value whose definition is still there is never touched, whatever tenant it belongs to and whether or not anything reads it. The command does not prune by age, by tenant, or by model, and takes no arguments to do so.

Checking first

Deleting is unrecoverable, so look before you run it:

php artisan custom-fields:prune --dry-run

Would prune 42 orphaned custom field values.

The dry run counts and touches nothing. Without the option:

Pruned 42 orphaned custom field values.

Both exit 0, including when there is nothing to do.

How it deletes

Rows go in chunks of 500, each pass reading the keys it is about to delete, so the matching set shrinks and the loop ends. Within a chunk, rows are deleted one at a time rather than in one statement, so each fires the value model's deleting and deleted events.

Those events are the package's whole observability surface. An application keeping a search index in step with them would otherwise see every delete the trait makes and none of the command's. See events and listeners.

Scheduling it

Never running it is a valid choice, which is why nothing schedules it for you. Values outliving their definition is documented behaviour, not a leak, and the rows are inert.

Schedule it if deleted fields are routine in your application and the rows add up:

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('custom-fields:prune')->weekly();

Do not schedule it while you are still deciding whether a field removal was a mistake. A weekly prune turns a reversible deletion into an unrecoverable one on whatever day it next runs.

What to read next

• Changing and deleting fields for what deleting a definition does and does not do.
• Events and listeners for the events prune fires.