Adopt PSR-0 namespace convention for core framework classes

I'm all for this. I've been using PSR-0 in drush deploy and it's been great.

As far as the drawbacks go, I don't think 1 is worth considering. The syntax is super ugly; So is php. We'll get over it.

2 is valid, but we dob't have to be tied to it. We could potentially not use that autoloader for a particular set of classes if we ended up with an I/O issue, but we have so few as it is I'm not sure that it would be a problem.

I've been thinking about this for a while as well, and got roughly to the proposal outlined here (i.e. that we could use PSR-0 for /includes and punt on everywhere else for now).

It would be great to be able to use an autoloader that doesn't depend on the database for includes. That makes the registry dependencies on the module system a bit less of an issue if we're just relying on it for module provided classes, while also making lots of things (potentially) not dependent on the database/installer just because they're autoloaded.

I'm not sure we want to autoload everything, it comes at a runtime cost for things that are always loaded anyway. So for example we might want to hard-require interfaces related to very low level systems like CMI, cache etc. to avoid autoloading those, but that's the same whether using PSR-0 or not in /includes. Needs a bit of thought but that's a discussion that probably warrants its own issue. There's definitely a lot of code in Drupal that it does make sense to autoload, that's currently included every request but used hardly ever, like a lot of common.inc.

In principle I agree with this proposal. I think it will make it easier for developers to move between different frameworks.

My main concern is that this will lead to everything which is currently a function being moved to static methods in classes under includes/Drupal. I don't think such an approach would be much of an advancement, especially when considering the effort involved in the migration. This would probably provide a good opportunity to review mode of the include/ code.

I think this is an excellent suggestion. More PHP interoperability to the people!

When implementing we could really benefit from the work done for Symfony2 with this. Their autoloader is really flexible in how it allows you to register namespaces, of any depth, and prefixes to specific directories. This enables you to autoload \Drupal\Form from /includes but \Pathauto\* from /sites/all/modules, for example.

Also the performance issue with increased IO has been solved in Symfony2 with the ClassCache component. If you really want to bother for developers running without APC, that is.

Great summary and explanation.

I think is a big improvement, needed to use other frameworks and to let other frameworks use parts of Drupal.

Subscribe

Closely related: #1239644: Define basic conventions for converting things into classes

subscribing

Include sample of non-Drupal class in the examples at the bottom.

Um yeah, just do it.

Just a question about contributed modules, this change will not make it very incompatible with drupal 7? Just to say, we will need to change in a module about all calls to a drupal function because this.

subscribe

@yukaru there are not really many core classes that contrib modules instantiate directly, if at all. Adopting this convention won't change that, but it's part of wider efforts to refactor a lot of the code in /includes that will mean api changes, which will be done in different issues to this one.

+1

@catch This change will reflect only in existing classes? I was thinking it will change like this, making all drupal oop:

node_load() becomes $node = new Drupal::node(); $node->load();

@yukare, this specific change is just adopting a convention. There may end up being a patch here, it might only be adding the autoloader Crell linked to though if at all.

There are likely to be a large number of other issues in Drupal 8 to convert various subsystems to using classes (although I doubt "all Drupal").

That includes some things linked from #1224666: [meta] Unofficial Drupal 8 Framework initiative, parts of initiatives like WSCCI and CMI, entities and various other bits.

However adopting PSR-0 as a standard and try to get newly added code to conform to it, does not get all of that done, and nor would it all be done in this issue (unless we wanted to try to have the first core issue with 10,000 followups ;)).

What it does do is help us to make some up front decisions about how our classes might be organised, and start to think about issues like how that organisation might impact things like unit testing and performance.

@Crell I think I'm going to start a new issue about front loading of classes, I have some rough ideas but don't want to take this one off topic.

I think I miss something here. You skipped modules? Just like that? So how will contrib fit into this grand* scheme?

grand == totally braindead, usual PHP style.

@chx, there's a possibility we can apply PSR-0 to modules, and/or extend it to classes not provided by modules (i.e. in /libraries or similar). I know people have been thinking about this, not sure if there are concrete steps.

I think it's OK to start by using this for /includes where everything is predictable (and we should not be relying on the registry due to circular dependencies on system module...), and keep the registry for autoloading of classes in modules, at least as a first step.

Right now if you have a class that doesn't live in a module in Drupal 7, you have to hard require it in settings.php if it's needed before the registry is properly available, this doesn't make that situation any better or worse.

I opened #1241190: Possible approaches to bootstrap/front loading of classes.

My favorite reason why this is a good idea: "6) It is not a Drupalism. It's a general PHP convention that any modern PHP developer either has been or will be exposed to sooner or later. That makes Drupal easier to learn because we're not inventing our own standards and conventions needlessly."

I really like the direction this proposal is going. Like @robertDouglass and your point #6, I'm of the mindset that any changes we can start making that bring Drupal more in line with the broader landscape of PHP frameworks lowers the barrier to entry for experienced PHP developers that are new to Drupal.

subscribe

Oh, nice.

<curmudgeon>

It appears the Java-heads have invaded PHP-space and perverted it to their own ends. :-)

Crell says newer Linux kernels have vastly better [filesystem] caching, allowing this use of the filesystem as an autoload registry database to work well. Now, to me, Crell is a programming God. I take his word as gospel, in general. But having spent some years actually building Unix filesystems, I'm a bit skeptical about any filesystem getting that much faster. All that directory -> indirection -> costs -> real -> processing -> time, even if you are lucky enough to avoid having to read one of those meta data blocks off the disk. Not everybody has 16GB of RAM dedicated to their PHP server.

But if as Crell says, this is the way PHP is going and it's essentially a moot point, we might as well join them for consistency and ease of learning sake. I've got a 6-pack of your favorite beer that says D8 will be slower on the same hardware than D6, though.

</curmudgeon>

I agree with those who suggest we not autoload everything. That may be the key.

+1 aka subscribe

Crell: Not quite. The difference between the standard SplClassLoader and Symfony2's UniversalClassLoader is that the latter handles multiple namespaces/prefixes with fallbacks for default directories.

You could of course instantiate the standard one multiple times but then you wouldn't have the convenient fallback.

One important issue to discuss when talking autoloading and namespaces is PHP version requirement. Are we moving to require 5.3+ with Drupal 8?

Also I really don't think we should bend over backwards to facilitate good performance for people not running APC. They obviously don't care much about it, so why should we?

I'd like Drupal to run on non-APC sites but I don't really mind much beyond that - especially if it's a speed vs. memory trade-off, then non-APC sites tend to notice memory issues first - i.e. when hitting the limit.

I do care about installations that have APC enabled, but have not set apc.stat=0, because that's a very common case, so allowing people to remove the file i/o (and also reduce the number of files that need to be individually compiled and cached) is more important.

However I think the discussion about performance really belongs in #1241190: Possible approaches to bootstrap/front loading of classes, unless someone has a really strong objection to file-per-class to the point they'd try to block adopting the standard.

Frankly, this is really the not interesting part of this. PSR-0 is just a stupid convention, adopting it for core framework classes is just a no-brainer. Let's do it.

The remaining part is what's interesting:

• What does it mean for the framework code? How do we split it and refactor it so that it can take best advantage of this? I guess this is partly covered by #1239644: Define basic conventions for converting things into classes
• What does it mean for modules? I suggested earlier to adopt an extension of PSR-0 that automatically load code from modules (a la \Drupal\Modules\Commerce\CommerceEntityController). This could be closely coupled with my proposal of adding a drupal:// streamwrapper for modules and themes (see #1185360: Refactor code loading and support loading from PHAR archives)

Wondering what we're going to do with stuff like StreamWrapperInterface, which is the base for our own DrupalStreamWrapperInterface -- only the latter is in the Drupal namespace.

StreamWrapperInterface is in the global namespace but shouldn't be. It should be provided by PHP but shouldn't. The best we could do is place it under Drupal\File\PHPStreamWrapperInterface.

I think you absolutely want to avoid "require_once" since it will impose disk i/o and the bootstrap file generation approach mentioned here http://drupal.org/node/1241190#comment-4835062 is a much better alternative for users that do not use a byte code cache.

Yeah, let's do it and punt contrib. Agreed.

This is great. Defining a base autoload point within core that follows PSR-0 will solve a number of our chicken-or-egg problems with regards to early-stage logic. As @Damien Tournoud said, this is a big fat no-brainer. Punting on contrib & plugin patterns is perfectly fine, as really, we'll want this in core pretty much no matter what, AND making this decision does not at all lock us in to a particular strategy elsewhere.

Let's be clear, though, that SplClassLoader is sorta awful and shouldn't be used, since we'd end up needing to register a *ton* of objects for additional namespaces/autoload points, and let them each perform their logic independently. An appreciably complex Drupal site could end up with dozens. No bueno. The sort of approach that Symfony2 has taken is a big step forward (@Crell - I mentioned this improved autoloader months ago :P), though that implementation might actually be *more* flexible than what we need, with some resulting IO costs.

@tobiassjosten - it's an overstatement to say that symfony2's class caching has *solved* the io problem. It's a well-established technique, made easier to implement by a well-ordered structure for namespaces, but it can't just magically solve the problem of composing the cache content. We do, and will always (until PHP enters the new millenium and introduces a transparent, native system for opcode caching), have to care about sites without an opcode cache, which means we'll have to be crafty about how we build it. That said, the ClassCollectionLoader is another thing we can pick up and use to help solve this problem.

Keeping my other performance ramblings in a response to #1241190: Possible approaches to bootstrap/front loading of classes.

Hello! Still didn't have the time to read all of this thread yet, but you should be aware I made an autoloader patch, based on my experience and a lot of duplicate code I had to make for many of my modules.

This autoloader handles both map-based and namespace-based PSR-0 autoloading, and seems to work fine. It also have reduced the bootstrap.inc from some code insanity. It is also loaded a lot before the actual autoloader, therefore could be used for cache backends and such later.

Please, for people that are interested go and see a more detailled description over there: #1254488: Map-based and namespace based PSR-0 compatible autoloader proposal

From what I understand so far about PSR-0,
I think we should not jump into this, as long as we don't have at least a rough plan how to deal with contrib modules, themes and libraries.

However:
I have yet failed to find any definition of the PSR-0 standard!
http://www.google.com/search?q=PSR-0
The first link,
http://groups.google.com/group/php-standards/web/psr-0-final-proposal?pli=1
sends me to a list of google group discussion topics, not a definition.
The rest is blog posts pointing to this not-helpful google groups page.

So, before I continue, can anyone post a link?
(ideally, also in the starting post)

Ok, seems this is what we currently know about PSR-0.

7) The PHP community is beginning to come to a consensus around the PSR-0 standard for PHP namespaces and class naming in PHP 5.3+. Both of the 3rd party libraries currently under consideration follow that standard. One of the advantages of it is that it includes an algorithm for a very simple autoload mechanism that requires no external resources (databases, etc.). There is even a standard implementation available under an extremely liberal license. Disclaimer: Although I was not involved in the creation of the PSR-0 standard, I am currently the nominal Drupal representative to the PHP Standards Working Group, such as it is.

PSR-0, as far as I my understanding goes, is designed for arbitrarily nested directory structures, where class names match up with the directory path.
This is not the case for modules.

Drupal modules can be located in a variety of places, and only the system table (*) can tell us where to look for a specific one.
I don't think we should sacrifice this, only to conform with a standard.

So, given a class name, here is what our autoloader will need to do:
1. Detect / guess the module name -> class name prefix (**)
2. Locate the module directory -> system table (*)
3. Locate the class file within the module directory -> PSR-0 with the class name suffix.

(*) "system table"
This could as well be a cached version of the same data, stored in the filesystem.

(**) "class name prefix"
I would propose that class names in modules should be module name (lowercase) + "anything ucfirst".
This can be some_module_SomeClass, or some_module_Some_Class.
So, we get the module name by splitting off anything before the first underscore + uppercase character.

This is still somewhat in the spirit of PSR-0, but with the additional logic that is necessary for Drupal.

myself #43,
there is still a little problem with steps 2. and 3.
What if two modules share the same directory?
The autoloader would look for some_module_SomeClass in the same file as another_module_SomeClass, if both modules are in the same location. (that would be sth like $module_dir/classes/SomeClass.inc)

So, either
- two modules that participate in autoloading cannot be in the same location, OR
- modules can define alternate subfolders to look for classes, via their info file, OR
- the subfolder within the module dir does again contain the module name.

Such as,
sites/all/modules/some_and_another/some_module.info
sites/all/modules/some_and_another/another_module.info
sites/all/modules/some_and_another/lib/some_module/SomeClass.inc
sites/all/modules/some_and_another/lib/another_module/SomeClass.inc

Why can't two modules be in the same location? All it needs to do is look for a file in that directory, and the system table will hold the location.

edited to add: I don't see any problem switching /includes to use this and punt on modules until a bit later. We have the registry available as a transition.

All you need is the system_list() and a convention. As you can find (for now) future core PSR-0 code under DRUPAL_ROOT./includes/<namespace> we could simply have for modules DRUPAL_ROOT./sites/all/modules/<modulename>/includes/<module_namespace> where the module_namespace could be formalized using a convention.

Then in order to use a PSR-0 autoloader over module we'd only need to know the module path (as in system_list() gives us, which is necessary to load the .module file anyway).

pounard #46,

sites/all/modules/<modulename>/includes/<module_namespace>

rather
sites/all/modules/<project_name>/includes/<module_namespace>
where i don't get exactly what you mean with module_namespace.

Also, what is your plan about #43 point 1.?
Given a class name, how do you know which module that is?
Would you agree with my proposal of module name prefix, or do you have a different idea?

catch #45,

Why can't two modules be in the same location?

At least it would create some ambiguity.

A file
sites/all/modules/some_or_another/includes/Some/Class.inc
Which class will this contain?
class some_module_Some_Class, or
class another_module_Some_Class ?

Or is this what we do with the "module_namespace" as in #46 ?

Let's find an example:

content module on D6 was in cck folder, but when asking the system for the content module path, path returned was something like sites/all/modules/cck right?

Then let's take as convention that content module namespace would be Content (just simple camelcase: I take the module name, remove non alpha-numerical chars, and upcase the first letter: easy to do pragmatically, and really fast to) then the namespace path would be: sites/all/modules/cck/includes/Content/.

Now, let's say I have the Content\Field (Field class in the Content namespace) class, then the file would be: sites/all/modules/cck/includes/Content/Field.php

Just a simple sample, but working nicely.

EDIT: With this example, the real PSR-0 starts after sites/all/modules/<module>/includes and with the Symfony autoloader, you can assign path prefix at runtime to namespaces. So, basically, when I bootstrap modules I just have to addNamespaceWithPrefix('Content', 'sites/all/modules/cck/includes') to the autoloader, and basically the only information I need from database is sites/all/modules/cck which I already have in actual Drupal.

Now, allowing module to give another namespace by themselves could be done, either by their info file (but then need to go to database = bad) or either by a hook (if not implemented just assume default camelcased). Or any other mecanic can fit here, but PSR-0 default behavior for modules here is simple and pretty much failsafe (except maybe with the camelcase stuff because you could have a conflict with say cckmenu and cck_menu for example).

Re-EDIT: To allow namespaces to be changed from the module name, the .info line doesn't sound that bad, a column could be added to the system table (makes sense) and still no more SQL request would have to be done (and result can be cached anyway).
Now, to allow multiple namespaces per module, then multiple lines in .info file could be added, then definitely we would have to rely on cache (adding a new table just for namespaces is a lot of overengeneering.

In a perfect world, the D7 registry table would never have existed.

Re-Re-EDIT: I wrote "include" everywhere, but I'd really prefer "library" much more like pretty much all modern PHP frameworks (includes reminds me the good old PHP3, while library seems more the fashionable term now, and semantically a bit more correct IMHO since we are heavily orienting stuff to component driven architecture).

EDIT: With this example, the real PSR-0 starts after sites/all/modules/<module>/includes

Ok, this seems to be the heart of your proposal, that makes it different from mine..
In my imagination, we would skip this additional subfolder level, and PSR-0 only the rest of the class name, that follows the module name (or module namespace).

you can assign path prefix at runtime to namespaces

All this seems to assume that we really move to 5.3 namespaces in D8, and not a "__" or "_hook_" separator.
This would of course make the point 1. from #43 quite easy to solve.

Fine for my taste, but.. for me it did not look like people would come to an agreement soon.
I guess we should prepare sth for both scenarios - with namespaces, and without them.

except maybe with the camelcase stuff because you could have a conflict with say cckmenu and cck_menu for example

I wonder, do we need to CamelCase everything?
Is the perceived "lowercase for classes looks wrong" a higher value than having the literal module name for grep and find-replace?

With namespaces:
I don't see any problem about having lowercase + underscore in namespace names. Or does an undercore mean "subfolder" even for namespace names?

Without namespaces:
some_module_SomeClass or some_module_SomeClass does make it quite easy to detect what is the module name, and what is the class name.
(EDIT:)
With SomeModule_Some_Class, ok, you look at the first fragment..
In both cases, you can nameclash with 3rd party libraries.
With the first approach, you can even nameclash with other modules (but this is not a new problem), since PHP (unlike the autoloader!!) is case-insensitive.

Underscore means subfolder in PSR-0 for PHP5.2, actually most frameworks will ship with autoloaders that will treat both \ and _ as directory separator.

Underscore means subfolder in PSR-0 for PHP5.2, actually most frameworks will ship with autoloaders that will treat both \ and _ as directory separator.

Ok...
As far as I understand, there is not really the "absolute" definition of PSR-0 yet, but rather some ideas, and "this is how framework X implements it".
I do not see why we can not add our own Drupal-specific autoloading logic, that goes beyond basic PSR-0, in aspects where Drupal is just different.

So, the Drupal autoloader would split a class name (+ namespace), use the first part for module detection, and only the second part for PSR-0 within that module dir.
The "underscore = subfolder" would only be relevant for the second part of the class name. In the first part, it is simply part of the module name, and that's it.

---------------

Ok, all that said:
I think I am now convinced that there are viable solutions available for autoloading in modules, and we are not running into a dead end.
The exact implementation can be discussed elsewhere.
So, we can get back to "core framework classes".

Discussion about modules can move here :)
#1290658: Move all module-provided classes to PHP namespaces (PSR-0 or similar), and autoload them without the registry [policy, no patch]

Thus, we would have something like:

/includes/Symfony/Http/Whatever.php (stuff from the Symfony library here.)
/includes/Drupal/Locale/Bulder.php (class \Drupal\Locale\Builder)
/includes/Drupal/Cache/CacheInterface.php (interface \Drupal\Cache\CacheInterface)
/includes/Drupal/Cache/CacheDatabase.php (class \Drupal\Cache\Database, which implements \Drupal\Cache\CacheInterface)

I wonder if this is actually a good idea, to put parts of symfony (or other 3rd party stuff) into includes? Should this not live in sites/all/libraries?
Also, we should be careful including 3rd party stuff in Drupal. If Drupal core depends on a class namespaced as "symfony", then what happens if a user wants to install a different version of symfony in sites/all/libraries? Firstly, it will result in the same class being defined twice, secondly the conflict between versions..
(absolutely not sure if this is what Crell intended with the example)

you guys might also want to keep an eye out for composer. this is currently being worked on to provide packaging for php libs. i don't know exactly if they have plans to deal with different versions of the same lib:
https://github.com/composer

@#53 As Symfony is going to be a core dependency, its component should live side by side with core API: sites dir is for external or contrib code on which the core doesn't rely and not the opposite.

A bit off-topic: I think it'd make sense to move this whole new PHP5.3 API into its own dir such as DRUPAL_ROOT/library to separate it from the legacy includes dir, which name is an inheritance from the past pure PHP3/4 procedural/scripting code style. Library dir name does semantically fit with a library/component based approach.

Follow-ups:

#1320648: Meta: start converting existing core classes to PSR-0 [policy, no patch]
#1320650: Stop scanning /includes with the registry

subscribing

Can I suggest that we use the directory name "classes" instead of "vendor" or "includes". Since, you know, it contains classes. Like the "modules" directory contains modules and the "themes" directory contains themes.

I've taught numerous workshops on OOP in PHP5 and have written many classes for use with Drupal 6 and 7 apps. Can I also suggest that we mandate a standard extension of ".class.php" for all classes. I realise this is a slight variation from PHP, but I believe it adds semantic value to the filename and is preferable (in terms of clarity) to alternatives such as ".inc".

Can I suggest that we use the directory name "classes" instead of "vendor" or "includes". Since, you know, it contains classes. Like the "modules" directory contains modules and the "themes" directory contains themes.

I've taught numerous workshops on OOP in PHP5 and have written many classes for use with Drupal 6 and 7 apps. Can I also suggest that we mandate a standard extension of ".class.php" for all classes. I realise this is a slight variation from PSR-0, but I believe it adds semantic value to the filename and is preferable (in terms of clarity) to alternatives such as ".inc".

PSR-0 does not only serve the purpose of being a project standard, but also helps unifying with Symfony, the chosen underlaying framework and allows us to use their tools (autoloaders and such) without having to extend or rewrite them. Not only Symfony, but a lot of other frameworks are already using this standard and a lot of others will in the future too. I don't think changing that is a good idea for us now, using PSR-0 also means accepting that PHP has standard and raise the understanbility of our own software. Furhter, it's too late since alsmot all Drupal code already has been ported.