Symfony 8.1 Console: Method-Based Commands and Argument Resolvers
Symfony 8.1 lets one class hold many console commands and resolves CLI arguments into entities, dates, and enums. Code examples and caveats inside.
Console commands in Symfony have been getting shorter for a few releases now. Invokable commands and the #[Argument] and #[Option] attributes removed most of the configure() and execute() boilerplate. Symfony 8.1, released on May 29, 2026, takes two more steps in that direction: you can put several commands in one class, and you can let Symfony turn raw CLI input into typed objects before your code runs.
If you maintain a Symfony app with a pile of small admin commands, these two features will change how you organize them. Here is how each one works, with the code, and where I would be careful.
Method-based commands
The usual complaint about one-class-per-command is repeated constructors. Say you have app:user:create and app:user:delete. Both need the user repository and a logger, so you write the same constructor twice.
Symfony 8.1 lets you apply #[AsCommand] to methods instead of the class. This example comes from the official Symfony announcement, contributed by Yonel Ceruto:
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Output\OutputInterface;
class UserCommands
{
public function __construct(
private UserRepository $users,
private LoggerInterface $logger,
) {
}
#[AsCommand('app:user:create', description: 'Creates a new user')]
public function create(OutputInterface $output): int
{
// ...
return Command::SUCCESS;
}
#[AsCommand('app:user:delete', description: 'Deletes an existing user')]
public function delete(OutputInterface $output): int
{
// ...
return Command::SUCCESS;
}
}
Each annotated method is registered as its own command through autoconfiguration. You define the constructor once and every command in the class shares the injected services. Symfony already works this way for multiple controller actions in one class and for multiple Messenger handlers in one class, so the pattern should feel familiar.
Standalone Console and testing
If you use the Console component without the service container, register each method as a first-class callable:
$instance = new UserCommands($users, $logger);
$application = new Application();
$application->addCommand($instance->create(...));
$application->addCommand($instance->delete(...));
Testing is just as direct. Pass the callable to CommandTester and exercise one method at a time:
$tester = new CommandTester((new UserCommands($users, $logger))->create(...));
$tester->execute([]);
$tester->assertCommandIsSuccessful();
A fair criticism
Not everyone likes this. In the comments on the announcement, one reader argued it breaks the Single Responsibility Principle and that having many small class files is no problem in 2026. That is a reasonable position. My take is that grouping makes sense when the commands are truly siblings, such as a set of commands that all manage the same entity. If two commands only share a logger, keep them apart.
Console argument resolvers
The second feature is bigger. Even with invokable commands, you still had to convert raw CLI strings into application objects yourself. An integer user ID became a User entity by calling the repository, and a date string became a DateTimeImmutable by calling createFromFormat().
Symfony 8.1 adds console argument resolvers, contributed by Robin Chalas. If you have used value resolvers in controllers, this is the same mechanism applied to arguments and options. Here is the official example:
use App\Entity\User;
use Symfony\Bridge\Doctrine\Attribute\MapEntity;
use Symfony\Component\Console\Attribute\Argument;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Attribute\MapDateTime;
use Symfony\Component\Console\Attribute\Option;
#[AsCommand(name: 'app:report:generate')]
final class GenerateReportCommand
{
public function __construct(
private ReportGenerator $reports,
) {
}
public function __invoke(
// resolves the entity by its primary key
#[Argument, MapEntity]
User $user,
#[Option, MapDateTime(format: 'Y-m-d')]
\DateTimeInterface $date,
): int {
// ...
}
}
Run it like this:
php bin/console app:report:generate 42 --date=2026-05-08
Symfony loads the User with ID 42 from the database and converts 2026-05-08 into a DateTimeInterface before __invoke() is called. If the argument holds an email address instead of an ID, the announcement shows you can switch the lookup with #[MapEntity(mapping: ['user' => 'email'])].
The announcement also says 8.1 ships built-in resolvers for backed enums and for UUID or ULID values. A commenter pointed out that backed enum support in invokable commands already existed since Symfony 7.4, so treat the enum part as a tidy-up rather than something brand new.
Services in the method signature
Resolvers also let you inject services straight into __invoke() instead of the constructor. Compare the two shapes from the announcement:
// Before
public function __construct(
private ReportGenerator $reports,
) {
}
public function __invoke(
#[Argument] int $userId,
// ...
): int {
// After
public function __invoke(
ReportGenerator $reports,
#[Argument] int $userId,
// ...
): int {
The same dependency injection attributes you use in controllers work here too, including #[Autowire] and #[Target]:
use Psr\Log\LoggerInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\DependencyInjection\Attribute\Target;
use Symfony\Component\Messenger\MessageBusInterface;
#[AsCommand(name: 'app:audit')]
final class AuditCommand
{
public function __invoke(
#[Autowire(service: 'messenger.bus.async')] MessageBusInterface $bus,
#[Target('security')] LoggerInterface $logger,
#[Autowire('%kernel.environment%')] string $env,
): int {
// ...
}
}
Writing your own resolver
Resolvers are extensible. You implement ValueResolverInterface to map arguments and options to any custom object. Built-in, targeted, and custom resolvers are covered in the Symfony Console value resolver documentation. I have not built a custom console resolver yet, so check that page before relying on a specific method signature.
Where I would use these
A few practical notes for a real project:
- Admin command sets. A
TenantCommandsclass withcreate,suspend, andpurgemethods is a good fit for method-based commands. They share a repository and an audit logger, and they all operate on the same concept. - Anything that takes an ID. Commands like
app:invoice:resend 1234are where#[MapEntity]removes the most code. Think about what happens when the ID does not exist, and test that case. I would verify the failure message your team sees before shipping this to ops staff. - Date and enum options.
#[MapDateTime]and enum resolution move parsing out of your command body, so the command only deals with valid values. - Testing. Because the callable passes straight to
CommandTester, method-based commands stay easy to test without booting the kernel.
I have not confirmed in the official posts whether argument resolvers can be combined with method-based commands in the same class. The two announcements show them separately, so test that combination before you rely on it.
Upgrading
Symfony states that its backward compatibility promise applies to 8.1, so upgrading from 8.0 should not require code changes. The 8.1.0 release notes point to the upgrade guide and to SymfonyInsight upgrade reports for spotting code that needs attention. Both features are additive, so you can adopt them one command at a time.
If you run training or internal tooling around Symfony, such as the command line helpers behind a PHP Architect or PHP Tek conference site, these two changes are a nice excuse to clean up a src/Command directory that has grown over the years.
Sources
- Symfony 8.1.0 released, Symfony Blog, May 29, 2026
- New in Symfony 8.1: Method-Based Commands, Symfony Blog, May 6, 2026
- New in Symfony 8.1: Console Argument Resolvers, Symfony Blog, May 8, 2026
- Symfony 8.1 curated new features, Symfony Blog, May 29, 2026
- Symfony Console value resolvers (8.1 docs)