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:

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

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

How It Works

1. An editor tries to delete an entry, asset, or category
2. Homer's CP JavaScript calls the safety check API
3. The SafetyService evaluates protection rules, user permissions, and impact data
4. The ImpactAnalysisService queries the usage graph and classifies risk
5. A SafetyCheckResult is returned: allow, warn, confirm, or block
6. If not allowed, a modal shows the risk level, usage breakdown, and recommendation
7. For critical risk, the editor must type DELETE to confirm
8. On confirmation, a bypass token is generated and validated server-side
9. The DeletionGuardService acts as the server-side backstop in block mode
10. 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.