Asset Cleaner for Craft CMS

Identify and clean up unused assets in Craft CMS 5.

Features

View Usage Button - See where any asset is used directly from the asset edit page
Utilities Page - Scan volumes for unused assets with bulk actions
Per-Volume Results - Results grouped by volume with individual file counts and total sizes
Export Options - Download CSV or ZIP of unused assets with smart filenames
Folder Structure Option - Choose to preserve folder structure or flatten files in ZIP downloads
Soft Delete (Trash) - Move assets to trash for safe removal with recovery option
Permanent Delete - Permanently delete assets with double confirmation
Progress Indicator - Visual progress bar during scanning
Memory-Efficient - Handles large files (10GB+) without memory issues
CLI Commands - Scan, export, and delete from the command line

Requirements

Craft CMS 5.0.0 or later
PHP 8.2 or later

Installation

Via Composer (recommended)

composer require yannkost/craft-asset-cleaner
php craft plugin/install asset-cleaner

Manual Installation

Copy the asset-cleaner folder to your plugins/ directory
Add to your composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "plugins/asset-cleaner"
        }
    ]
}

Run:

composer require yannkost/craft-asset-cleaner
php craft plugin/install asset-cleaner

Usage

Control Panel

Navigate to Utilities → Asset Cleaner
Select the volumes you want to scan
Click Scan Now
Review the results grouped by volume, showing:
- Number of unused assets per volume
- Total file size per volume
Use bulk actions (global or per-volume):
- Download CSV - Export list of unused assets
- Download ZIP - Download unused assets (with folder structure option)
- Put into Trash - Soft delete assets (recoverable)
- Delete Permanently - Permanently remove assets (with double confirmation)

ZIP Download Options

When downloading a ZIP file, you can choose:

Flat - All files in the ZIP root
Preserve folder structure - Files organized by volume-handle/folder/path/filename

Smart Filenames

Exported files include meaningful names with timestamps:

CSV: unused-assets_volume-name_2024-01-15_14-30-00.csv
ZIP: unused-assets_volume1__volume2_2024-01-15_14-30-00.zip

View Usage Button

On any asset edit page, click the View Usage button (eye icon) to see:

Entries using the asset via Asset fields
Entries referencing the asset in Redactor/CKEditor fields

CLI Commands

# Scan all volumes
php craft asset-cleaner/scan

# Scan specific volumes
php craft asset-cleaner/scan --volumes=images,files

# Export unused assets to CSV
php craft asset-cleaner/scan/export

# Export specific volumes
php craft asset-cleaner/scan/export --volumes=images

# Delete unused assets (with confirmation)
php craft asset-cleaner/scan/delete

# Delete without confirmation
php craft asset-cleaner/scan/delete --force

# Dry run (preview only)
php craft asset-cleaner/scan/delete --dry-run

How It Works

The plugin identifies unused assets by performing comprehensive checks across your Craft CMS site:

Relations Table - Asset field references in entries, globals, categories, and other elements stored in Craft's relations table
Content Fields - Scans Redactor, CKEditor, and PlainText fields for embedded asset URLs, filenames, and paths
Global Sets - Checks global set content fields for asset references
Nested Entries - Resolves Matrix blocks and other nested entries to their parent entries for accurate reporting

The plugin uses multiple search patterns to ensure accurate detection:

Asset filenames
Full asset URLs
Relative URL paths
Folder paths + filenames
data-asset-id attributes in HTML content

No database migrations are required. All queries are performed directly against Craft's existing tables.

Technical Details

Memory-Efficient ZIP Creation

The plugin uses streaming to handle large files without exhausting PHP memory:

Files are processed in 8KB chunks
Temporary files are used instead of loading entire files into memory
Supports files of any size, limited only by disk space

Permissions

The Asset Cleaner utility requires the utility:asset-cleaner permission. Assign this permission to user groups that should have access to the utility.

License

The Craft License. See LICENSE.md for details.

Support