[TwigComponent] Support for SubDirectory-named components via namespace config

[weaverryan]

Q	A
Bug fix?	no
New feature?	yes
Tickets	Ref: symfony/demo#1426 (comment)
License	MIT

Recipes PR: symfony/recipes#1243

Currently, you can render an anonymous component with a : syntax, which becomes a subdirectory:

<twig:Button:Primary /> -> templates/components/Button/Primary.html.twig

But if you want to add a class for this component later, you now must use the name: 'Button:Primary' key. That's because, even if the component lives in App\Twig\Components\Button\Primary, the automatic component name will just be Primary.

New Features & Conventions from this PR

A) New Config

You configure the "namespace root" and templates directory for your components. Default will be:

# config/packages/twig_component.yaml
twig_component:
    defaults:
        # default component template directory
        App\Twig\Components\: 'components/'

If you don't have this config, you will get the same "class name === component name" behavior of today, but with a deprecation notice.

B) SubDirectory Naming

Thanks to the above, component names now take into account "subdirectories":

Component Class	Component Name
App\Twig\Components\Alert	Alert
App\Twig\Components\Button\Primary	Button:Primary

Best-Practices / Conventions

1. App\Twig\Components\ as the default namespace/directory for components.

What do people think? What are you doing in your apps today?

2. Upper-camel case for component names

You can do whatever you want, but I'm proposing that we continue to use the convention where component name, class and template all use UpperCamelCase naming:

<twig:Alert> -> App\Twig\Components\Alert -> templates/components/Alert.html.twig

I've also updated and reorganized the TwigComponent docs quite a lot - we had some great sections that, over time, were not in the ideal order.

Also, the TwigComponent docs now use the <twig:HTML> syntax almost exclusively.

Cheers!

TODO

• Recipe update for config file
• Add Configuration section to docs

[smnandre]

1/ We don't find many plurals in symfony "default" structure.. not a preference but App\Twig\**Component**\... seems more usual no ?

2/ 100% for UpperCamel as default case

So maybe

src/Twig/Component/Alert -> templates/components/Alert.html.twig ?

[weaverryan]

1/ We don't find many plurals in symfony "default" structure.. not a preference but App\Twig*Component*... seems more usual no ?

It is a bit odd - we should just decide one way or another. MakerBundle currently generates into App\Twig\Components, which is why I chose it. But that was just the lazy option. We can update MakerBundle. Heck we should make MakerBundle read this config to know where to generate stuff :)

[smnandre]

The symfony demo uses "componentS" too... but it may be a unique thing in the symfony codebase.

(again, i have no personal opinion on the matter)

[tacman]

I prefer Component (without the "S"), so it's consistent with src/Entity, src/EventSubscriber, src/Form.

I've been working on a bundle the incorporates some common bootstrap components (Alert, Accordion, Badge, etc.), and I'm wondering if there's a way to autoregister subdirectories and even anonymous components.

For example, right now I have

        foreach (
            [
                AlertComponent::class,
                AccordionComponent::class,
                AlertComponent::class,
                BadgeComponent::class,
                ButtonComponent::class,
                CardComponent::class,
                CarouselComponent::class,
                DropdownComponent::class,
                DividerComponent::class,
                LinkComponent::class
            ] as $componentClass
        ) {
            $builder->register($componentClass)->setAutowired(true)->setAutoconfigured(true);
        }

But I'm starting to subdivide the component for a bootstrap themes (tabler, snead, adminkit, etc.), to replace the embed/include/macro setup that's common in most layout.html.twig files. But now I have event more components:

• TablerNavbar
• TablerPageHeader
• TablerPageTitle
• TablerUserNavbar

So of course I love the idea of this PR, so I can have Tabler\Navbar.php, Tabler\PageHeader.php, etc.

Most macros port very easily to anonymous components, but also most macros I use are in bundles, so it'd be cool if there were a way when initializing the bundle there were a way to scan the templates directory and register the templates as anonymous components.

[weaverryan]

Replaced by #1151