README

Content safety and integrity for Craft CMS. Prevents accidental breakage of content, relationships, assets, and site structure.

Know what will break before it breaks.

Requirements

Craft CMS 5.3.0 or later
PHP 8.2 or later

Installation

Open your terminal and run:

composer require justinholtweb/craft-homer

Then go to Settings > Plugins in the Craft control panel and click Install for Homer — or run:

php craft plugin/install homer

Features

Deletion Safety

Before deleting an entry, asset, or category, Homer checks how many other elements reference it and classifies the risk:

Safe — no references, safe to delete
Low Risk — a few references, warning shown
High Risk — many references, confirmation required
Critical Risk — heavily referenced, typed confirmation (type DELETE) required

Homer can operate in three modes:

Mode	Behavior
Warn	Show warnings but allow the action
Confirm	Require confirmation before risky actions
Block	Prevent risky actions entirely

Relation Safety

Homer builds a usage graph by querying the relations table. For any element, it can tell you:

How many other elements reference it
Which elements, through which fields
Whether any of those referencing elements are live, disabled, or pending

This powers the impact analysis behind every safety check.

Asset Safety

Assets get special treatment. Homer checks:

Relation field references (asset fields, image fields)
Rich text / CKEditor content references via the search index
Unused asset detection for cleanup

Audit Log

Every risky action is logged with:

What action was taken (delete, disable)
Which element was affected
Who performed the action
Risk level and reference count at time of action
The decision (allowed, warned, confirmed, blocked)

Logs are retained for a configurable number of days (default: 90).

CP Integration

Homer adds to the Craft control panel:

Warning modals before dangerous deletions with risk badges, usage breakdowns, and typed confirmation
Usage badges on element edit pages showing incoming reference counts
Homer section in the CP sidebar with a dashboard and audit log
Homer Safety utility with orphaned entry finder, unused asset review, and recent high-risk actions

Permissions

Permission	Description
View impact reports	Access usage and impact report pages
Bypass safety warnings	Proceed past warnings without restriction
Bypass deletion blocks	Override block mode (use carefully)
View audit log	Access the audit log
Manage Homer settings	Change plugin configuration

Configuration

Configure Homer from Settings > Plugins > Homer in the control panel, or create a config/homer.php file:

<?php

return [
    'mode' => 'warn',
    'protectElementTypes' => ['entry', 'asset', 'category'],
    'highRiskUsageThreshold' => 5,
    'typedConfirmationThreshold' => 20,
    'adminBypass' => true,
    'deletionSafety' => true,
    'relationSafety' => true,
    'assetSafety' => true,
    'auditLog' => true,
    'strictEnvironments' => ['production'],
    'auditLogRetentionDays' => 90,
];

Multi-Environment

<?php

return [
    '*' => [
        'mode' => 'warn',
        'adminBypass' => true,
    ],
    'production' => [
        'mode' => 'block',
        'adminBypass' => false,
    ],
    'staging' => [
        'mode' => 'confirm',
    ],
    'dev' => [
        'mode' => 'warn',
    ],
];

The strictEnvironments setting enforces block mode regardless of the mode setting. By default, production is a strict environment.

Settings Reference

Setting	Type	Default	Description
`mode`	`string`	`'warn'`	Safety mode: `warn`, `confirm`, or `block`
`protectElementTypes`	`array`	`['entry', 'asset', 'category']`	Element types Homer checks
`highRiskUsageThreshold`	`int`	`5`	References needed for "high risk"
`typedConfirmationThreshold`	`int`	`20`	References needed for typed confirmation
`adminBypass`	`bool`	`true`	Let admins bypass all checks
`deletionSafety`	`bool`	`true`	Enable deletion impact checks
`relationSafety`	`bool`	`true`	Enable relation safety warnings
`assetSafety`	`bool`	`true`	Enable asset usage detection
`auditLog`	`bool`	`true`	Enable audit logging
`strictEnvironments`	`array`	`['production']`	Environments that force block mode
`auditLogRetentionDays`	`int`	`90`	Days to keep audit log entries

How It Works

An editor tries to delete an entry, asset, or category
Homer's CP JavaScript calls the safety check API
The SafetyService evaluates protection rules, user permissions, and impact data
The ImpactAnalysisService queries the usage graph and classifies risk
A SafetyCheckResult is returned: allow, warn, confirm, or block
If not allowed, a modal shows the risk level, usage breakdown, and recommendation
For critical risk, the editor must type DELETE to confirm
On confirmation, a bypass token is generated and validated server-side
The DeletionGuardService acts as the server-side backstop in block mode
The action is recorded in the audit log

Roadmap

Future versions may include:

Custom safety rule engine
Publish-time validation (missing required relations, assets, fields)
Orphaned content detection and cleanup workflows
Asset replacement safety (dimension, mime type, filesize checks)
URI change impact analysis
Field deletion and handle change warnings
Recycle bin and restore helpers
Queue-based site-wide integrity scans

License

This plugin requires a commercial license. See LICENSE.md.

justinholtweb / craft-homer

Maintainers

Package info

Statistics

Security