symfony · damienfern · Jul 4, 2025 · Jul 4, 2025 · Jul 4, 2025 · Jul 5, 2025
@@ -4,6 +4,7 @@ CHANGELOG
 7.4
 ---
 
+ * Add `debug:security:role-hierarchy` command to dump role hierarchy graphs in the Mermaid.js flowchart format
  * Register alias for argument for password hasher when its key is not a class name:
 
     With the following configuration:

@@ -0,0 +1,94 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bundle\SecurityBundle\Command;
+
+use Symfony\Component\Console\Attribute\AsCommand;
+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 Symfony\Component\Console\Style\SymfonyStyle;
+use Symfony\Component\Security\Core\Dumper\MermaidDirectionEnum;
+use Symfony\Component\Security\Core\Dumper\MermaidDumper;
+use Symfony\Component\Security\Core\Role\RoleHierarchyInterface;
+
+/**
+ * Command to dump the role hierarchy as a Mermaid flowchart.
+ *
+ * @author Damien Fernandes <damien.fernandes24@gmail.com>
+ */
+#[AsCommand(name: 'debug:security:role-hierarchy', description: 'Dump the role hierarchy as a Mermaid flowchart')]
+class SecurityRoleHierarchyDumpCommand extends Command
+{
+    public function __construct(
+        private readonly ?RoleHierarchyInterface $roleHierarchy = null,
+    ) {
+        parent::__construct();
+    }
+
+    protected function configure(): void
+    {
+        $this
+            ->setDefinition([
+                new InputOption(
+                    name: 'direction',
+                    shortcut: 'd',
+                    mode: InputOption::VALUE_REQUIRED,
+                    description: 'The direction of the flowchart ['.implode('|', $this->getAvailableDirections()).']',
+                    default: MermaidDirectionEnum::TOP_TO_BOTTOM->value,
+                    suggestedValues: $this->getAvailableDirections()
+                ),
+            ])
+            ->setHelp(<<<'USAGE'
+The <info>%command.name%</info> command dumps the role hierarchy in Mermaid format.
+
+<info>Mermaid</info>: %command.full_name% > roles.mmd
+<info>Mermaid with direction</info>: %command.full_name% --direction=BT > roles.mmd
+USAGE
+            )
+        ;
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $io = new SymfonyStyle($input, $output);
+
+        if (null === $this->roleHierarchy) {
+            $io->getErrorStyle()->writeln('<comment>No role hierarchy is configured.</comment>');
+
+            return Command::SUCCESS;
+        }
+
+        $direction = $input->getOption('direction');
+
+        if (!MermaidDirectionEnum::tryFrom($direction)) {
+            $io->getErrorStyle()->writeln('<error>Invalid direction. Available options: '.implode('|', $this->getAvailableDirections()).'</error>');
+
+            return Command::FAILURE;
+        }
+
+        $dumper = new MermaidDumper();
+        $mermaidOutput = $dumper->dump($this->roleHierarchy, MermaidDirectionEnum::from($direction));
+
+        $output->writeln($mermaidOutput);
+
+        return Command::SUCCESS;
+    }
+
+    /**
+     * @return string[]
+     */
+    private function getAvailableDirections(): array
+    {
+        return array_map(fn ($case) => $case->value, MermaidDirectionEnum::cases());
+    }
+}
@@ -12,6 +12,7 @@
 namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
 use Symfony\Bundle\SecurityBundle\Command\DebugFirewallCommand;
+use Symfony\Bundle\SecurityBundle\Command\SecurityRoleHierarchyDumpCommand;
 
 return static function (ContainerConfigurator $container) {
     $container->services()
@@ -24,5 +25,11 @@
                 false,
             ])
             ->tag('console.command', ['command' => 'debug:firewall'])
+
+        ->set('security.command.role_hierarchy_dump', SecurityRoleHierarchyDumpCommand::class)
+            ->args([
+                service('security.role_hierarchy'),
+            ])
+            ->tag('console.command')
     ;
 };
@@ -0,0 +1,94 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bundle\SecurityBundle\Tests\Command;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Bundle\SecurityBundle\Command\SecurityRoleHierarchyDumpCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Tester\CommandTester;
+use Symfony\Component\Security\Core\Role\RoleHierarchy;
+
+class SecurityRoleHierarchyDumpCommandTest extends TestCase
+{
+    public function testExecuteWithNoRoleHierarchy()
+    {
+        $command = new SecurityRoleHierarchyDumpCommand();
+        $commandTester = new CommandTester($command);
+
+        $exitCode = $commandTester->execute([]);
+
+        $this->assertSame(Command::SUCCESS, $exitCode);
+        $this->assertStringContainsString('No role hierarchy is configured', $commandTester->getDisplay());
+    }
+
+    public function testExecuteWithRoleHierarchy()
+    {
+        $hierarchy = [
+            'ROLE_ADMIN' => ['ROLE_USER'],
+            'ROLE_SUPER_ADMIN' => ['ROLE_ADMIN', 'ROLE_USER'],
+        ];
+
+        $roleHierarchy = new RoleHierarchy($hierarchy);
+        $command = new SecurityRoleHierarchyDumpCommand($roleHierarchy);
+        $commandTester = new CommandTester($command);
+
+        $exitCode = $commandTester->execute([]);
+
+        $this->assertSame(Command::SUCCESS, $exitCode);
+        $output = $commandTester->getDisplay();
+        $expectedOutput = <<<EXPECTED
+graph TB
+    ROLE_ADMIN
+    ROLE_USER
+    ROLE_SUPER_ADMIN
+    ROLE_ADMIN --> ROLE_USER
+    ROLE_SUPER_ADMIN --> ROLE_ADMIN
+    ROLE_SUPER_ADMIN --> ROLE_USER
+
+EXPECTED;
+
+        $this->assertSame($expectedOutput, $output);
+    }
+
+    public function testExecuteWithCustomDirection()
+    {
+        $hierarchy = [
+            'ROLE_ADMIN' => ['ROLE_USER'],
+        ];
+
+        $roleHierarchy = new RoleHierarchy($hierarchy);
+        $command = new SecurityRoleHierarchyDumpCommand($roleHierarchy);
+        $commandTester = new CommandTester($command);
+
+        $exitCode = $commandTester->execute(['--direction' => 'BT']);
+
+        $this->assertSame(Command::SUCCESS, $exitCode);
+        $output = $commandTester->getDisplay();
+        $this->assertStringContainsString('graph BT', $output);
+    }
+
+    public function testExecuteWithInvalidDirection()
+    {
+        $hierarchy = [
+            'ROLE_ADMIN' => ['ROLE_USER'],
+        ];
+
+        $roleHierarchy = new RoleHierarchy($hierarchy);
+        $command = new SecurityRoleHierarchyDumpCommand($roleHierarchy);
+        $commandTester = new CommandTester($command);
+
+        $exitCode = $commandTester->execute(['--direction' => 'INVALID']);
+
+        $this->assertSame(Command::FAILURE, $exitCode);
+        $this->assertStringContainsString('Invalid direction', $commandTester->getDisplay());
+    }
+}
@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.4
+---
+
+* Add `MermaidDumper` to dump Role Hierarchy graphs in the Mermaid.js flowchart format
+
 7.3
 ---
 

@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\Dumper;
+
+enum MermaidDirectionEnum: string
+{
+    case TOP_TO_BOTTOM = 'TB';
+    case TOP_DOWN = 'TD';
+    case BOTTOM_TO_TOP = 'BT';
+    case RIGHT_TO_LEFT = 'RL';
+    case LEFT_TO_RIGHT = 'LR';
+}
@@ -0,0 +1,99 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\Dumper;
+
+use Symfony\Component\Security\Core\Role\RoleHierarchy;
+use Symfony\Component\Security\Core\Role\RoleHierarchyInterface;
+
+/**
+ * MermaidDumper dumps a Mermaid flowchart describing role hierarchy.
+ *
+ * @author Damien Fernandes <damien.fernandes24@gmail.com>
+ */
+class MermaidDumper
+{
+    /**
+     * Dumps the role hierarchy as a Mermaid flowchart.
+     *
+     * @param RoleHierarchyInterface $roleHierarchy The role hierarchy to dump
+     * @param MermaidDirectionEnum   $direction     The direction of the flowchart
+     */
+    public function dump(RoleHierarchyInterface $roleHierarchy, MermaidDirectionEnum $direction = MermaidDirectionEnum::TOP_TO_BOTTOM): string
+    {
+        $hierarchy = $this->extractHierarchy($roleHierarchy);
+
+        if (!$hierarchy) {
+            return "graph {$direction->value}\n    classDef default fill:#e1f5fe;";
+        }
+
+        $output = ["graph {$direction->value}"];
+        $allRoles = $this->getAllRoles($hierarchy);
+
+        foreach ($allRoles as $role) {
+            $output[] = $this->formatRoleNode($role);
+        }
+
+        foreach ($hierarchy as $parentRole => $childRoles) {
+            foreach ($childRoles as $childRole) {
+                $output[] = "    {$this->normalizeRoleName($parentRole)} --> {$this->normalizeRoleName($childRole)}";
+            }
+        }
+
+        return implode("\n", array_filter($output));
+    }
+
+    private function extractHierarchy(RoleHierarchyInterface $roleHierarchy): array
+    {
+        if (!$roleHierarchy instanceof RoleHierarchy) {
+            return [];
+        }
+
+        $reflection = new \ReflectionClass(RoleHierarchy::class);
+
+        if ($reflection->hasProperty('hierarchy')) {
+            $hierarchyProperty = $reflection->getProperty('hierarchy');
+
+            return $hierarchyProperty->getValue($roleHierarchy);
+        }
+
+        return [];
+    }
+
+    private function getAllRoles(array $hierarchy): array
+    {
+        $allRoles = [];
+
+        foreach ($hierarchy as $parentRole => $childRoles) {
+            $allRoles[] = $parentRole;
+            foreach ($childRoles as $childRole) {
+                $allRoles[] = $childRole;
+            }
+        }
+
+        return array_unique($allRoles);
+    }
+
+    private function formatRoleNode(string $role): string
+    {
+        $escapedRole = $this->normalizeRoleName($role);
+
+        return "    {$escapedRole}";
+    }
+
+    /**
+     * Normalizes the role name by replacing non-alphanumeric characters with underscores.
+     */
+    private function normalizeRoleName(string $role): ?string
+    {
+        return preg_replace('/[^a-zA-Z0-9_]/', '_', $role);
+    }
+}
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,7 @@ CHANGELOG @@
 .4
     ---
+     * Add `debug:security:role-hierarchy` command to dump role hierarchy graphs in the Mermaid.js flowchart format
      * Register alias for argument for password hasher when its key is not a class name:
         With the following configuration:
@@ Expand Down @@