gistfile1.md

PSR-4: Class Autoloading

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. Introduction

---

The goal for this specification is to extend PSR-0 and to provide an alternative option for applications to determine the location of a file resource on a medium as supported by PHP, when a fully-qualified class name is provided.

2. Scope

---

This specification is partly backwards incompatible with PSR-0. Where a conflict occurs the rules in this specification precede, or override, the rules in PSR-0.

3. Specification

---

• The _ character has no special meaning in class names.
• For a collection of one or more classes a namespace prefix MUST be documented.
• The documented namespace prefix MUST be a valid namespace for each class in the collection.
• The portion of the fully-qualified class name following the namespace prefix must be considered the fully-qualified class name for the purpose of transformation into a filename.
• A conforming autoloader MUST NOT interfere with other autoloaders, and as such it MUST NOT throw exceptions, MUST NOT raise errors of any level, and SHOULD NOT return a value.

4. Examples

---

• Given a namespace prefix \Doctrine\Common and a fully-qualified class name \Doctrine\Common\IsolatedClassLoader, the resulting filename would be IsolatedClassLoader.php.
• Given a namespace prefix \Doctrine and a fully-qualified class name \Doctrine\Common\IsolatedClassLoader, the resulting filename would be Common/IsolatedClassLoader.php.
• Given a namespace prefix \Symfony\Component\HttpFoundation and a fully-qualified class name \Symfony\Component\HttpFoundation\Request, the resulting filename would be Request.php.
• Given a namespace prefix \Symfony and a fully-qualified class name \Symfony\Component\HttpFoundation\Request, the resulting filename would be Component/HttpFoundation/Request.php.
• Given a namespace prefix \Zend and a fully-qualified class name \Zend\Acl, the resulting filename would be Acl.php.
• Given a namespace prefix \Acme\My_Project and a fully-qualified class name \Acme\My_Project\Some_module\some_class, the resulting filename would be Some_module/some_class.php.

👍

You'll need to remove all references of "extending PSR-0" as people will definitelty confuse what that means. This does not rely on PSR-0 and should be read by itself. Even the scope is way off and needs to be redone.

@Drak I thought you hated any sort of example? Why are these ok but the official proposal is being asked to remove ALL of them? Could SOME not be kept?

I could live with this although I would love those examples into a spot where they can be changed outside of the standard.

Well done, @simensen

Gist is nice for quick prototypes like this but I don't get notifications from people so missed some of these comments. :-/

@philsturgeon I'm happy to start tweaking this when it is time to do so.

@AmyStephen Thanks!

I think there is a difference between these examples and implementation examples. I can't speak for @Drak but those are the distinctions I see. If moving them to somewhere else is a blocker I'd happily move them. :)

While I am a fan of terseness and less-is-more, what I see here is a variation on the same problem that @philsturgeon pulled the second vote for. That is, if you don't already understand the rules, just reading the rules won't help. The only thing that does make clear what's happening is the examples, and apparently examples are bad to have in the spec.

We have to recall that the one thing that made PSR-0 acceptable to the original members was the code implementation written by Matthew Weier O'Phinney. The document was bogged down in arguments like we have now, until MWOP wrote some code, and everyone agreed "yes, this is what we mean."

With a nod to @simensen I present this alternative rewrite of the alternative rewrite: https://gist.github.com/pmjones/7129733

@philsturgeon - the examples here are more like test cases. I believe they serve to illustrate expected input/output.

I don't know how anyone could not understand the rules. Clearly everyone got PSR0 without any misunderstanding so this document is just PSR0 with a few amendments. PSR0 is already understood, so therefore amendment is simple to follow.