# Console Commands and Workers

DBM Framework provides a lightweight CLI runner for application commands and worker jobs. The application entry point is bin/dbm.

# Discover and run entries

php bin/dbm
php bin/dbm list
php bin/dbm command:list
php bin/dbm worker:list
php bin/dbm command example
php bin/dbm worker clear-cache

list shows both groups. The two *:list forms show one group. Commands are explicit operations; workers are suitable for batch processing and integrations. Scheduling is external, for example through system cron. The runner catches uncaught failures. Worker execution also reports elapsed time and peak memory.

Before dispatching, bin/dbm loads bootstrap/autoload.php, initializes the project autoloader, and requires the project .env file. It then creates the service container and invokes bootstrap/services.php followed by bin/services.php, when present. Each service file must return a callable that accepts the container.

# Commands

Place command classes in src/Console/Command/, in the App\Console\Command namespace, with filenames ending in Command.php. ExampleCommand.php is run as example; names such as clear-cache map to ClearCacheCommand.

namespace App\Console\Command;

use Dbm\Console\AbstractCommand;

final class ExampleCommand extends AbstractCommand
{
    public function execute(): void
    {
        $this->success('Completed', true);
    }
}

AbstractCommand provides success(), info(), warning(), and error(). Their optional second argument selects a background color.

# Workers

Place worker classes in src/Console/Worker/, in the App\Console\Worker namespace, with filenames ending in Worker.php.

namespace App\Console\Worker;

use Dbm\Console\AbstractWorker;

final class ClearCacheWorker extends AbstractWorker
{
    public function run(): void
    {
        $this->log('Cache cleared');
        $this->success('Cache cleared');
    }
}

Workers provide log($message, $level), success($message), and error($message). Unlike commands, worker success() accepts only the message; use log() for warning or informational levels.

# Dependency resolution and database lifecycle

Commands and workers are resolved through the service container and can receive dependencies through constructor injection. Register application-specific CLI services in bin/services.php; shared services may be registered in bootstrap/services.php. Do not put application wiring in bin/dbm.

If an entry uses the database, implement RequiresDatabaseInterface. The runner then validates the database environment, resolves DatabaseInterface, and closes the connection after execution. Injecting the database alone does not opt the class into that lifecycle.

namespace App\Console\Worker;

use Dbm\Console\AbstractWorker;
use Dbm\Database\Contracts\DatabaseInterface;
use Dbm\Database\Contracts\RequiresDatabaseInterface;

final class ImportWorker extends AbstractWorker implements RequiresDatabaseInterface
{
    public function __construct(
        private readonly DatabaseInterface $database
    ) {}

    public function run(): void
    {
        foreach ($this->database->fetchAll('SELECT id FROM items') as $row) {
            $this->log((string) $row['id']);
        }

        $this->success('Import finished');
    }
}

The DatabaseInterface binding must be registered in a service file loaded by the CLI entry point. Entries that do not use the database should not implement the marker and will not trigger this database setup.

# Guidelines

• Keep each command or worker focused on one task.
• Use constructor injection and register services in the appropriate service file.
• Log useful progress and report a clear final status.
• Avoid initializing services that an entry does not need.