dbrabon/file_adoption

Scans the public file directory for orphaned files and adopts them as managed file entities.

v1.2.3 2025-06-30 22:37 UTC

Requires

• php: ^8.2
• drupal/core: ^10 || ^11

Requires (Dev)

• phpunit/phpunit: ^10

GPL-2.0-or-later

• Daniel Boone Brabon

README

File Adoption is a utility module for Drupal that scans the public files directory for files that are not tracked by Drupal's file_managed table. Identified "orphaned" files can be registered as managed file entities.

Installation

1. Place the module in your Drupal installation, typically using Composer:

   composer require dbrabon/file_adoption

   or by copying the module into modules/custom.
2. Enable the module from the Extend page or with Drush:

   drush en file_adoption

3. Navigate to Administration → Reports → File Adoption (/admin/reports/file-adoption) to configure and run scans.

Configuration

The configuration form offers the following options:

• Ignore Patterns – Comma or newline separated patterns (relative to public://) that should be skipped when scanning.
• Enable Adoption – When checked, cron will automatically adopt orphaned files using the configured settings.
• Items per cron run – Maximum number of files processed and displayed per scan or cron run. Defaults to 20.
• Skip symlinks – Enabled by default to ignore files reached through symbolic links. Disable to include them in scans.
• Inventory cache lifetime – Number of seconds to keep scan results before performing a new scan. Defaults to 86400 (24 hours).

Changes are stored in file_adoption.settings.

Cron Integration

When Enable Adoption is active, the module's hook_cron() implementation runs the file scanner during cron to register any discovered orphans automatically. If a cached inventory of scan results exists and is still within the configured cache lifetime, cron processes items from that list before performing a new scan. This allows large inventories to be adopted across multiple cron runs.

Manual Scanning

To run a scan on demand:

1. Visit the File Adoption configuration page at /admin/reports/file-adoption.
2. Click Quick Scan for a fast scan or Batch Scan to process files using Drupal's Batch API.
3. Review the results and click Adopt to create the file entities.
4. If results are cached and you want a fresh scan, click Refresh inventory.

Performance Considerations

Scanning large file trees can take significant time. If manual scans time out, increase PHP's max execution time in your environment. For very large sites, prefer running scans via cron so processing occurs in the background. Use the module's Items per cron run setting to control how many files are processed in each pass.

The Public Directory Contents Preview is only built when a recent inventory is cached or results were loaded from a batch scan. If no cached inventory is available, the form skips directory scanning and displays a placeholder message instead.