Problem/Motivation

Per #2247381-12: Update all existing change records for PSR-4 support and #14, core components are loaded using the PSR-4 autoloader, but they are still in a lib/Drupal/ directory.

From #12:

Regarding Core/Component:
Classes there are now, too using a PSR-4 compatible, class-loader. They are just not registered to a subnamespace - like /core/modules/node/src is registered to \Drupal\node - instead /core/lib is registered to the top-level namespace directly*. This distinction is important - i.e. it is important to state that we are using PSR-4 everywhere - because of the difference when it comes to underscores. I.e. class names with underscores will not get picked up as namespaces changes, where they would have been before the PSR-4 patch.

From #14:

I made this decision mostly for technical reasons, because PSR-4 is given priority in the class loader (this was Jordi's idea), and because now if we ever want to do any discovery in core folders (for tests or plugins or other), we can use the same logic as for modules.

Proposed resolution

Decide whether:

  • core/lib should be renamed to core/src.
  • It makes sense to keep the Drupal/Core/ and Drupal/Component/ nested directories, or whether they should be rearranged.

Remaining tasks

  • Decide whether core/lib/ should be core/src/.
  • Decide whether it makes sense to keep the Drupal/ directory for Core/ and/or Component/.
  • Decide whether it still makes sense for Core/ and Component/ to be at the same level.

User interface changes

None.

API changes

Filepath changes only, if any.

Comments

xjm’s picture

catch’s picture

Issue tags: +beta deadline

Adding beta deadline. I doubt we'll want to tackle this afterwards.

webchick’s picture

I actually think core/lib is fine. Semantically, the things in that directory are core libraries. Versus in modules, the stuff in that folder is the actual source code of the module.

sun’s picture

Not touching /core/lib has always been part of the PSR-4 agreement.

The only thing that has been changed is how the classes in /core/lib are loaded, but that is an internal, irrelevant detail of the classloader.

In addition, I agree with @webchick's assessment; the directory mostly contains individual components (~= libraries).

In short, changing the directory layout of /core/lib was never on the table.

xjm’s picture

Not touching /core/lib has always been part of the PSR-4 agreement.

Right, but my understanding was that this was because they were going to continue to use PSR-0 for better presumed interoperability with other projects. Now they follow a PSR-0 namespace-to-directory mapping but somehow use the PSR-4 autoloader, which is the source of my confusion. :)

I actually think core/lib is fine. Semantically, the things in that directory are core libraries. Versus in modules, the stuff in that folder is the actual source code of the module.

I don't really buy this because good luck installing or running Drupal core without them. ;) Seems to me they're the source code for the core base system. It's not too big a deal I guess.

What about the Drupal directory bit? My main technical concern with PSR-4 (minor next to my concern with the disruption of the change, but nonetheless) has always been that the namespace-to-directory mapping was no longer 1:1. That said, if we had to give that up, educating people what the PSR-0 and PSR-4 standards were (and explaining that we used one for core's classes themselves for interoperability, but the other for modules that were dependent on core because they couldn't exist outside the Drupal namespace) seemed like a teachable thing. There's a what and a why. But if core/lib/ has one kind of directory-to-namespace mapping, and modules have another, and the reason is not "because the first one is PSR-0 and the second one is PSR-4", I need another way to wrap my head around it, a different what and why.

But if others don't find any of this as unexpected and confusing as I do, we can certainly close this as works as designed so long as we document it clearly/succinctly somewhere obvious.

sun’s picture

It's not clear what you're suggesting. Do you suggest to do the following?

/core/lib/Drupal/Component/Utility  →  /core/src/Component/Utility
/core/lib/Drupal/Core/Utility       →  /core/src/Core/Utility

Notes:

Drupal core is an application framework that consists of many components itself (cf. Symfony, zf2, etc). A framework rather presents a set of libraries. As such, following the directory layout of the PSR-0 standard might make more sense (which has no impact on how the contained classes are loaded though).

The good news is that we do not have to document anything on our own, except of "This follows PSR-0." and "This follows PSR-4."


Counter-arguments/notes:

Guzzle 4 was recently included/upgraded in Drupal core, which also uses PSR-4 (for the better). That's an actual real world proof that PSR-4 is not only for "extensions of application frameworks"; it works under all possible circumstances.

Usage of the PSR-0 directory layout has no special effects on potential git-subtree splits of Drupal\Components in the future. Subtree splits would work with PSR-4, too.

Lastly, we didn't really achieve what we wanted to achieve with Drupal\Component for D8. Many contributors are questioning the sense of the separation from/to Drupal\Core already today. — I personally think it makes sense, but for the sake of full disclosure, without it, the above mentioned PSR-4 paths would shorten to:

/core/lib/Drupal/Component/Utility  →  /core/src/Utility
/core/lib/Drupal/Core/Utility       →  /core/src/Utility

(but again, I'd disagree with removing the Component/Core concept.)

Crell’s picture

A quick clarification: PSR-0 is no longer even relevant. PSR-4 is "directory to namespace mapping, with a configurable prefix". We just have the prefix configured differently for modules and for core. (A few people still are confused by that, so I'm restating it to be explicit.)

I don't feel strongly enough to burn karma on core/lib vs. core/src. If wishes were horses I'd do core/src, but I and not going to shed blood for it.

The /Drupal/ part of the directory never bothered me much. It made a bit more sense back when we had our included Symfony code in there, too, but we've long since switched to /vendor/ and are not going back. I don't expect us to be adding any more namespaces for our own code that aren't under /Drupal/. I have no particular desire to remove it, but I also won't be reduced to tears if we pull that out.

The Core and Component directories, though, I have no idea what the summary is talking about with "at the same level". If it's asking if that distinction is meaningful, the answer is 1000% yes. That split exists very deliberately to highlight and encourage the creation of Drupal-uncoupled components, something we should be doing more of. Removing those is not on the table. At all. If that's not what that line is talking about then I don't understand it in the slightest. :-)

donquixote’s picture

I guess the "right way" to go about Core vs Component would be sth like

"psr-4":
  "Drupal\Core\\": "core/src/"
  "Drupal\Component\Foo\\": "core/vendor/Drupal/Component/Foo/src"

And move the top-level class \Drupal to class \Drupal\Core\Drupal.
It does not look like we are going to do this..

Besides that, I am with Crell, and prefer the solution of least drama. So far it seemed that not touching core/lib/Drupal is the most promising in this regard.

But if core/lib/ has one kind of directory-to-namespace mapping, and modules have another, and the reason is not "because the first one is PSR-0 and the second one is PSR-4"

I expect a number of projects will replace PSR-0 with "PSR-4 with full 1:1 namespace-to-directory.". This is a cheap way to get rid of the underscore handling, without moving any files around. It is perfectly legitimate, and mentioned in Jordi's blog post about PSR-4.

So, it could happen that in the future we will not discuss about PSR-4 vs PSR-0, but about PSR-4 with flat directories vs PSR-4 with deep directories.

Crell’s picture

Developing Drupal/Component outside of the core repo is not on the table (Dries has made that clear) so #9 (putting Drupal/Component in /vendor/) is not an option.

penyaskito’s picture

My "vote" would be to leave it as it is now, because of concerns explained at #3 and #4.

sun’s picture

Status: Active » Closed (works as designed)

As far as I can see, everything has been said on this issue; status quo works as designed.


FWIW: re: #10:

Developing Drupal/Component outside of the core repo is not on the table (Dries has made that clear) so #9 (putting Drupal/Component in /vendor/) is not an option.

Dries made that decision ~2 years ago. Meanwhile we're able to identify clear and true benefits of doing it. Therefore, I predict it's going to happen for D9.

sun’s picture

FWIW, adding a closely related issue.