phil / references-bundle

0.1.0-alpha 2026-11-11 06:11 UTC

Requires

• php: >=8.5
• doctrine/dbal: ^4.5
• doctrine/orm: ^3.7
• phil/resource: ^0.1@dev
• symfony/config: ^8.2
• symfony/dependency-injection: ^8.2

Requires (Dev)

• doctrine/doctrine-bundle: ^3.3
• doctrine/persistence: ^4.1
• phpunit/phpunit: ^13.4
• psr/log: ^3.0
• symfony/console: ^8.2
• symfony/event-dispatcher: ^8.2
• symfony/framework-bundle: ^8.2
• symfony/http-kernel: ^8.2

Suggests

• symfony/console: For phil:references:check

MIT

• Philippe Gamache

• references
• symfony-bundle
• usages
• where-used

Published on Packagist.org on 2026-11-11 13:33 UTC

README

Know where each resource is used, and refuse to delete one that something still needs.

phil/references-bundle tells a Symfony application where its resources are used. A ReferenceCollector the application writes finds the links of one kind of source, such as an image in a page's JSON blocks or a polymorphic association. The bundle keeps these links in a table, up to date at each Doctrine flush. Deleting a resource still used rolls the flush back with a StillReferenced that names the sources using it. phil:references:check lists the links to resources that are gone, and fails while there is one.

It covers the links a foreign key cannot hold: a reference inside a JSON column, or a kind and an identifier side by side. It is for an application whose editors build pages out of blocks and media, and need to see where an image appears before they remove it. Calling References::assertUnused() before a deletion gives the person a clear message; the flush listener is the safety net behind it.

The bundle stores its table through Doctrine DBAL and listens to Doctrine ORM flushes. Resources are named through phil/resource, so sources and targets of any kind share one table. The design rests on two ports the application fills: collectors say what a source links to, and a ReferenceTarget says whether a resource of its kind still exists. A kind without a target is never refused a deletion nor checked for broken links.

Status

Part	State
Usage, the repository port; ResourceReference of phil/resource	Implemented and tested
References: refresh, forget, usages, deletion check, broken links; ReferenceCollector, ReferenceTarget, Link	Implemented and tested
DbalUsageRepository, its table and schema listener	Implemented and tested
ReferenceTrackingListener: usages at each flush, deletion refused	Implemented and tested
phil:references:check	Implemented and tested

Documentation

Document	What it covers
Installation	Requirements, registering, configuration, the table.
Collectors and targets	Writing a collector and a target; what the flush does.
Usages	"Where is it used", refusing a deletion, broken links.
Extension points	What an application implements, configures, replaces or relies on.
Testing	How the bundle is tested.
Reference	Every type of the bundle.

Quick start

$references->usagesOf(ResourceReference::of('image', $image->id));   // where is it used?
$references->assertUnused(ResourceReference::of('image', $image->id)); // StillReferenced when it is

bin/console phil:references:check

Requirements

PHP 8.5 or later; Doctrine DBAL 4.5 and ORM 3.7; Symfony 8.2's dependency injection and config; phil/resource 0.1 for resource references. Symfony Console is optional.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

License

MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Parler Haut Interagir Librement project. See LICENSE.