Introduce a modern, JSX-like syntax for TwigComponents

Halleck45 · Halleck45 · commit ebb3a0f7f7df · 2025-03-29T07:15:26.000+01:00
diff --git a/src/TwigComponent/CHANGELOG.md b/src/TwigComponent/CHANGELOG.md
@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.21.0
+
+-  Introduce an experimental JSX-like syntax for TwigComponents, making `<twig:` prefix optional
+
 ## 2.20.0
 
 -  Add Anonymous Component support for 3rd-party bundles #2019
diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst
@@ -1719,6 +1719,36 @@ Pass the name of some component as an argument to print its details:
     |                                                   | int $min = 10                     |
     +---------------------------------------------------+-----------------------------------+
 
+Short Syntax
+------------
+
+An experimental short syntax is available for components, and has been introduced in 2.21.
+
+This mode allows you to omit the `<twig:` prefix and reference components directly by their name,
+with the first letter capitalized.
+
+.. code-block:: html+twig
+
+    <Acme:Button type="primary">
+        Click me
+    </Acme:Button>
+
+This is equivalent to:
+
+.. code-block:: html+twig
+
+    <twig:Acme:Button type="primary">
+        Click me
+    </twig:Acme:Button>
+
+To enable this feature, add the following configuration:
+
+.. code-block:: yaml
+
+    # config/packages/twig_component.yaml
+    twig_component:
+        short_syntax: true
+
 Contributing
 ------------
 
diff --git a/src/TwigComponent/src/Command/TwigComponentDebugCommand.php b/src/TwigComponent/src/Command/TwigComponentDebugCommand.php
@@ -39,6 +39,8 @@ public function __construct(
         private Environment $twig,
         private readonly array $componentClassMap,
         ?string $anonymousDirectory = null,
+        private readonly ?bool $withShortSyntax = false,
+        private readonly ?bool $withProfiler = false,
     ) {
         parent::__construct();
         $this->anonymousDirectory = $anonymousDirectory ?? 'components';
@@ -85,6 +87,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
         $components = $this->findComponents();
         $this->displayComponentsTable($io, $components);
+        $this->displayDetailsAboutConfiguration($io);
 
         return Command::SUCCESS;
     }
@@ -356,4 +359,17 @@ private function getAnonymousComponentProperties(ComponentMetadata $metadata): a
 
         return $properties;
     }
+
+    private function displayDetailsAboutConfiguration(SymfonyStyle $io): void
+    {
+        $io->section('Configuration of TwigComponent');
+        $io->table(
+            ['Configuration', 'Current value'],
+            [
+                ['anonymous_template_directory', $this->anonymousDirectory],
+                ['short_syntax', $this->withShortSyntax ? 'enabled' : 'disabled'],
+                ['profiler',  $this->withProfiler ? 'enabled' : 'disabled'],
+            ]
+        );
+    }
 }
diff --git a/src/TwigComponent/src/DependencyInjection/TwigComponentExtension.php b/src/TwigComponent/src/DependencyInjection/TwigComponentExtension.php
@@ -129,18 +129,30 @@ static function (ChildDefinition $definition, AsTwigComponent $attribute) {
         ;
 
         $container->register('ux.twig_component.twig.lexer', ComponentLexer::class);
+        $container->getDefinition('ux.twig_component.twig.lexer')
+            ->addMethodCall('enableShortSyntax', [$config['short_syntax']]);
 
         $container->register('ux.twig_component.twig.environment_configurator', TwigEnvironmentConfigurator::class)
             ->setDecoratedService(new Reference('twig.configurator.environment'))
             ->setArguments([new Reference('ux.twig_component.twig.environment_configurator.inner')]);
 
+        // Currently, the ComponentLexer is not injected into the TwigEnvironmentConfigurator, but built directly in the
+        // code (with a new ComponentLexer($environment)).
+        // We cannot change this behavior without a major refactoring : environment is currently configured at runtime.
+        // So we add setters for our required options
+        // This should be improved in the future : currently, some parameters of the ComponentLexer are not settable
+        $container->getDefinition('ux.twig_component.twig.environment_configurator')
+            ->addMethodCall('enabledShortSyntax', [$config['short_syntax']]);
+
         $container->register('ux.twig_component.command.debug', TwigComponentDebugCommand::class)
             ->setArguments([
                 new Parameter('twig.default_path'),
                 new Reference('ux.twig_component.component_factory'),
                 new Reference('twig'),
                 new AbstractArgument(\sprintf('Added in %s.', TwigComponentPass::class)),
                 $config['anonymous_template_directory'],
+                $config['short_syntax'],
+                $config['profiler'],
             ])
             ->addTag('console.command')
         ;
@@ -217,6 +229,10 @@ public function getConfigTreeBuilder(): TreeBuilder
                     ->info('Enables the profiler for Twig Component (in debug mode)')
                     ->defaultValue('%kernel.debug%')
                 ->end()
+                ->booleanNode('short_syntax')
+                    ->info('Enables the short syntax for Twig Components (the <twig: prefix is optional)')
+                    ->defaultValue(false)
+                ->end()
                 ->scalarNode('controllers_json')
                     ->setDeprecated('symfony/ux-twig-component', '2.18', 'The "twig_component.controllers_json" config option is deprecated, and will be removed in 3.0.')
                     ->defaultNull()
diff --git a/src/TwigComponent/src/Twig/ComponentLexer.php b/src/TwigComponent/src/Twig/ComponentLexer.php
@@ -26,9 +26,11 @@
  */
 class ComponentLexer extends Lexer
 {
+    private $withShortSyntax = false;
+
     public function tokenize(Source $source): TokenStream
     {
-        $preLexer = new TwigPreLexer();
+        $preLexer = new TwigPreLexer(withShortSyntax: $this->withShortSyntax);
         $preparsed = $preLexer->preLexComponents($source->getCode());
 
         return parent::tokenize(
@@ -39,4 +41,9 @@ public function tokenize(Source $source): TokenStream
             )
         );
     }
+
+    public function enabledShortSyntax(bool $withShortSyntax = true): void
+    {
+        $this->withShortSyntax = $withShortSyntax;
+    }
 }
diff --git a/src/TwigComponent/src/Twig/TwigEnvironmentConfigurator.php b/src/TwigComponent/src/Twig/TwigEnvironmentConfigurator.php
@@ -22,6 +22,8 @@
  */
 class TwigEnvironmentConfigurator
 {
+    private bool $withShortSyntax = false;
+
     public function __construct(
         private readonly EnvironmentConfigurator $decorated,
     ) {
@@ -31,12 +33,22 @@ public function configure(Environment $environment): void
     {
         $this->decorated->configure($environment);
 
-        $environment->setLexer(new ComponentLexer($environment));
+        $componentLexer = new ComponentLexer($environment);
+        $componentLexer->enabledShortSyntax($this->withShortSyntax);
+        $environment->setLexer($componentLexer);
 
         if (class_exists(EscaperRuntime::class)) {
             $environment->getRuntime(EscaperRuntime::class)->addSafeClass(ComponentAttributes::class, ['html']);
         } elseif ($environment->hasExtension(EscaperExtension::class)) {
             $environment->getExtension(EscaperExtension::class)->addSafeClass(ComponentAttributes::class, ['html']);
         }
     }
+
+    /**
+     * This method should be replaced by a proper autowiring configuration.
+     */
+    public function enabledShortSyntax(bool $withShortSyntax = true): void
+    {
+        $this->withShortSyntax = $withShortSyntax;
+    }
 }
diff --git a/src/TwigComponent/src/Twig/TwigPreLexer.php b/src/TwigComponent/src/Twig/TwigPreLexer.php
@@ -15,7 +15,7 @@
 use Twig\Lexer;
 
 /**
- * Rewrites <twig:component> syntaxes to {% component %} syntaxes.
+ * Rewrites <twig:component> or <Component> syntaxes to {% component %} syntaxes.
  */
 class TwigPreLexer
 {
@@ -28,17 +28,34 @@ class TwigPreLexer
      */
     private array $currentComponents = [];
 
-    public function __construct(int $startingLine = 1)
+    public function __construct(int $startingLine = 1, private readonly bool $withShortSyntax = false)
     {
         $this->line = $startingLine;
     }
 
     public function preLexComponents(string $input): string
     {
-        if (!str_contains($input, '<twig:')) {
+        // tag may be:
+        // - long: <twig:componentName>
+        // - short (jsx like): <ComponentName> (with a capital letter)
+
+        $isLongSyntax = str_contains($input, '<twig:');
+        $isShortSyntax = $this->withShortSyntax && preg_match_all('/<([A-Z][a-zA-Z0-9_:-]+)([^>]*)>/', $input, $matches, \PREG_SET_ORDER);
+
+        if (!$isLongSyntax && !$isShortSyntax) {
             return $input;
         }
 
+        if ($isShortSyntax) {
+            $componentNames = array_map(fn ($match) => $match[1], $matches);
+            $componentNames = array_unique(array_filter($componentNames));
+
+            // To simplify things in the rest of the class, we replace the component name with twig:<componentName>
+            foreach ($componentNames as $componentName) {
+                $input = preg_replace('!<(/?)'.preg_quote($componentName).'!', '<$1twig:'.lcfirst($componentName), $input);
+            }
+        }
+
         $this->input = $input = str_replace(["\r\n", "\r"], "\n", $input);
         $this->length = \strlen($input);
         $output = '';
@@ -394,7 +411,7 @@ private function consumeBlock(string $componentName): string
         }
         $blockContents = $this->consumeUntilEndBlock();
 
-        $subLexer = new self($this->line);
+        $subLexer = new self($this->line, $this->withShortSyntax);
         $output .= $subLexer->preLexComponents($blockContents);
 
         $this->consume($closingTag);
diff --git a/src/TwigComponent/tests/Integration/Command/TwigComponentDebugCommandTest.php b/src/TwigComponent/tests/Integration/Command/TwigComponentDebugCommandTest.php
@@ -241,4 +241,17 @@ private function tableDisplayCheck(string $display): void
         $this->assertStringContainsString('Template', $display);
         $this->assertStringContainsString('Properties', $display);
     }
+
+    public function testDisplayDetailsAboutConfiguration(): void
+    {
+        $commandTester = $this->createCommandTester();
+        $commandTester->execute([]);
+
+        $commandTester->assertCommandIsSuccessful();
+
+        $display = $commandTester->getDisplay();
+
+        $this->assertStringContainsString('anonymous_template_directory   components', $display);
+        $this->assertStringContainsString('short_syntax                   disabled', $display);
+    }
 }
diff --git a/src/TwigComponent/tests/Unit/TwigPreLexerTest.php b/src/TwigComponent/tests/Unit/TwigPreLexerTest.php
@@ -26,6 +26,15 @@ public function testPreLex(string $input, string $expectedOutput): void
         $this->assertSame($expectedOutput, $lexer->preLexComponents($input));
     }
 
+    /**
+     * @dataProvider getLexTestsWhithShortOptions
+     */
+    public function testPreLexWithShortSyntax(string $input, string $expectedOutput): void
+    {
+        $lexer = new TwigPreLexer(withShortSyntax: true);
+        $this->assertSame($expectedOutput, $lexer->preLexComponents($input));
+    }
+
     /**
      * @dataProvider getInvalidSyntaxTests
      */
@@ -376,6 +385,12 @@ public static function getLexTests(): iterable
             '<twig:foobar bar="baz" {{ ...attr }}>content</twig:foobar>',
             '{% component \'foobar\' with { bar: \'baz\', ...attr } %}{% block content %}content{% endblock %}{% endcomponent %}',
         ];
+
+        yield 'jsx_component_simple_component_not_enabled_by_default' => [
+            '<Foo />',
+            '<Foo />',
+        ];
+
         yield 'component_with_comment_line' => [
             "<twig:foo \n   # bar  \n />",
             '{{ component(\'foo\') }}',
@@ -437,4 +452,79 @@ public static function getLexTests(): iterable
             TWIG,
         ];
     }
+
+    public function getLexTestsWhithShortOptions()
+    {
+        yield 'not_a_component' => [
+            '<foo />',
+            '<foo />',
+        ];
+
+        yield 'jsx_component_simple_component' => [
+            '<Foo />',
+            '{{ component(\'foo\') }}',
+        ];
+
+        yield 'jsx_component_attribute_with_no_value_and_no_attributes' => [
+            '<Foo/>',
+            '{{ component(\'foo\') }}',
+        ];
+
+        yield 'jsx_component_with_default_block_content' => [
+            '<Foo>Foo</Foo>',
+            '{% component \'foo\' %}{% block content %}Foo{% endblock %}{% endcomponent %}',
+        ];
+
+        yield 'jsx_component_with_default_block_that_holds_a_component_and_multi_blocks' => [
+            '<Foo>Foo <twig:bar /><twig:block name="other_block">Other block</twig:block></Foo>',
+            '{% component \'foo\' %}{% block content %}Foo {{ component(\'bar\') }}{% endblock %}{% block other_block %}Other block{% endblock %}{% endcomponent %}',
+        ];
+
+        yield 'jsx_component_with_character_:_on_his_name' => [
+            '<Foo:bar></Foo:bar>',
+            '{% component \'foo:bar\' %}{% endcomponent %}',
+        ];
+
+        yield 'jsx_component_with_character_-_on_his_name' => [
+            '<Foo-bar></Foo-bar>',
+            '{% component \'foo-bar\' %}{% endcomponent %}',
+        ];
+
+        yield 'jsx_component_with_character_._on_his_name' => [
+            '<Foo.bar></Foo.bar>',
+            '{% component \'foo.bar\' %}{% endcomponent %}',
+        ];
+
+        yield 'jsx_component_with_block' => [
+            '<SuccessAlert>
+                <Block name="alert_message">
+                    xxxx
+                </Block>
+            </SuccessAlert>',
+            '{% component \'successAlert\' %}
+                {% block alert_message %}
+                    xxxx
+                {% endblock %}
+            {% endcomponent %}',
+        ];
+
+        yield 'jsx_component_with_sub_blocks' => [
+            '<SuccessAlert>
+                <Message name="alert_message">
+                    <Icon name="success" />
+                </Message>
+                <Message name="alert_message">
+                    <Icon name="success" />
+                </Message>
+            </SuccessAlert>',
+            '{% component \'successAlert\' %}
+                {% block content %}{% component \'message\' with { name: \'alert_message\' } %}
+                    {% block content %}{{ component(\'icon\', { name: \'success\' }) }}
+                {% endblock %}{% endcomponent %}
+                {% component \'message\' with { name: \'alert_message\' } %}
+                    {% block content %}{{ component(\'icon\', { name: \'success\' }) }}
+                {% endblock %}{% endcomponent %}
+            {% endblock %}{% endcomponent %}',
+        ];
+    }
 }

Original file line number	Diff line number	Diff line change
`@@ -26,9 +26,11 @@`
`26`	`26`	`*/`
`27`	`27`	`class ComponentLexer extends Lexer`
`28`	`28`	`{`
	`29`	`+ private $withShortSyntax = false;`
	`30`	`+`
`29`	`31`	`public function tokenize(Source $source): TokenStream`
`30`	`32`	`{`
`31`		`- $preLexer = new TwigPreLexer();`
	`33`	`+ $preLexer = new TwigPreLexer(withShortSyntax: $this->withShortSyntax);`
`32`	`34`	`$preparsed = $preLexer->preLexComponents($source->getCode());`
`33`	`35`
`34`	`36`	`return parent::tokenize(`
`@@ -39,4 +41,9 @@ public function tokenize(Source $source): TokenStream`
`39`	`41`	`)`
`40`	`42`	`);`
`41`	`43`	`}`
	`44`	`+`
	`45`	`+ public function enabledShortSyntax(bool $withShortSyntax = true): void`
	`46`	`+ {`
	`47`	`+ $this->withShortSyntax = $withShortSyntax;`
	`48`	`+ }`
`42`	`49`	`}`