README

Symfony Console command that recursively deletes files and directories older than a specified number of hours.

Overview

plugin-component-directory-cleaner provides a single Symfony Console command (cleaner:run) that cleans up stale files and empty directories from a given path. It traverses the target directory recursively using PHP's RecursiveDirectoryIterator and RecursiveIteratorIterator, comparing each item's modification time (mtime) against a configurable timeout threshold in hours.

In the SalesRender plugin ecosystem, plugins frequently generate temporary files -- uploaded data, export results, intermediate processing artifacts, and similar ephemeral content. Without periodic cleanup, these files accumulate and consume disk space. This component solves that problem by providing a ready-to-use console command that can be invoked manually, via cron, or programmatically.

The command is automatically registered in every SalesRender plugin that uses plugin-core, since ConsoleAppFactory::createBaseApp() adds DirectoryCleanerCommand to the Symfony Console application by default. No additional configuration is required on the plugin developer's side.

Installation

composer require salesrender/plugin-component-directory-cleaner

Note: If your plugin depends on salesrender/plugin-core, this component is already included as a transitive dependency and the command is auto-registered.

Requirements

• PHP >= 7.1.0
• symfony/console ^5.0

Key Classes

DirectoryCleanerCommand

Namespace: SalesRender\Plugin\Components\DirectoryCleaner

Extends: Symfony\Component\Console\Command\Command

A Symfony Console command registered under the name cleaner:run.

Command Configuration

Arguments

Behavior

1. Resolves the directory argument to a real path via realpath().
2. Creates a RecursiveDirectoryIterator (with SKIP_DOTS flag) wrapped in a RecursiveIteratorIterator using CHILD_FIRST order -- meaning deepest items are processed first, allowing empty subdirectories to be removed after their contents.
3. Iterates over every item:
   • Excluded files (hardcoded list: .gitignore) are skipped. Output: Skip [exclude]: /path/to/file.
   • Items newer than the threshold are skipped. Output: Skip [by timeout]: /path/to/file.
   • Stale directories are removed with rmdir(). Output: Remove [directory]: /path [Success|Failed].
   • Stale files are removed with unlink(). Output: Remove [file]: /path [Success|Failed].
4. Returns exit code 0.

Important: The CHILD_FIRST iteration order ensures that a directory's contents are processed before the directory itself. If all files inside a directory are stale and removed, rmdir() can then successfully remove the now-empty directory. However, if the directory contains even one non-stale file (or an excluded file like .gitignore), rmdir() will fail because the directory is not empty.

Usage

Standalone Usage

You can use DirectoryCleanerCommand in any standalone Symfony Console application:

<?php

use Symfony\Component\Console\Application;
use SalesRender\Plugin\Components\DirectoryCleaner\DirectoryCleanerCommand;

require __DIR__ . '/vendor/autoload.php';

$app = new Application();
// Register the directory cleaner command
$app->add(new DirectoryCleanerCommand());
$app->run();

With Plugin Core

When using salesrender/plugin-core (or any of its specialized variants like plugin-core-macros, plugin-core-logistic, plugin-core-chat, plugin-core-pbx, plugin-core-geocoder, plugin-core-integration), the DirectoryCleanerCommand is automatically registered in ConsoleAppFactory::createBaseApp():

// Inside plugin-core ConsoleAppFactory::createBaseApp()
$app = new Application();
$app->add(new DirectoryCleanerCommand());
// ... other commands registered here ...

A typical plugin's console.php looks like this:

#!/usr/bin/env php
<?php

use SalesRender\Plugin\Core\Macros\Factories\ConsoleAppFactory;

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/bootstrap.php';

$factory = new ConsoleAppFactory();
$application = $factory->build();
$application->run();

Since the factory handles registration, you can immediately use cleaner:run without any additional setup.

CLI Usage

Clean all files older than 24 hours (default):

php console.php cleaner:run /path/to/temp/directory

Clean all files older than 6 hours:

php console.php cleaner:run /path/to/temp/directory 6

Clean all files older than 72 hours (3 days):

php console.php cleaner:run /path/to/uploads 72

Example Output

Skip [exclude]: /var/html/app/temp/.gitignore
Remove [file]: /var/html/app/temp/export_20250101.csv [Success]
Remove [file]: /var/html/app/temp/upload_20250102.xlsx [Success]
Skip [by timeout]: /var/html/app/temp/recent_file.txt
Remove [directory]: /var/html/app/temp/old_batch [Success]

Scheduling with Cron

In a SalesRender plugin, you can schedule periodic cleanup using addCronTask() in your custom ConsoleAppFactory:

use SalesRender\Plugin\Core\Factories\ConsoleAppFactory as BaseConsoleAppFactory;
use Symfony\Component\Console\Application;

class MyConsoleAppFactory extends BaseConsoleAppFactory
{
    public function build(): Application
    {
        // Run cleanup every hour for the uploads directory
        $this->addCronTask('0 * * * *', 'cleaner:run /path/to/uploads 24');
        return parent::build();
    }
}

Configuration

This component has no external configuration files. All parameters are passed as command arguments at runtime:

• directory -- the absolute or relative path to the directory to clean. The path is resolved via realpath().
• hours -- the age threshold in hours. Files and directories with mtime older than now - hours will be deleted. Defaults to 24.

The exclusion list (currently only .gitignore) is hardcoded in the cleanUp() method and cannot be changed via arguments.

API Reference

DirectoryCleanerCommand

See Also

• salesrender/plugin-core -- Core framework that auto-registers this command via ConsoleAppFactory
• salesrender/plugin-component-db -- Related component providing the db:cleaner command (TableCleanerCommand) for cleaning old database table records
• Symfony Console Documentation -- Reference for the underlying Symfony Console component