[HttpKernel][FrameworkBundle] Add alternative convention for bundle directories

[yceruto]

Q	A
Branch?	4.4
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	#32453
License	MIT
Doc PR	TODO

We already know that bundles must be compatible with many Symfony's versions, so it is very likely that current bundles won't be able to use this feature soon, unless they create symbolic links to support both structures.

The point is that this is already happening, so in the future when our bundles stop to support <=4.3 then you'll be sure to change the current directory structure.

We have recently added the getPublicDir() method in #31975, here I'm removing it in favor of hardcoding a new convention.

I've added some functional tests in which I've changed everything to this structure:

-- ModernBundle
   |-- config/ 
   |-- public/
   |-- src/
       |-- ModernBundle.php
   |-- templates/
   |-- translations/

WDYT?

[nicolas-grekas]

As I wrote in #32453 (comment), I'm not sure we want to make dirs configurable. Even getPublicDir is suspicious to me.

[linaori]

I think making them configurable isn't necessarily what I want, it's the confusing structure it has right now I'd like to change. Making dirs configurable is one way to do this, because it means I don't have to follow the current structure and that it provides a migration path to change the default.

I very much prefer the structure as shown in the example. The fact that the non-code directory is called "Resources" (mind you, capital R) is bothering me since the start. the "views" directory isn't named correctly anymore either as it's called "templates" in Symfony.

Not sure if the proposed API is a good idea, but I do think that the bundle is responsible for the exposure of certain directories.

• "Hey Symfony, you can find templates in this directory!"
• "Hey, this directory contains entities, if you use doctrine, please register this"
• etc.

Symfony telling where everything should be feels like something we could change, though it should have sane defaults. I don't agree with the current structure being a sane default anymore due to the changes in the Symfony structure; app/Resources vs bundle/Resources.

[ro0NL]

what if we create a single entrypoint similar like Kernel, e.g. $bundle->locateResource(BundlePaths::CONFIG_DIR[, 'validator.yaml'])

with a built-in deprecation for views in favor of templates

for DI extensions we should also consider injecting the config dir somehow, or access to any path for that matter

[yceruto]

As I wrote in #32453 (comment), I'm not sure we want to make dirs configurable. Even getPublicDir is suspicious to me.

I'm fine if it's not configurable, but we still want a new bundle directory structure, do you want it too?

with a built-in deprecation for views in favor of templates

@ro0NL we shouldn't deprecating yet -> ... bundles must be compatible with many Symfony's versions. at least until we're sure we can all migrate to the new structure without any compatibility issue.

for DI extensions we should also consider injecting the config dir somehow, or access to any path for that matter

I'm not sure it's necessary, you can hardcode it safely there, it's in userland.

[nicolas-grekas]

we still want a new bundle directory structure, do you want it too

yes! that'd look consistent with the new directory structure of apps

I'd just do it in FrameworkExtension only (and remove/deprecate getPublicDir)

[yceruto]

Update

Removed the configuration of the bundle directory, it is now a new convension that we can optionally use as of 4.4 version.

Added getBundleDir method to the Bundle class, which is intended to define the root directory of the bundle. It may differ from the directory where the Bundle.php file is located (aka getPath()), e.g. when we have the new structure src/Bundle.php then ->getBundleDir() is a folder higher up.

The current convention is not being obsolete yet, it will (in the future).

Convention from 3rd-party bundles like Doctrine (/Resources/config/doctrine) must progressively support the new method in order to finally be able to deprecating/remove the old structure.

[nicolas-grekas]

I really like this approach :)
What's the purpose of getPath now? Should we deprecated it? Or should we plan to deprecate it in 5.1, to help bundles migrate smoothly?

[yceruto]

What's the purpose of getPath now? Should we deprecated it? Or should we plan to deprecate it in 5.1, to help bundles migrate smoothly?

I think that as of 5.2 (NOV 2020) where we should start to deprecating the legacy structure as well. That'll match with the end of support for 3.4.

[yceruto]

Sorry for the rebasing after the approved revisions, I needed to update my PhpUnit bridge to make my local phpunit work properly.

Status: This Is Ready In My Side ;)

[nicolas-grekas]

Thank you @yceruto.

[yceruto]

Yujuuu!! 🎉

[anyt]

Hi,

Bundle::getPublicDir() method is mentioned in the documentation but it's not used.

Are there any plans to introduce the function back or remove it from documentation?

[yceruto]

Are there any plans to introduce the function back or remove it from documentation?

Yes, it should be removed from the documentation (leftover of #31975)