feat(security): add command to dump role hierarchy as a mermaid chart

symfony · damienfern · Jul 4, 2025 · Jul 4, 2025 · Jul 4, 2025 · Jul 5, 2025
commit 02f276192b46be23c533d628a762f7252ce2c73b
@@ -0,0 +1,112 @@
+<?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\Completion\CompletionInput;
+use Symfony\Component\Console\Completion\CompletionSuggestions;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Security\Core\Dumper\MermaidDumper;
+use Symfony\Co
10000
mponent\Security\Core\Role\RoleHierarchyInterface;
+
+/**
+ * Command to dump the role hierarchy as a Mermaid flowchart.
+ *
+ * @author Your Name <your.email@example.com>
+ *
+ * @final
+ */
+#[AsCommand(name: 'debug:security:role-hierarchy', description: 'Dump the role hierarchy as a Mermaid flowchart')]
+class SecurityRoleHierarchyDumpCommand extends Command
+{
+    private const DIRECTION_OPTIONS = [
+        'TB',
+        'TD',
+        'BT',
+        'RL',
+        'LR',
+    ];
+
+    public function __construct(
+        private readonly ?RoleHierarchyInterface $roleHierarchy = null,
+    ) {
+        parent::__construct();
+    }
+
+    protected function configure(): void
+    {
+        $this
+            ->setDefinition([
+                new InputOption('direction', 'd', InputOption::VALUE_REQUIRED, 'The direction of the flowchart ['.implode('|', self::DIRECTION_OPTIONS).']', 'TB'),
+                new InputOption('format', 'f', InputOption::VALUE_REQUIRED, 'The output format', 'mermaid'),
+            ])
+            ->setHelp(<<<'USAGE'
+The <info>%command.name%</info> command dumps the role hierarchy in different formats.
+
+<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
+    {
+        if (null === $this->roleHierarchy) {
+            $output->writeln('<comment>No role hierarchy is configured.</comment>');
+            return Command::SUCCESS;
+        }
+
+        $direction = $input->getOption('direction');
+        $format = $input->getOption('format');
+
+        if ('mermaid' !== $format) {
+            $output->writeln('<error>Only "mermaid" format is currently supported.</error>');
+            return Command::FAILURE;
+        }
+
+        if (!in_array($direction, self::DIRECTION_OPTIONS, true)) {
+            $output->writeln('<error>Invalid direction. Available options: '.implode(', ', self::DIRECTION_OPTIONS).'</error>');
+            return Command::FAILURE;
+        }
+
+        // Map console direction options to dumper constants
+        $directionMap = [
+            'TB' => MermaidDumper::DIRECTION_TOP_TO_BOTTOM,
+            'TD' => MermaidDumper::DIRECTION_TOP_DOWN,
+            'BT' => MermaidDumper::DIRECTION_BOTTOM_TO_TOP,
+            'RL' => MermaidDumper::DIRECTION_RIGHT_TO_LEFT,
+            'LR' => MermaidDumper::DIRECTION_LEFT_TO_RIGHT,
+        ];
+
+        $dumper = new MermaidDumper($directionMap[$direction]);
+        $mermaidOutput = $dumper->dump($this->roleHierarchy);
+
+        $output->writeln($mermaidOutput);
+
+        return Command::SUCCESS;
+    }
+
+    public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
+    {
+        if ($input->mustSuggestOptionValuesFor('direction')) {
+            $suggestions->suggestValues(self::DIRECTION_OPTIONS);
+        }
+
+        if ($input->mustSuggestOptionValuesFor('format')) {
+            $suggestions->suggestValues(['mermaid']);
+        }
+    }
+}
@@ -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,104 @@
+<?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\Application;
+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->assertEquals(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->assertEquals(Command::SUCCESS, $exitCode);
+        $output = $commandTester->getDisplay();
+        $this->assertStringContainsString('graph TB', $output);
+        $this->assertStringContainsString('ROLE_ADMIN --> ROLE_USER', $output);
+        $this->assertStringContainsString('ROLE_SUPER_ADMIN --> ROLE_ADMIN', $output);
+        $this->assertStringContainsString('ROLE_SUPER_ADMIN --> ROLE_USER', $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->assertEquals(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->assertEquals(Command::FAILURE, $exitCode);
+        $this->assertStringContainsString('Invalid direction', $commandTester->getDisplay());
+    }
+
+    public function testExecuteWithInvalidFormat()
+    {
+        $hierarchy = [
+            'ROLE_ADMIN' => ['ROLE_USER'],
+        ];
+
+        $roleHierarchy = new RoleHierarchy($hierarchy);
+        $command = new SecurityRoleHierarchyDumpCommand($roleHierarchy);
+        $commandTester = new CommandTester($command);
+
+        $exitCode = $commandTester->execute(['--format' => 'dot']);
+
+        $this->assertEquals(Command::FAILURE, $exitCode);
+        $this->assertStringContainsString('Only "mermaid" format is currently supported', $commandTester->getDisplay());
+    }
+
+}
@@ -0,0 +1,129 @@
+<?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\RoleHierarchyInterface;
+
+/**
+ * MermaidDumper dumps a Mermaid flowchart describing role hierarchy.
+ *
+     * @author Damien Fernandes <your.email@example.com>
+ */
+class MermaidDumper
+{
+    public const DIRECTION_TOP_TO_BOTTOM = 'TB';
+    public const DIRECTION_TOP_DOWN = 'TD';
+    public const DIRECTION_BOTTOM_TO_TOP = 'BT';
+    public const DIRECTION_RIGHT_TO_LEFT = 'RL';
+    public const DIRECTION_LEFT_TO_RIGHT = 'LR';
+
+    private const VALID_DIRECTIONS = [
+        self::DIRECTION_TOP_TO_BOTTOM,
+        self::DIRECTION_TOP_DOWN,
+        self::DIRECTION_BOTTOM_TO_TOP,
+        self::DIRECTION_RIGHT_TO_LEFT,
+        self::DIRECTION_LEFT_TO_RIGHT,
+    ];
+
+    public function __construct(
+        private readonly string $direction = self::DIRECTION_TOP_TO_BOTTOM,
+    ) {
+        if (!in_array($direction, self::VALID_DIRECTIONS, true)) {
+            throw new \InvalidArgumentException(sprintf(
+                'Direction "%s" is not valid, valid directions are: "%s".',
+                $direction,
+                implode('", "', self::VALID_DIRECTIONS)
+            ));
+        }
+    }
+
+    /**
+     * Dumps the role hierarchy as a Mermaid flowchart.
+     *
+     * @param RoleHierarchyInterface $roleHierarchy The role hierarchy to dump
+     */
+    public function dump(RoleHierarchyInterface $roleHierarchy): string
+    {
+        $hierarchy = $this->extractHierarchy($roleHierarchy);
+
+        if ([] === $hierarchy) {
+            return "graph {$this->direction}\n    classDef default fill:#e1f5fe;";
+        }
+
+        $output = ["graph {$this->direction}"];
+        $allRoles = $this->getAllRoles($hierarchy);
+
+        // Add role nodes
+        foreach ($allRoles as $role) {
+            $output[] = $this->formatRoleNode($role);
+        }
+
+        // Add hierarchy relationships (parent -> child)
+        foreach ($hierarchy as $parentRole => $childRoles) {
+            foreach ($childRoles as $childRole) {
+                $output[] = "    {$this->escapeRoleName($parentRole)} --> {$this->escapeRoleName($childRole)}";
+            }
+        }
+
+        return implode("\n", array_filter($output));
+    }
+
+    /**
+     * Extracts the role hierarchy from the RoleHierarchyInterface.
+     */
+    private function extractHierarchy(RoleHierarchyInterface $roleHierarchy): array
+    {
+        $reflection = new \ReflectionClass($roleHierarchy);
+
+        if ($reflection->hasProperty('hierarchy')) {
+            $hierarchyProperty = $reflection->getProperty('hierarchy');
+            return $hierarchyProperty->getValue($roleHierarchy);
+        }
+
+        return [];
+    }
+
+    /**
+     * Gets all unique roles from the hierarchy.
+     */
+    private function getAllRoles(array $hierarchy): array
+    {
+        $allRoles = [];
+
+        foreach ($hierarchy as $parentRole => $childRoles) {
+            $allRoles[] = $parentRole;
+            foreach ($childRoles as $childRole) {
+                $allRoles[] = $childRole;
+            }
+        }
+
+        return array_unique($allRoles);
+    }
+
+    /**
+     * Formats a role node for Mermaid.
+     */
+    private function formatRoleNode(string $role): string
+    {
+        $escapedRole = $this->escapeRoleName($role);
+        return "    {$escapedRole}";
+    }
+
+    /**
+     * Escapes role name for use as Mermaid node ID.
+     */
+    private function escapeRoleName(string $role): string
+    {
+        // Replace any non-alphanumeric characters with underscores
+        return preg_replace('/[^a-zA-Z0-9_]/', '_', $role);
+    }
+}