Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

The framework exposes maintenance commands for code pickup, cache hygiene, generated metadata, linting, and DI probing.

How it works

server:reload rebuilds autoload and sends a graceful Swoole reload signal, cache:clear removes compiled cache artifacts, registry:sync refreshes generated registry data, and lint/test commands validate architecture and instantiation assumptions.

Why it matters

Without a disciplined maintenance surface, teams fall back to ad-hoc deletes, vague restarts, and guesswork. These commands make routine recovery and validation explicit.

Key concepts

server:reload: Gracefully reloads Swoole workers so code changes are picked up without a full container restart.
cache:clear: Clears compiled cache artifacts such as Twig output when runtime state becomes stale.
test:handler: Instantiates one handler and reports whether DI properties were wired successfully.

Maintenance Surface

Refresh, validate, and inspect the runtime without improvisation

These commands cover the maintenance loop that teams hit all the time: stale templates, generated registries, architecture drift, and suspicious DI wiring.

Graceful refresh. server:reload picks up code changes without a full container restart when the Swoole runtime is healthy.

Architectural checks. lint:* and test:handler turn framework invariants into explicit checks instead of “I hope boot catches it.”

State hygiene. cache:clear and registry:sync reduce the class of issues caused by stale compiled artifacts or outdated generated bindings.

Command	Purpose	Why it matters
`bin/semitexa server:reload`	Gracefully reload Swoole workers after code changes.	Fast path for normal development when containers do not need a full restart.
`bin/semitexa cache:clear --twig`	Clear compiled Twig cache after template changes or stale render state.	Cuts straight to one of the most common SSR debugging needs.
`bin/semitexa registry:sync`	Regenerate DI-oriented registry artifacts such as contract resolvers.	Keeps generated framework metadata aligned with current code.
`bin/semitexa lint:handlers`	Validate handler signatures and payload/resource bindings.	Catches architecture drift before it shows up as a weird runtime failure.
`bin/semitexa test:handler Semitexa\\Demo\\Application\\Handler\\PayloadHandler\\Testing\\AiToolingHandler`	Probe handler instantiation and property injection directly.	Useful when DI uncertainty is more valuable to test than business behavior.

Refresh changed templates safely

bin/semitexa cache:clear --twig
bin/semitexa server:reload

Check architecture after refactor

bin/semitexa registry:sync
bin/semitexa lint:handlers
bin/semitexa lint:di

Probe one suspicious handler

bin/semitexa test:handler 'Semitexa\\Demo\\Application\\Handler\\PayloadHandler\\Testing\\RuntimeMaintenanceHandler'

registry:sync lint:*

Verified against Semitexa Ultimate 2026.09.19.1020

Runtime Maintenance

Strong CLI does not stop at code generation. It also gives operators and developers a disciplined way to refresh, validate, and diagnose a live Semitexa runtime.

How it works

server:reload picks up code changes without a full container restart. cache:clear handles stale compiled Twig templates and other artifacts. registry:sync regenerates DI-oriented registry bindings. lint:* validates handler signatures and architectural invariants. test:handler probes instantiation and DI wiring for a specific handler class.

Why this matters

Without explicit maintenance commands, teams fall back to ad-hoc shell scripts, full restarts, or trial-and-error debugging. A coherent maintenance surface keeps the runtime operable and reduces the cost of investigating unexpected behavior during development and production operations.

1<?php23declare(strict_types=1);45namespace Semitexa\Core\Application\Console\Command;67use Semitexa\Core\Attribute\AsCommand;8use Semitexa\Core\Console\Runtime\ClearCacheAction;9use Semitexa\Core\Console\Runtime\ReloadRuntimeAction;10use Semitexa\Core\Console\Runtime\VerifyRuntimeAction;11use Symfony\Component\Console\Command\Command;12use Symfony\Component\Console\Input\InputInterface;13use Symfony\Component\Console\Output\OutputInterface;14use Symfony\Component\Console\Style\SymfonyStyle;1516/**17 * Lifecycle: clear cache → reload → verify18 *19 * Does NOT rebuild autoload or recreate containers.20 * Only safe for code changes inside existing files.21 * For new/renamed/deleted classes or .env changes, use server:restart.22 */23#[AsCommand(name: 'server:reload', description: 'Gracefully reload Swoole workers (fast, code-only, no env refresh)')]24class ServerReloadCommand extends Command25{26    protected function configure(): void27    {28        $this->setName('server:reload')29            ->setDescription('Gracefully reload Swoole workers (fast, code-only, no env refresh)');30    }3132    protected function execute(InputInterface $input, OutputInterface $output): int33    {34        $io = new SymfonyStyle($input, $output);3536        $io->title('Reloading Swoole Workers');3738        // 1. Clear cache (twig, etc.)39        $clearCache = new ClearCacheAction($io);40        try {41            $clearCache->execute();42        } catch (\Throwable $e) {43            $io->warning(sprintf(44                'Cache clearing failed: %s. Continuing with reload and verification.',45                $e->getMessage()46            ));47        }4849        // 2. Reload: send SIGUSR150        $reload = new ReloadRuntimeAction($io);51        if (!$reload->execute()) {52            return Command::FAILURE;53        }5455        // 3. Verify: health check only (no build marker check)56        // Give workers a moment to cycle57        sleep(2);5859        $verify = new VerifyRuntimeAction($io);60        if (!$verify->execute(checkBuildMarker: false)) {61            return Command::FAILURE;62        }6364        $io->success('Swoole workers reloaded successfully!');65        return Command::SUCCESS;66    }67}68

<?php

declare(strict_types=1);

namespace Semitexa\Core\Application\Console\Command;

use Semitexa\Core\Attribute\AsCommand;
use Semitexa\Core\Console\Runtime\ClearCacheAction;
use Semitexa\Core\Console\Runtime\ReloadRuntimeAction;
use Semitexa\Core\Console\Runtime\VerifyRuntimeAction;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

/**
 * Lifecycle: clear cache → reload → verify
 *
 * Does NOT rebuild autoload or recreate containers.
 * Only safe for code changes inside existing files.
 * For new/renamed/deleted classes or .env changes, use server:restart.
 */
#[AsCommand(name: 'server:reload', description: 'Gracefully reload Swoole workers (fast, code-only, no env refresh)')]
class ServerReloadCommand extends Command
{
    protected function configure(): void
    {
        $this->setName('server:reload')
            ->setDescription('Gracefully reload Swoole workers (fast, code-only, no env refresh)');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);

        $io->title('Reloading Swoole Workers');

        // 1. Clear cache (twig, etc.)
        $clearCache = new ClearCacheAction($io);
        try {
            $clearCache->execute();
        } catch (\Throwable $e) {
            $io->warning(sprintf(
                'Cache clearing failed: %s. Continuing with reload and verification.',
                $e->getMessage()
            ));
        }

        // 2. Reload: send SIGUSR1
        $reload = new ReloadRuntimeAction($io);
        if (!$reload->execute()) {
            return Command::FAILURE;
        }

        // 3. Verify: health check only (no build marker check)
        // Give workers a moment to cycle
        sleep(2);

        $verify = new VerifyRuntimeAction($io);
        if (!$verify->execute(checkBuildMarker: false)) {
            return Command::FAILURE;
        }

        $io->success('Swoole workers reloaded successfully!');
        return Command::SUCCESS;
    }
}

1<?php23declare(strict_types=1);45namespace Semitexa\Core\Application\Console\Command;67use Semitexa\Core\Console\BaseCommand;8use Semitexa\Core\Attribute\AsCommand;9use Semitexa\Llm\Attribute\AsAiSkill;10use Semitexa\Llm\Domain\Enum\AiConfirmationMode;11use Semitexa\Llm\Domain\Enum\AiRiskLevel;12use Symfony\Component\Console\Command\Command;13use Symfony\Component\Console\Input\InputInterface;14use Symfony\Component\Console\Input\InputOption;15use Symfony\Component\Console\Output\OutputInterface;16use Semitexa\Core\Console\Runtime\ReloadRuntimeAction;17use Symfony\Component\Console\Style\SymfonyStyle;18use Symfony\Component\Process\Process;1920/**21 * Clear application cache (Twig compiled templates, etc.).22 *23 * Removing the compiled templates from disk is only half the job under Swoole:24 * each worker holds its own compiled template in memory for its whole life, so25 * a disk-only clear leaves the workers that had already compiled a template26 * serving the old one. The result is not "stale until restart", which would at27 * least be consistent — it is two versions of the same page being served28 * concurrently, depending on which worker answers. So this command signals the29 * running workers to cycle after clearing, and says plainly when it could not.30 *31 * When cache was created by Swoole (e.g. in Docker as root), run with --via-docker so the command runs inside the container and can delete the files.32 */33#[AsCommand(name: 'cache:clear', description: 'Clear application cache (e.g. var/cache/twig) and cycle running workers so they drop their in-memory templates.')]34#[AsAiSkill(35    allowed: true,36    summary: 'Clear application cache after template changes and cycle running workers.',37    useWhen: 'User asks to clear cache, refresh templates, or fix stale runtime state. Also the right answer when a page shows a mix of old and new output between reloads — that is per-worker compiled templates, and this drops them.',38    avoidWhen: 'User asks to restart services, rebuild containers, or reset Docker.',39    riskLevel: AiRiskLevel::Medium,40    confirmation: AiConfirmationMode::Always,41    supportsDryRun: false,42    argumentPolicy: 'allowlisted',43    exposeArguments: ['twig'],44)]45class CacheClearCommand extends BaseCommand46{47    private const CACHE_DIRS = ['twig'];4849    protected function configure(): void50    {51        $this->setName('cache:clear')52            ->setDescription('Clear application cache (e.g. var/cache/twig) and cycle running workers so they drop their in-memory templates.')53            ->addOption('twig', null, InputOption::VALUE_NONE, 'Clear only Twig cache (default: clear all known cache dirs)')54            ->addOption('no-reload', null, InputOption::VALUE_NONE, 'Clear the disk cache only, leaving running workers on their in-memory templates')55            ->addOption('via-docker', null, InputOption::VALUE_NONE, 'Run the clear inside the app container (use when cache was created by Swoole/Docker and host user cannot delete)');56    }5758    protected function execute(InputInterface $input, OutputInterface $output): int59    {60        $io = new SymfonyStyle($input, $output);61        $root = $this->getProjectRoot();62        $viaDocker = (bool) $input->getOption('via-docker');6364        if ($viaDocker) {65            return $this->runViaDocker($io, $root, $input);66        }6768        $baseDir = $root . '/var/cache';69        $twigOnly = (bool) $input->getOption('twig');7071        $dirsToClear = $twigOnly ? ['twig'] : self::CACHE_DIRS;72        $cleared = [];73        $failed = [];7475        foreach ($dirsToClear as $subDir) {76            $path = $baseDir . '/' . $subDir;77            if (!is_dir($path)) {78                continue;79            }80            if ($this->removeDirectoryContents($path)) {81                $cleared[] = 'var/cache/' . $subDir;82            } else {83                $failed[] = 'var/cache/' . $subDir;84            }85        }8687        if (!$twigOnly) {88            $resourceMetadata = $baseDir . '/resource-metadata.php';89            if (is_file($resourceMetadata)) {90                if (@unlink($resourceMetadata)) {91                    $cleared[] = 'var/cache/resource-metadata.php';92                } else {93                    $failed[] = 'var/cache/resource-metadata.php';94                }95            }96        }9798        if ($failed !== [] && $this->canRunViaDocker($root)) {99            $io->note('Could not clear from host (permission denied). Running inside Docker container...');100            return $this->runViaDocker($io, $root, $input);101        }102103        if ($cleared !== []) {104            $io->success('Cleared: ' . implode(', ', $cleared));105        }106        if ($failed !== []) {107            $io->warning('Could not clear: ' . implode('; ', $failed) . '. Run with --via-docker to clear from inside the app container, or: docker compose exec app bin/semitexa cache:clear');108            return Command::FAILURE;109        }110        if (count($cleared) === 0 && count($failed) === 0) {111            $io->text('Nothing to clear (no cache directories found under var/cache).');112        }113114        return $this->dropWorkerTemplates($io, (bool) $input->getOption('no-reload'));115    }116117    /**118     * Signal the running workers to cycle, so the templates they compiled into119     * their own memory go with the ones just removed from disk.120     *121     * Clearing the disk alone is what produced the reported symptom: workers122     * that had already compiled a template kept serving it, workers that had123     * not picked up the new one, and the page flipped between the two by124     * whichever worker answered. Nothing in the output said a restart was125     * needed, so the clear looked like it had worked.126     */127    private function dropWorkerTemplates(SymfonyStyle $io, bool $noReload): int128    {129        if ($noReload) {130            $io->note('Disk cache only (--no-reload). Running workers keep the templates they already compiled; use server:reload to drop those too.');131132            return Command::SUCCESS;133        }134135        $reload = new ReloadRuntimeAction($io);136        $presence = $reload->serverPresence();137138        if ($presence === ReloadRuntimeAction::PRESENCE_ABSENT) {139            $io->text('No running server found — nothing holds a compiled template in memory.');140141            return Command::SUCCESS;142        }143144        if ($presence === ReloadRuntimeAction::PRESENCE_UNKNOWN) {145            // A pidfile exists but could not be read or verified. Saying "no146            // running server" here would be a guess dressed as a fact, and the147            // guess that costs the operator: a live worker keeps serving the148            // template we just deleted while the command reports success.149            $io->warning('A pidfile exists but the Swoole master could not be verified, so the workers were NOT reloaded. Disk cache is clear; run server:reload (or server:restart) before trusting what the page shows.');150151            return Command::FAILURE;152        }153154        if (!$reload->execute()) {155            $io->warning('Disk cache is cleared, but the running workers still hold their compiled templates. Run server:reload (or server:restart) before trusting what the page shows.');156157            return Command::FAILURE;158        }159160        return Command::SUCCESS;161    }162163    private function runViaDocker(SymfonyStyle $io, string $root, InputInterface $input): int164    {165        // Forward the flags, so the in-container run behaves like the one the166        // operator asked for — including whether the workers get cycled. The167        // Swoole master lives in that container, so the reload belongs there.168        $args = ['bin/semitexa', 'cache:clear'];169        if ($input->getOption('twig')) {170            $args[] = '--twig';171        }172        if ($input->getOption('no-reload')) {173            $args[] = '--no-reload';174        }175        $process = new Process(['docker', 'compose', 'exec', '-T', 'app', 'php', ...$args], $root);176        $process->setTimeout(30);177        $process->run(function (string $type, string $buffer) use ($io): void {178            $io->write($buffer);179        });180        if ($process->isSuccessful()) {181            $io->success('Cache cleared (via Docker).');182            return Command::SUCCESS;183        }184        $io->error('Docker exec failed. Is the app container running? Try: docker compose exec app bin/semitexa cache:clear');185        return Command::FAILURE;186    }187188    private function canRunViaDocker(string $root): bool189    {190        if (!is_file($root . '/docker-compose.yml')) {191            return false;192        }193        $process = new Process(['docker', 'compose', 'exec', '-T', 'app', 'true'], $root);194        $process->setTimeout(5);195        $process->run();196        return $process->isSuccessful();197    }198199    /**200     * Remove all contents of a directory (files and subdirs). Directory itself is kept.201     */202    private function removeDirectoryContents(string $path): bool203    {204        if (!is_dir($path) || !is_readable($path)) {205            return false;206        }207        $ok = true;208        $items = @scandir($path);209        if ($items === false) {210            return false;211        }212        foreach ($items as $item) {213            if ($item === '.' || $item === '..') {214                continue;215            }216            $full = $path . '/' . $item;217            if (is_dir($full)) {218                $ok = $this->removeDirectoryRecursive($full) && $ok;219            } else {220                $ok = @unlink($full) && $ok;221            }222        }223        return $ok;224    }225226    private function removeDirectoryRecursive(string $path): bool227    {228        if (!is_dir($path)) {229            return true;230        }231        $items = @scandir($path);232        if ($items === false) {233            return false;234        }235        foreach ($items as $item) {236            if ($item === '.' || $item === '..') {237                continue;238            }239            $full = $path . '/' . $item;240            if (is_dir($full)) {241                $this->removeDirectoryRecursive($full);242            }243            @unlink($full);244        }245        return @rmdir($path);246    }247}248

<?php

declare(strict_types=1);

namespace Semitexa\Core\Application\Console\Command;

use Semitexa\Core\Console\BaseCommand;
use Semitexa\Core\Attribute\AsCommand;
use Semitexa\Llm\Attribute\AsAiSkill;
use Semitexa\Llm\Domain\Enum\AiConfirmationMode;
use Semitexa\Llm\Domain\Enum\AiRiskLevel;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Semitexa\Core\Console\Runtime\ReloadRuntimeAction;
use Symfony\Component\Console\Style\SymfonyStyle;
use Symfony\Component\Process\Process;

/**
 * Clear application cache (Twig compiled templates, etc.).
 *
 * Removing the compiled templates from disk is only half the job under Swoole:
 * each worker holds its own compiled template in memory for its whole life, so
 * a disk-only clear leaves the workers that had already compiled a template
 * serving the old one. The result is not "stale until restart", which would at
 * least be consistent — it is two versions of the same page being served
 * concurrently, depending on which worker answers. So this command signals the
 * running workers to cycle after clearing, and says plainly when it could not.
 *
 * When cache was created by Swoole (e.g. in Docker as root), run with --via-docker so the command runs inside the container and can delete the files.
 */
#[AsCommand(name: 'cache:clear', description: 'Clear application cache (e.g. var/cache/twig) and cycle running workers so they drop their in-memory templates.')]
#[AsAiSkill(
    allowed: true,
    summary: 'Clear application cache after template changes and cycle running workers.',
    useWhen: 'User asks to clear cache, refresh templates, or fix stale runtime state. Also the right answer when a page shows a mix of old and new output between reloads — that is per-worker compiled templates, and this drops them.',
    avoidWhen: 'User asks to restart services, rebuild containers, or reset Docker.',
    riskLevel: AiRiskLevel::Medium,
    confirmation: AiConfirmationMode::Always,
    supportsDryRun: false,
    argumentPolicy: 'allowlisted',
    exposeArguments: ['twig'],
)]
class CacheClearCommand extends BaseCommand
{
    private const CACHE_DIRS = ['twig'];

    protected function configure(): void
    {
        $this->setName('cache:clear')
            ->setDescription('Clear application cache (e.g. var/cache/twig) and cycle running workers so they drop their in-memory templates.')
            ->addOption('twig', null, InputOption::VALUE_NONE, 'Clear only Twig cache (default: clear all known cache dirs)')
            ->addOption('no-reload', null, InputOption::VALUE_NONE, 'Clear the disk cache only, leaving running workers on their in-memory templates')
            ->addOption('via-docker', null, InputOption::VALUE_NONE, 'Run the clear inside the app container (use when cache was created by Swoole/Docker and host user cannot delete)');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $root = $this->getProjectRoot();
        $viaDocker = (bool) $input->getOption('via-docker');

        if ($viaDocker) {
            return $this->runViaDocker($io, $root, $input);
        }

        $baseDir = $root . '/var/cache';
        $twigOnly = (bool) $input->getOption('twig');

        $dirsToClear = $twigOnly ? ['twig'] : self::CACHE_DIRS;
        $cleared = [];
        $failed = [];

        foreach ($dirsToClear as $subDir) {
            $path = $baseDir . '/' . $subDir;
            if (!is_dir($path)) {
                continue;
            }
            if ($this->removeDirectoryContents($path)) {
                $cleared[] = 'var/cache/' . $subDir;
            } else {
                $failed[] = 'var/cache/' . $subDir;
            }
        }

        if (!$twigOnly) {
            $resourceMetadata = $baseDir . '/resource-metadata.php';
            if (is_file($resourceMetadata)) {
                if (@unlink($resourceMetadata)) {
                    $cleared[] = 'var/cache/resource-metadata.php';
                } else {
                    $failed[] = 'var/cache/resource-metadata.php';
                }
            }
        }

        if ($failed !== [] && $this->canRunViaDocker($root)) {
            $io->note('Could not clear from host (permission denied). Running inside Docker container...');
            return $this->runViaDocker($io, $root, $input);
        }

        if ($cleared !== []) {
            $io->success('Cleared: ' . implode(', ', $cleared));
        }
        if ($failed !== []) {
            $io->warning('Could not clear: ' . implode('; ', $failed) . '. Run with --via-docker to clear from inside the app container, or: docker compose exec app bin/semitexa cache:clear');
            return Command::FAILURE;
        }
        if (count($cleared) === 0 && count($failed) === 0) {
            $io->text('Nothing to clear (no cache directories found under var/cache).');
        }

        return $this->dropWorkerTemplates($io, (bool) $input->getOption('no-reload'));
    }

    /**
     * Signal the running workers to cycle, so the templates they compiled into
     * their own memory go with the ones just removed from disk.
     *
     * Clearing the disk alone is what produced the reported symptom: workers
     * that had already compiled a template kept serving it, workers that had
     * not picked up the new one, and the page flipped between the two by
     * whichever worker answered. Nothing in the output said a restart was
     * needed, so the clear looked like it had worked.
     */
    private function dropWorkerTemplates(SymfonyStyle $io, bool $noReload): int
    {
        if ($noReload) {
            $io->note('Disk cache only (--no-reload). Running workers keep the templates they already compiled; use server:reload to drop those too.');

            return Command::SUCCESS;
        }

        $reload = new ReloadRuntimeAction($io);
        $presence = $reload->serverPresence();

        if ($presence === ReloadRuntimeAction::PRESENCE_ABSENT) {
            $io->text('No running server found — nothing holds a compiled template in memory.');

            return Command::SUCCESS;
        }

        if ($presence === ReloadRuntimeAction::PRESENCE_UNKNOWN) {
            // A pidfile exists but could not be read or verified. Saying "no
            // running server" here would be a guess dressed as a fact, and the
            // guess that costs the operator: a live worker keeps serving the
            // template we just deleted while the command reports success.
            $io->warning('A pidfile exists but the Swoole master could not be verified, so the workers were NOT reloaded. Disk cache is clear; run server:reload (or server:restart) before trusting what the page shows.');

            return Command::FAILURE;
        }

        if (!$reload->execute()) {
            $io->warning('Disk cache is cleared, but the running workers still hold their compiled templates. Run server:reload (or server:restart) before trusting what the page shows.');

            return Command::FAILURE;
        }

        return Command::SUCCESS;
    }

    private function runViaDocker(SymfonyStyle $io, string $root, InputInterface $input): int
    {
        // Forward the flags, so the in-container run behaves like the one the
        // operator asked for — including whether the workers get cycled. The
        // Swoole master lives in that container, so the reload belongs there.
        $args = ['bin/semitexa', 'cache:clear'];
        if ($input->getOption('twig')) {
            $args[] = '--twig';
        }
        if ($input->getOption('no-reload')) {
            $args[] = '--no-reload';
        }
        $process = new Process(['docker', 'compose', 'exec', '-T', 'app', 'php', ...$args], $root);
        $process->setTimeout(30);
        $process->run(function (string $type, string $buffer) use ($io): void {
            $io->write($buffer);
        });
        if ($process->isSuccessful()) {
            $io->success('Cache cleared (via Docker).');
            return Command::SUCCESS;
        }
        $io->error('Docker exec failed. Is the app container running? Try: docker compose exec app bin/semitexa cache:clear');
        return Command::FAILURE;
    }

    private function canRunViaDocker(string $root): bool
    {
        if (!is_file($root . '/docker-compose.yml')) {
            return false;
        }
        $process = new Process(['docker', 'compose', 'exec', '-T', 'app', 'true'], $root);
        $process->setTimeout(5);
        $process->run();
        return $process->isSuccessful();
    }

    /**
     * Remove all contents of a directory (files and subdirs). Directory itself is kept.
     */
    private function removeDirectoryContents(string $path): bool
    {
        if (!is_dir($path) || !is_readable($path)) {
            return false;
        }
        $ok = true;
        $items = @scandir($path);
        if ($items === false) {
            return false;
        }
        foreach ($items as $item) {
            if ($item === '.' || $item === '..') {
                continue;
            }
            $full = $path . '/' . $item;
            if (is_dir($full)) {
                $ok = $this->removeDirectoryRecursive($full) && $ok;
            } else {
                $ok = @unlink($full) && $ok;
            }
        }
        return $ok;
    }

    private function removeDirectoryRecursive(string $path): bool
    {
        if (!is_dir($path)) {
            return true;
        }
        $items = @scandir($path);
        if ($items === false) {
            return false;
        }
        foreach ($items as $item) {
            if ($item === '.' || $item === '..') {
                continue;
            }
            $full = $path . '/' . $item;
            if (is_dir($full)) {
                $this->removeDirectoryRecursive($full);
            }
            @unlink($full);
        }
        return @rmdir($path);
    }
}

1<?php23declare(strict_types=1);45namespace Semitexa\Core\Application\Console\Command;67use Semitexa\Core\Console\BaseCommand;8use Semitexa\Core\Attribute\AsCommand;9use Symfony\Component\Console\Command\Command;10use Symfony\Component\Console\Input\ArrayInput;11use Symfony\Component\Console\Input\InputInterface;12use Symfony\Component\Console\Input\InputOption;13use Symfony\Component\Console\Output\OutputInterface;14use Symfony\Component\Console\Style\SymfonyStyle;1516/**17 * Convenience command: runs registry:sync:contracts and (if available) registry:sync:entities.18 * Payload and resource sync have been removed — discovery happens at runtime.19 */20#[AsCommand(name: 'registry:sync', description: 'Run all registry sync commands (contracts, and entities if available).')]21class RegistrySyncCommand extends BaseCommand22{23    protected function configure(): void24    {25        $this->setName('registry:sync')26            ->setDescription('Run all registry sync commands (contracts, and entities if available).')27            ->addOption('json', null, InputOption::VALUE_NONE, 'Pass --json to sub-commands that support it');28    }2930    protected function execute(InputInterface $input, OutputInterface $output): int31    {32        $app = $this->getApplication();33        if ($app === null) {34            $output->writeln('<error>Application not available.</error>');35            return Command::FAILURE;36        }3738        $io = new SymfonyStyle($input, $output);39        $json = (bool) $input->getOption('json');40        $exitCode = Command::SUCCESS;4142        $contractsCmd = $app->find('registry:sync:contracts');43        if ($contractsCmd->run(new ArrayInput([]), $output) !== Command::SUCCESS) {44            $exitCode = Command::FAILURE;45        }4647        if ($app->has('registry:sync:entities')) {48            $entitiesCmd = $app->find('registry:sync:entities');49            $entitiesInput = new ArrayInput($json ? ['--json' => true] : []);50            if ($entitiesCmd->run($entitiesInput, $output) !== Command::SUCCESS) {51                $exitCode = Command::FAILURE;52            }53        }5455        if ($exitCode === Command::SUCCESS && !$json) {56            $io->success('Registry sync completed.');57        }5859        return $exitCode;60    }61}62

<?php

declare(strict_types=1);

namespace Semitexa\Core\Application\Console\Command;

use Semitexa\Core\Console\BaseCommand;
use Semitexa\Core\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\ArrayInput;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

/**
 * Convenience command: runs registry:sync:contracts and (if available) registry:sync:entities.
 * Payload and resource sync have been removed — discovery happens at runtime.
 */
#[AsCommand(name: 'registry:sync', description: 'Run all registry sync commands (contracts, and entities if available).')]
class RegistrySyncCommand extends BaseCommand
{
    protected function configure(): void
    {
        $this->setName('registry:sync')
            ->setDescription('Run all registry sync commands (contracts, and entities if available).')
            ->addOption('json', null, InputOption::VALUE_NONE, 'Pass --json to sub-commands that support it');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $app = $this->getApplication();
        if ($app === null) {
            $output->writeln('<error>Application not available.</error>');
            return Command::FAILURE;
        }

        $io = new SymfonyStyle($input, $output);
        $json = (bool) $input->getOption('json');
        $exitCode = Command::SUCCESS;

        $contractsCmd = $app->find('registry:sync:contracts');
        if ($contractsCmd->run(new ArrayInput([]), $output) !== Command::SUCCESS) {
            $exitCode = Command::FAILURE;
        }

        if ($app->has('registry:sync:entities')) {
            $entitiesCmd = $app->find('registry:sync:entities');
            $entitiesInput = new ArrayInput($json ? ['--json' => true] : []);
            if ($entitiesCmd->run($entitiesInput, $output) !== Command::SUCCESS) {
                $exitCode = Command::FAILURE;
            }
        }

        if ($exitCode === Command::SUCCESS && !$json) {
            $io->success('Registry sync completed.');
        }

        return $exitCode;
    }
}

1<?php23declare(strict_types=1);45namespace Semitexa\Core\Application\Console\Command;67use Semitexa\Core\Console\BaseCommand;8use Semitexa\Core\Attribute\AsCommand;9use Semitexa\Core\Attribute\AsPayloadHandler;10use Semitexa\Core\Contract\ResourceInterface;11use Semitexa\Core\Contract\TypedHandlerInterface;12use Semitexa\Core\Discovery\AttributeDiscovery;13use Semitexa\Core\HttpResponse;14use Symfony\Component\Console\Input\InputInterface;15use Symfony\Component\Console\Output\OutputInterface;16use Symfony\Component\Console\Style\SymfonyStyle;1718/**19 * Validate all handler signatures, return types, and payload/resource bindings.20 */21#[AsCommand(name: 'lint:handlers', description: 'Validate handler signatures, return types, and payload/resource bindings')]22final class LintHandlersCommand extends BaseCommand23{24    public function __construct(25        private readonly AttributeDiscovery $attributeDiscovery,26    ) {27        parent::__construct();28    }2930    protected function execute(InputInterface $input, OutputInterface $output): int31    {32        $io = new SymfonyStyle($input, $output);33        $io->title('Lint: Handlers');3435        $handlerClasses = $this->attributeDiscovery->getDiscoveredPayloadHandlerClassNames();36        $errors = [];3738        foreach ($handlerClasses as $handlerClass) {39            try {40                $ref = new \ReflectionClass($handlerClass);41            } catch (\Throwable $e) {42                $errors[] = "{$handlerClass}: Cannot reflect — {$e->getMessage()}";43                continue;44            }4546            // Must implement TypedHandlerInterface47            if (!$ref->implementsInterface(TypedHandlerInterface::class)) {48                $errors[] = "{$handlerClass}: Does not implement TypedHandlerInterface.";49                continue;50            }5152            // Must have handle() method53            if (!$ref->hasMethod('handle')) {54                $errors[] = "{$handlerClass}: Missing handle() method.";55                continue;56            }5758            $method = $ref->getMethod('handle');5960            // handle() must be public61            if (!$method->isPublic()) {62                $errors[] = "{$handlerClass}::handle() must be public.";63            }6465            // Must have at least 2 params66            $params = $method->getParameters();67            if (count($params) < 2) {68                $errors[] = "{$handlerClass}::handle() must accept at least 2 parameters (payload, resource).";69                continue;70            }7172            // Param 0: concrete class type73            $p0Type = $params[0]->getType();74            if (!$p0Type instanceof \ReflectionNamedType || $p0Type->isBuiltin()) {75                $errors[] = "{$handlerClass}::handle() parameter 0 must be a concrete class type.";76            }7778            // Param 1: must implement ResourceInterface. Multi-profile routes allow79            // union types (e.g. JsonResourceResponse|JsonLdResourceResponse)80            // for routes that serve multiple render profiles via Accept81            // negotiation; every component of the union must independently82            // implement ResourceInterface.83            $p1Type = $params[1]->getType();84            if ($p1Type instanceof \ReflectionUnionType) {85                foreach ($p1Type->getTypes() as $candidate) {86                    if (!$candidate instanceof \ReflectionNamedType || $candidate->isBuiltin()) {87                        $errors[] = "{$handlerClass}::handle() parameter 1 union must contain only concrete class types.";88                        continue;89                    }90                    $name = $candidate->getName();91                    if (!is_subclass_of($name, ResourceInterface::class) && $name !== ResourceInterface::class) {92                        $errors[] = "{$handlerClass}::handle() parameter 1 union type {$name} must implement ResourceInterface.";93                    }94                }95            } elseif (!$p1Type instanceof \ReflectionNamedType || $p1Type->isBuiltin()) {96                $errors[] = "{$handlerClass}::handle() parameter 1 must be a concrete ResourceInterface type.";97            } elseif (!is_subclass_of($p1Type->getName(), ResourceInterface::class)98                && $p1Type->getName() !== ResourceInterface::class) {99                $errors[] = "{$handlerClass}::handle() parameter 1 type {$p1Type->getName()} must implement ResourceInterface.";100            }101102            // Return type must not be HttpResponse103            $returnType = $method->getReturnType();104            if ($returnType instanceof \ReflectionNamedType && $returnType->getName() === HttpResponse::class) {105                $errors[] = "{$handlerClass}::handle() must return ResourceInterface, not HttpResponse.";106            }107108            // #[AsPayloadHandler] validation109            $attrs = $ref->getAttributes(AsPayloadHandler::class);110            if ($attrs !== []) {111                $attr = $attrs[0]->newInstance();112                if (!class_exists($attr->payload)) {113                    $errors[] = "{$handlerClass}: Payload class {$attr->payload} does not exist.";114                }115                if (!class_exists($attr->resource)) {116                    $errors[] = "{$handlerClass}: Resource class {$attr->resource} does not exist.";117                }118            }119        }120121        if ($errors === []) {122            $io->success(sprintf('All %d handlers are valid.', count($handlerClasses)));123            return self::SUCCESS;124        }125126        foreach ($errors as $error) {127            $io->error($error);128        }129        $io->error(sprintf('%d error(s) found in %d handlers.', count($errors), count($handlerClasses)));130        return self::FAILURE;131    }132}133

<?php

declare(strict_types=1);

namespace Semitexa\Core\Application\Console\Command;

use Semitexa\Core\Console\BaseCommand;
use Semitexa\Core\Attribute\AsCommand;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Contract\ResourceInterface;
use Semitexa\Core\Contract\TypedHandlerInterface;
use Semitexa\Core\Discovery\AttributeDiscovery;
use Semitexa\Core\HttpResponse;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

/**
 * Validate all handler signatures, return types, and payload/resource bindings.
 */
#[AsCommand(name: 'lint:handlers', description: 'Validate handler signatures, return types, and payload/resource bindings')]
final class LintHandlersCommand extends BaseCommand
{
    public function __construct(
        private readonly AttributeDiscovery $attributeDiscovery,
    ) {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $io->title('Lint: Handlers');

        $handlerClasses = $this->attributeDiscovery->getDiscoveredPayloadHandlerClassNames();
        $errors = [];

        foreach ($handlerClasses as $handlerClass) {
            try {
                $ref = new \ReflectionClass($handlerClass);
            } catch (\Throwable $e) {
                $errors[] = "{$handlerClass}: Cannot reflect — {$e->getMessage()}";
                continue;
            }

            // Must implement TypedHandlerInterface
            if (!$ref->implementsInterface(TypedHandlerInterface::class)) {
                $errors[] = "{$handlerClass}: Does not implement TypedHandlerInterface.";
                continue;
            }

            // Must have handle() method
            if (!$ref->hasMethod('handle')) {
                $errors[] = "{$handlerClass}: Missing handle() method.";
                continue;
            }

            $method = $ref->getMethod('handle');

            // handle() must be public
            if (!$method->isPublic()) {
                $errors[] = "{$handlerClass}::handle() must be public.";
            }

            // Must have at least 2 params
            $params = $method->getParameters();
            if (count($params) < 2) {
                $errors[] = "{$handlerClass}::handle() must accept at least 2 parameters (payload, resource).";
                continue;
            }

            // Param 0: concrete class type
            $p0Type = $params[0]->getType();
            if (!$p0Type instanceof \ReflectionNamedType || $p0Type->isBuiltin()) {
                $errors[] = "{$handlerClass}::handle() parameter 0 must be a concrete class type.";
            }

            // Param 1: must implement ResourceInterface. Multi-profile routes allow
            // union types (e.g. JsonResourceResponse|JsonLdResourceResponse)
            // for routes that serve multiple render profiles via Accept
            // negotiation; every component of the union must independently
            // implement ResourceInterface.
            $p1Type = $params[1]->getType();
            if ($p1Type instanceof \ReflectionUnionType) {
                foreach ($p1Type->getTypes() as $candidate) {
                    if (!$candidate instanceof \ReflectionNamedType || $candidate->isBuiltin()) {
                        $errors[] = "{$handlerClass}::handle() parameter 1 union must contain only concrete class types.";
                        continue;
                    }
                    $name = $candidate->getName();
                    if (!is_subclass_of($name, ResourceInterface::class) && $name !== ResourceInterface::class) {
                        $errors[] = "{$handlerClass}::handle() parameter 1 union type {$name} must implement ResourceInterface.";
                    }
                }
            } elseif (!$p1Type instanceof \ReflectionNamedType || $p1Type->isBuiltin()) {
                $errors[] = "{$handlerClass}::handle() parameter 1 must be a concrete ResourceInterface type.";
            } elseif (!is_subclass_of($p1Type->getName(), ResourceInterface::class)
                && $p1Type->getName() !== ResourceInterface::class) {
                $errors[] = "{$handlerClass}::handle() parameter 1 type {$p1Type->getName()} must implement ResourceInterface.";
            }

            // Return type must not be HttpResponse
            $returnType = $method->getReturnType();
            if ($returnType instanceof \ReflectionNamedType && $returnType->getName() === HttpResponse::class) {
                $errors[] = "{$handlerClass}::handle() must return ResourceInterface, not HttpResponse.";
            }

            // #[AsPayloadHandler] validation
            $attrs = $ref->getAttributes(AsPayloadHandler::class);
            if ($attrs !== []) {
                $attr = $attrs[0]->newInstance();
                if (!class_exists($attr->payload)) {
                    $errors[] = "{$handlerClass}: Payload class {$attr->payload} does not exist.";
                }
                if (!class_exists($attr->resource)) {
                    $errors[] = "{$handlerClass}: Resource class {$attr->resource} does not exist.";
                }
            }
        }

        if ($errors === []) {
            $io->success(sprintf('All %d handlers are valid.', count($handlerClasses)));
            return self::SUCCESS;
        }

        foreach ($errors as $error) {
            $io->error($error);
        }
        $io->error(sprintf('%d error(s) found in %d handlers.', count($errors), count($handlerClasses)));
        return self::FAILURE;
    }
}

1<?php23declare(strict_types=1);45namespace Semitexa\Core\Application\Console\Command;67use Semitexa\Core\Console\BaseCommand;8use Semitexa\Core\Attribute\AsCommand;9use Semitexa\Core\Attribute\InjectAsFactory;10use Semitexa\Core\Attribute\InjectAsMutable;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Container\ContainerFactory;13use Semitexa\Core\Container\RequestScopedContainer;14use Symfony\Component\Console\Command\Command;15use Symfony\Component\Console\Input\InputArgument;16use Symfony\Component\Console\Input\InputInterface;17use Symfony\Component\Console\Output\OutputInterface;18use Symfony\Component\Console\Style\SymfonyStyle;1920#[AsCommand(name: 'test:handler', description: 'Test handler instantiation and property injection')]21class TestHandlerCommand extends BaseCommand22{23    protected function configure(): void24    {25        $this->setName('test:handler')26            ->setDescription('Test handler instantiation and property injection')27            ->addArgument('handler', InputArgument::REQUIRED, 'Handler class name (FQN)');28    }2930    protected function execute(InputInterface $input, OutputInterface $output): int31    {32        $io = new SymfonyStyle($input, $output);33        $handlerClass = $input->getArgument('handler');3435        $io->title('Testing Handler: ' . $handlerClass);3637        try {38            // Test 1: Direct container get()39            $io->section('Test 1: Direct container->get()');40            $container = ContainerFactory::get();41            try {42                $handler1 = $container->get($handlerClass);43                $io->success('✅ get() succeeded');44                $this->inspectHandler($io, $handler1, $handlerClass);45            } catch (\Throwable $e) {46                $io->error('❌ get() failed: ' . $e->getMessage());47            }4849            // Test 2: RequestScopedContainer get()50            $io->section('Test 2: RequestScopedContainer->get()');51            // Diagnostic-only: createRequestScoped() builds a fresh scope per52            // call, which matches what runtime request handlers do (one scope53            // per request). The previous getRequestScoped() API returned a54            // memoized instance and was removed; for this diagnostic the55            // distinction does not matter — we just need to resolve through56            // the request-scoped path and inspect the result.57            $requestScoped = ContainerFactory::createRequestScoped();58            try {59                $handler2 = $requestScoped->get($handlerClass);60                $io->success('✅ RequestScopedContainer->get() succeeded');61                $this->inspectHandler($io, $handler2, $handlerClass);62            } catch (\Throwable $e) {63                $io->error('❌ RequestScopedContainer->get() failed: ' . $e->getMessage());64            }6566            // Test 3: Check if handler is registered67            $io->section('Test 3: Container has()');68            $hasDefinition = $container->has($handlerClass);69            $io->text('Has entry: ' . ($hasDefinition ? '✅ yes' : '❌ no'));7071        } catch (\Throwable $e) {72            $io->error('Fatal error: ' . $e->getMessage());73            $io->text($e->getTraceAsString());74            return Command::FAILURE;75        }7677        return Command::SUCCESS;78    }7980    private function inspectHandler(SymfonyStyle $io, object $handler, string $handlerClass): void81    {82        $reflection = new \ReflectionClass($handler);8384        $io->text('Class: ' . get_class($handler));85        $io->text('Properties:');8687        foreach ($reflection->getProperties() as $property) {88            $property->setAccessible(true);89            $name = $property->getName();90            $value = $property->getValue($handler);9192            $attrs = [];93            if (!empty($property->getAttributes(InjectAsReadonly::class))) {94                $attrs[] = 'InjectAsReadonly';95            }96            if (!empty($property->getAttributes(InjectAsMutable::class))) {97                $attrs[] = 'InjectAsMutable';98            }99            if (!empty($property->getAttributes(InjectAsFactory::class))) {100                $attrs[] = 'InjectAsFactory';101            }102            $injectMark = $attrs !== [] ? ' [' . implode(', ', $attrs) . ']' : '';103104            if ($value === null) {105                $io->text("  ❌ {$name}: NULL (not initialized){$injectMark}");106            } else {107                $io->text("  ✅ {$name}: " . get_class($value) . $injectMark);108            }109        }110    }111}112113

<?php

declare(strict_types=1);

namespace Semitexa\Core\Application\Console\Command;

use Semitexa\Core\Console\BaseCommand;
use Semitexa\Core\Attribute\AsCommand;
use Semitexa\Core\Attribute\InjectAsFactory;
use Semitexa\Core\Attribute\InjectAsMutable;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Container\ContainerFactory;
use Semitexa\Core\Container\RequestScopedContainer;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

#[AsCommand(name: 'test:handler', description: 'Test handler instantiation and property injection')]
class TestHandlerCommand extends BaseCommand
{
    protected function configure(): void
    {
        $this->setName('test:handler')
            ->setDescription('Test handler instantiation and property injection')
            ->addArgument('handler', InputArgument::REQUIRED, 'Handler class name (FQN)');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $handlerClass = $input->getArgument('handler');

        $io->title('Testing Handler: ' . $handlerClass);

        try {
            // Test 1: Direct container get()
            $io->section('Test 1: Direct container->get()');
            $container = ContainerFactory::get();
            try {
                $handler1 = $container->get($handlerClass);
                $io->success('✅ get() succeeded');
                $this->inspectHandler($io, $handler1, $handlerClass);
            } catch (\Throwable $e) {
                $io->error('❌ get() failed: ' . $e->getMessage());
            }

            // Test 2: RequestScopedContainer get()
            $io->section('Test 2: RequestScopedContainer->get()');
            // Diagnostic-only: createRequestScoped() builds a fresh scope per
            // call, which matches what runtime request handlers do (one scope
            // per request). The previous getRequestScoped() API returned a
            // memoized instance and was removed; for this diagnostic the
            // distinction does not matter — we just need to resolve through
            // the request-scoped path and inspect the result.
            $requestScoped = ContainerFactory::createRequestScoped();
            try {
                $handler2 = $requestScoped->get($handlerClass);
                $io->success('✅ RequestScopedContainer->get() succeeded');
                $this->inspectHandler($io, $handler2, $handlerClass);
            } catch (\Throwable $e) {
                $io->error('❌ RequestScopedContainer->get() failed: ' . $e->getMessage());
            }

            // Test 3: Check if handler is registered
            $io->section('Test 3: Container has()');
            $hasDefinition = $container->has($handlerClass);
            $io->text('Has entry: ' . ($hasDefinition ? '✅ yes' : '❌ no'));

        } catch (\Throwable $e) {
            $io->error('Fatal error: ' . $e->getMessage());
            $io->text($e->getTraceAsString());
            return Command::FAILURE;
        }

        return Command::SUCCESS;
    }

    private function inspectHandler(SymfonyStyle $io, object $handler, string $handlerClass): void
    {
        $reflection = new \ReflectionClass($handler);

        $io->text('Class: ' . get_class($handler));
        $io->text('Properties:');

        foreach ($reflection->getProperties() as $property) {
            $property->setAccessible(true);
            $name = $property->getName();
            $value = $property->getValue($handler);

            $attrs = [];
            if (!empty($property->getAttributes(InjectAsReadonly::class))) {
                $attrs[] = 'InjectAsReadonly';
            }
            if (!empty($property->getAttributes(InjectAsMutable::class))) {
                $attrs[] = 'InjectAsMutable';
            }
            if (!empty($property->getAttributes(InjectAsFactory::class))) {
                $attrs[] = 'InjectAsFactory';
            }
            $injectMark = $attrs !== [] ? ' [' . implode(', ', $attrs) . ']' : '';

            if ($value === null) {
                $io->text("  ❌ {$name}: NULL (not initialized){$injectMark}");
            } else {
                $io->text("  ✅ {$name}: " . get_class($value) . $injectMark);
            }
        }
    }
}

Operator Habit

Good maintenance discipline

The command surface is strongest when teams use it instead of ad-hoc deletes, grep, and trial-and-error restarts.

Prefer server:reload to full restarts when the problem is only code pickup and the runtime itself is healthy.

Reach for cache:clear when templates or compiled SSR output behave inconsistently before assuming deeper corruption.

Run lint and test:handler checks early during refactors, not only after breakage becomes visible in the browser.

Keep registry sync explicit so generated binding artifacts stay reviewable rather than magical.

How it works

Why it matters

Without a disciplined maintenance surface, teams fall back to ad-hoc deletes, vague restarts, and guesswork. These commands make routine recovery and validation explicit.

Key concepts

server:reload: Gracefully reloads Swoole workers so code changes are picked up without a full container restart.
cache:clear: Clears compiled cache artifacts such as Twig output when runtime state becomes stale.
test:handler: Instantiates one handler and reports whether DI properties were wired successfully.