Bundle repository directory structure

theofidry commented 9 years ago

As stated in the official doc, the current structure of a bundle should be:

<your-bundle>/
├─ AcmeBlogBundle.php
├─ Controller/
├─ README.md
├─ LICENSE
├─ Resources/
│   ├─ config/
│   ├─ doc/
│   │  └─ index.rst
│   ├─ translations/
│   ├─ views/
│   └─ public/
└─ Tests/

Which many developers translate as the following for a repository:

AcmeBlogBundle.php
Controller/
README.md
LICENSE
Resources/
 ├─ config/
 ├─ doc/
 │  └─ index.rst
 ├─ translations/
 ├─ views/
 └─ public/
Tests/

with a composer.json containing:

"autoload": {
     "psr-4": { "Acme\\BlogBundle\\": "" }
}

In short, everything at the root. This practice has two harmful results:

As everything is placed in the root, it easily becomes hard to tell the difference between files related to the source code of the bundle and configuration files such as composer.json, .gitignore, .travis.yml, behat.yml, phpunit.xml.dist and so just to name a few common ones
We include code related to tests in the autoloading even in production mode

Whereas doing the following:

src/
├─ AcmeBlogBundle.php
├─ Controller/
└─ Resources/
   ├─ config/
   ├─ doc/
   │  └─ index.rst
   ├─ translations/
   ├─ views/
   └─ public/
tests/
README.md
Resources
composer.json

with:

"autoload": {
     "psr-4": { "Acme\\BlogBundle\\": "src" }
},
"autoload-dev": {
     "psr-4": { "Acme\\BlogBundle\\Tests\\": "tests" }
}

would address both those issues.

Obviously, changing the architecture of the existing bundles is not always doable as it will break lots of PR and for the bundles which are meant to be used as dev dependencies that's not an issue.

cc @Seldaek

stof commented 9 years ago

I would say that both are acceptable:

Symfony does not care about the location of your tests (it will never access them)
the structure of the bundle itself is still the same, even if the structure of the repo is not (the bundle folder would be the src one as far as Symfony is concerned in your second example)

theofidry commented 9 years ago

Symfony does not care about the location of your tests (it will never access them)

Still, we're dumping too much "useless" (for an application in prod) code to the autoload.php. If it has no performance impact, then at least that's already a relief :)

the structure of the bundle itself is still the same, even if the structure of the repo is not (the bundle folder would be the src one as far as Symfony is concerned in your second example)

Yes both structure are perfectly valid and my issue is more about the directory structure of the actual repository rather than the bundle itself. The way the doc is written and some popular bundle are organised, every developer is hinted to place everything at the root rather than a src. The result is just a mix of source code, configuration files for everything: git, composer configuration, behat/phpunit/phpspec, scrutinizer, travis, etc, and test code.

So it's not a question of changing the bundle organisation itself (sorry if the issue title was misleading, I'm editing the issue title to reflect on that), but rather on the bundle repository structure.

Seldaek commented 9 years ago

Regarding autoloading, it has a minor impact when building optimized autoloaders with composer as the test classes will be in the classmap. Obviously that's not a huge deal if it's a few classes, but it's not zero-impact.

And yes I think it'd be great to bring things in line with common practices of pretty much every other project. There is no real reason anymore to have it all at the repository root.

greg0ire commented 7 years ago

👍 this should be re-evaluated I think. Some thoughts :

src/
├─ AcmeBlogBundle.php
├─ Controller/
└─ Resources/
   ├─ config/
   ├─ doc/
   │  └─ index.rst
   ├─ translations/
   ├─ views/
   └─ public/
tests/
README.md
Resources
composer.json

Resources appears twice here, should it really live under src?
Should we still have Resources or should we have config, doc, public, translations and views or rather, templates at the root of the bundle?

theofidry commented 7 years ago

Yeah I would move the Resources into a single resources folder at the root and put everything there. Regarding the doc I would create a doc folder rather...:

resources/
├─ config/
├─ translations/
├─ public/
└─ views/
doc/ <-- top level
src/  <-- only source code, nothing else
├─ AcmeBlogBundle.php
└─ Controller/
tests/  <-- tests separated, can live in the same namespace as the source code
README.md
composer.json

IMO the biggest mistake for bundles in the Symfony community was to follow the Sensio/Symfony bundle structure which is done for a specific reason and its structure is - I find, inappropriate for a bundle lambda.

And for libraries which come with a bundle, I would rather recommend a project structure a la nelmio/alice or api-platform/core. I've been trying them for a while now and it's been quite successful so far.

greg0ire commented 7 years ago

Should views become templates ?

SimonHeimberg commented 7 years ago

For applications, separate src/ and tests/ directory is recommended since 3.0: http://symfony.com/doc/3.0/best_practices/creating-the-project.html#structuring-the-application

Having the two best practices more similar would be nice.

stof commented 7 years ago

moving Resources outside the bundle folder would require changes in Symfony itself (and in all other bundles doing convention-based registration following the same rules than the core). but moving the code into src and having the doc and the tests outside it is already possible. Symfony does not care about it (as far as your autoloading is working). Having the bundle source at the root is a convention coming from before the PSR-4 spec (to be able to use PSR-0 and composer's target-dir instead of having a huge nesting inside src)

greg0ire commented 7 years ago

So maybe we should do all the BC changes and add compatibility for resources outside src, and then deprecate having them inside src (that last part would be in the far future though).

stof commented 7 years ago

@greg0ire it is too late for 3.4. We are already in the feature freeze since 2 weeks

theofidry commented 7 years ago

it's actually already possible to move the resources folder outside. Right now the only missing par is guidelines and doc, nothing more.

Majkl578 commented 6 years ago

Bump. This is still wrong in 2018.

nicholasruunu commented 6 years ago

With the new SF4 structure I find the resources folder unnecessary, just move everything in resources to root, and change views to templates. Otherwise I agree with @theofidry

stof commented 6 years ago

I would change the recommendation for the doc from /doc to /docs, which is the folder name supported by Github for automatic publication to github pages (handy for bundles wanting to use it to host their doc) and which is also the most common name among PHP packages according to the analysis done by https://github.com/php-pds/skeleton

stof commented 6 years ago

for now, I would keep Resources inside the src folder though. Changing this convention requires changing the core, and it means finding a way for bundles to be compatible with the existing versions of Symfony too (which probably means not updating to the new location, and so not following an updated rule).

stof commented 6 years ago

So to be clear for everyone, here is my proposal:

.github/ # Github templates if needed by the project
bin/ # Any script than need to be exposed by Composer
docs/
src/
├─ AcmeBlogBundle.php
├─ Controller/
└─ Resources/
   ├─ config/
   ├─ translations/
   ├─ views/
   └─ public/
tests/
.travis.yml  # may be a different CI than Travis of course
LICENSE
README.md
composer.json
phpunit.xml.dist

javiereguiluz commented 6 years ago

About the use of doc/ vs docs/, which is the only debatable dir, it took me a while to find out the detailed results in PDS (https://github.com/php-pds/skeleton_research/blob/1.x/results/addendum-dirs.txt), but here they are:

documentation directory     6,397 repos
    docs/   4,240 repos
    doc/    1,838 repos
    documentation/  119 repos

yceruto commented 6 years ago

About keep Resources inside the src folder, couldn't we add all new convention but keeping also the previous one like we've today templates & translations at root and src/Resources/views & src/Resources/translations for projects?

javiereguiluz commented 6 years ago

I agree with Yonel. In fact, we could/should revamp Symfony's handling of bundles (even creating a new interface or bundle mechanism if needed) to support that dir structure. A bundle should/could be like a mini Symfony app, with the same dirs (templates/, src/, config/) and main files (even a src/Kernel.php too).

And if you care about BC compatibility, sadly most bundles are not compatible with newer Symfony versions, so we wouldn't be breaking anything that it's not already broken.

stof commented 6 years ago

@yceruto but then, it means that shared bundles would still have to use the old convention because existing releases only support the old convention. This makes it kind of weird to change the best practice if any bundle caring about the ecosystem by supporting more than the latest minor version of Symfony (remember we have LTS versions of Symfony) would be unable to follow best practices.

Projects are simpler: they control their Symfony version, so they have no issue migrating to the new recommended location.

yceruto commented 6 years ago

but then, it means that shared bundles would still have to use the old convention because existing releases only support the old convention.

For existing ones that want to migrate to the new conventions and still be compatible with old Symfony versions could --symbolic-link be a workaround?

glennmcewan commented 5 years ago

Is this still up for discussion? I think updating the docs to recommend using src/ is worthwhile and BC.

javiereguiluz commented 5 years ago

If you like the idea of allowing to use config/, templates/, translations/, etc. to store bundles files (instead of using Resources/config/, etc.) please show some support and add comments here: https://github.com/symfony/symfony/issues/32453 Thanks.

javiereguiluz commented 5 years ago

I'm closing this in favor of #12156, which will document the new great and modern structure proposed for bundles in https://github.com/symfony/symfony/pull/32845. Thank you all for the discussion!

symfony / symfony-docs

Bundle repository directory structure #5691