Relationship map

One file says which rows depend on which, and what happens to them when the row they point at is deleted. Our databases carry almost no real foreign keys, so this file is the referential integrity — the deleter, the checks and the map-driven joins all read it.

Where it lives and what reads it

The v2 shape

A map is written from the side that gets pointed at: each table lists who references it, under referenced_by. That is the direction a delete travels, so the danger sits next to the declaration. Each child table holds a list of edges, because one table can point at the same parent through two columns.

<?php

return [

    'version' => 2,

    'tables' => [

        'employees' => [
            'key'           => 'id',
            'referenced_by' => [

                // A document is part of the employee: without them it means nothing.
                'employee_documents' => [
                    ['foreign_key' => 'employee_id', 'rel_type' => 'own', 'on_delete' => 'cascade',
                     'has' => 'documents', 'belongs_to' => 'employee'],
                ],

                // A payslip records money that was paid. It outlives the employee.
                'payslips' => [
                    ['foreign_key' => 'employee_id', 'rel_type' => 'consume', 'on_delete' => 'restrict',
                     'has' => 'payslips', 'belongs_to' => 'employee'],
                ],

                // A department survives losing its manager; someone is appointed later.
                // Two edges from one table, so each needs its own `has` name.
                'departments' => [
                    ['foreign_key' => 'manager_id', 'rel_type' => 'consume', 'on_delete' => 'set_null',
                     'has' => 'managed_departments', 'belongs_to' => 'manager'],
                    ['foreign_key' => 'deputy_id',  'rel_type' => 'consume', 'on_delete' => 'set_null',
                     'has' => 'deputised_departments', 'belongs_to' => 'deputy'],
                ],

                // A link table: nothing but keys. It is `own` from BOTH ends.
                'project_members' => [
                    ['foreign_key' => 'employee_id', 'rel_type' => 'own', 'on_delete' => 'cascade',
                     'has' => 'memberships', 'belongs_to' => 'employee'],
                ],
            ],
        ],

        'projects' => [
            'referenced_by' => [
                'project_members' => [
                    ['foreign_key' => 'project_id', 'rel_type' => 'own', 'on_delete' => 'cascade',
                     'has' => 'members', 'belongs_to' => 'project'],
                ],
            ],
        ],
    ],
];

Per-table keys

Per-edge keys

role and inverse are older names for has and belongs_to and are still read. Cardinality is never declared: the table holding the foreign key is always the many side, and many-to-many is a link table owned from both ends. The reverse direction (what does a payslip point at?) is computed at load — never write both directions by hand.

on_delete — what happens

This is the only field the deleter acts on. It is your decision about the domain, and no tool fills it in for you.

An edge with no on_delete is undecided, and the deleter refuses any delete that reaches it. That is why the scaffold writes 'on_delete' => null, // DECIDE rather than leaving the key out: a missing key reads as "not applicable", an explicit null reads as "nobody has answered this yet".

Only cascade carries a delete further down. set_null and restrict stop it at that edge. If any restrict is hit anywhere in the tree, nothing at all is deleted.

rel_type — own or consume

rel_type answers one question about the child row:

It belongs to the edge, not the table. One row can be both: an assignment is own from its class (no class, no assignment) and consume from its teacher (a new teacher takes it over).

own is transitive — a part of a part is still a part. consume stops where it is found: if a payslip consumes an employee and the employee consumes a department, the payslip has nothing to do with the department when something is deleted.

When it comes into play

Its job is to make your on_delete checkable. On its own, any on_delete looks as plausible as any other. Paired with what the edge is, half the combinations contradict themselves, and the checker can say so. It comes into play in three places:

1. vsloquent:map --verify compares each edge's pair (the table below) and walks the graph for problems that reach several edges.
2. Delete previews attach warnings to a finished plan() — rows that also belong to a parent you are not deleting, settlement pointers about to be cleared. They are added to the plan from outside it, so they cannot change what gets deleted.
3. The scaffold, which marks a table that is nothing but keys as own, because a link table means nothing without either end. Everywhere else it leaves rel_type for you.

The pairs

A disagreement never says which half is wrong — the label may be careless and the on_delete exactly right. It says one of the two is wrong, and you decide which.

Checking the map

php artisan vsloquent:map                  # coverage numbers, then every finding
php artisan vsloquent:map --verify         # findings only
php artisan vsloquent:map --coverage       # headline numbers only
php artisan vsloquent:map --scaffold       # PHP for relationships nobody declared, judgement left UNSET
php artisan vsloquent:map --upgrade        # the v1 map rewritten as v2
php artisan vsloquent:map --verify --parent=employees --connection=pgsql

Findings come in two kinds. Blocking ones mean a delete that reaches that edge will fail. The others mean the delete will succeed — and you may not want it to.

Blocking — the deleter refuses

Warnings — the delete would succeed

A delete preview adds two more for the specific rows involved: co-owned ("12 project_members rows also belong to projects, which is not being deleted") and consume-nulled (pointers about to be cleared on rows that record something that happened).

Deleting through the map

use Vsd\Vsloquent\Support\CascadeDeleter;

// Dry run: ['delete' => …, 'nullify' => …, 'blocked' => …, 'missing' => …]
$plan = CascadeDeleter::plan('employees', $id);

// The real thing. One transaction; a `restrict` anywhere and nothing is deleted.
$affected = CascadeDeleter::delete('employees', $id);   // [table => rows affected]

plan() and delete() walk the same code, so a preview cannot disagree with what the delete does. If you already opened a transaction, delete() joins it. Pass a soft-delete column as the fourth argument and the whole cascade soft-deletes instead.

Other backends

Today the map and everything that reads it are PHP — vsd/vsloquent, in Laravel. Nothing in the idea depends on PHP. The map is plain data, and the rules above are graph logic over that data. A NestJS, plain Node or Python back end can take part in the same contract. None of those ports exists yet; a port has to keep these, or the backends will disagree about the same database:

• One map, read as data. The same tables, edges and keys as above, not a re-typed copy per language. Two copies drift, and both look plausible.
• The map wins over the ORM. Prisma, TypeORM and SQLAlchemy have their own onDelete, and SQLAlchemy's delete-orphan is close to own. None of them knows consume, the pairs or the warnings. Use the ORM for queries, not as the source of the delete rules.
• The same deleter behaviour: one transaction; a restrict at any depth refuses the whole delete; only cascade goes deeper; an undecided edge refuses; plan() and delete() share one walk.
• The same wall: the deleter never reads rel_type. Warnings are attached to a finished plan, never fed back into it.
• The same findings, with the same names, so a report from one stack reads the same as one from another.

This follows the rest of the framework: same contract, any stack, through twins of the PHP packages rather than a second set of rules. See Next.js & Node for the twins that exist today.