pmjones/fig-standards — pull request #1 by donquixote (2013-08-02 03:45:43+00:00)
Title: Autoloader spec: Rewrite, again

Hi Paul,
I had already given up, but.. seeing that this is still being worked on, here is another approach.
(As you probably know, I am on the "standalone classloader PSR" front, I don't like mixing with resource PSR.)

What has changed?
- Use well-known terms of the PHP world, where possible. Avoid introducing unnecessary made-up terms.
We are looking for a class, we include a file. The class has a FQCN and is in a namespace, the file has a file path.
- Don't specify details of the algorithm, only specify the "outside" behavior. Which class is requested, which file is included.
- classes, namespaces and directories are not just strings, they are also also concepts with a meaning. Refering to these can free us from wasting time on implementation details - e.g. trailing slash vs no trailing slash.
- Be clear on the scope, the "when" and "if". Don't just say "must include that file"; but "if/when .., then it must/may include a/that file".
- Suitable wording for cases with multiple possible options. Don't just say "the prefix" but "one of the prefixes" or "if there is any prefix, then.." etc.
- Be clear on whether we are talking about the autoloader behavior, or about classes in the library/code.
(I am not sure if we should explicitly write "library")
- Alternative wording for the "mapping" stuff. (see below)
- Make sure we are not too restrictive. (see below)

### What is wrong with "mapping"?

The "must be mapped to" is ambiguous. As a noun, "map" or "mapping" usually means some kind of lookup array that connects one value to another value. As a verb, "map" or "to be mapped" can mean different things: The act of creating a "map" array, or the act of looking up a value in a "map" array. As an adjective, "to be mapped" can mean the existence of a value for a given key in a "map" array.

Besides, "mapping" is not the most useful term if one key can be connected to more than one value. In this case, "associated" might be the better term.

We also don't really explain where the "map" comes from. In fact we don't really know either, and this is fine - it is out of scope. The only thing we should avoid is the idea that mappings would be created out of the blue and ad-hoc, whenever the class loader is triggered. The map should be persistent between classloader invocations.

We don't actually have to enforce this, we could consider it out of scope. But at least we should not write the text in a way that the usual interpretation will be that of a map that is somewhat persistent.

The alternative I propose may not be the best, but at least I tried.

### Do not make restrictions beyond scope

The following things should be not illegal.
That is, they should be out of scope, so we do not want to accidentally make them illegal.
At the same time, we do not want to explicitly mention these things in the spec, because again, they don't belong there, they are out of scope.

A loader that does PSR-0 *and* PSR-4 (and other things, who knows), must not be made illegal by this spec.
Therefore, "classloader" now refers to an spl callback, or a part of that. E.g. in a multi-purpose loader, this would be the part that deals with PSR-4. Or there could even be multiple parts that all do PSR-4.

A file that cannot be loaded, or does not have a matching prefix.
The old spec said "the prefix must be matched". This would make any loader illegal that does not have a matching prefix for really every class it may ever be called with.
So, instead, we say IF a file is included, THEN it must "match".

A file is not included, because something else has priority.
E.g. a PSR-0 or classmap class has priority over a given PSR-4 match.
This may lead to a file not being included, and a class not being loaded by this loader.
The loader should be allowed to do this.
So essentially, we cannot say "must include that file", because it would make these loaders illegal.

#### What does "out of scope" even mean?

I remember having this disagreement with phil. What is the difference of "allowed" vs "out of scope"?

"out of scope" means we don't talk about it, but we leave it open for others to introduce a restriction.
"allowed" could mean you have the ultimate human right do do something, and stopping you from that would be illegal.

In some cases we have to be specific to restrict the scope to where we want it to be.
E.g. "drinking is illegal" would refer to any substance, any person (or animal?), any time, any place.
To avoid this, we have to say "people under 18 in Belgium may not drink alcohol in a bar on the weekend". (no idea if that law exists)

Sometimes the scope is clear from the context. E.g. it is clear we are talking about classes in PHP here, not about classes in C# or in Java or anything else.