[PSR-4] Back on Track

[Phil Sturgeon]

So we hit a little rough patch there, but solutions have been made.

After lots of people talking past each other, providing shoddy examples then trying to prove or disprove those examples, we got a more constructive conversation on the go on IRC. Most of the conversation for the longest time was about official v alternative proposals. It took us a while but we got most folks to agree to stop making alternative proposals and try to work on the main version. While the document is in review we're just trying to take care of concerns or misunderstandings, and that is the only way to make progress.

 

Alternatives are taking everything back to the drawing board. It's never "well what is wrong with this alternative" that is important, it's a question of "what is wrong with the official, that cannot be changed with wording tweaks?". Every alternative proposer has always said the official document cannot be changed to assuage their concerns, but in the end, every time, we've done it.

The real concern currently with PSR-4 is that people believe we are specifically defining "One True Algorithm", which due to the way it has been wording looks like a collection of sequential pseudo-code which must be run on-the-fly each and every time the autoloader is hit by PHP. 

Multiple people in the group have said they thought this to be the issue.

The PSR-4 document never said that. We are not defining an algorithm.

It might have looked like it did, but that was a wording issue. So, now that we're all on the same page we can easily fix this. I asked people to get onto IRC and was joined by Andreas Hennings, Beau Simmens, Justin Hileman and of course Paul M Jones. We talked for so long that if we do that again I'll probably be fired. 

Seriously it was insane. But all the time we were discussion small iterative changes to various bits of wording that everyone could be happy with, which covered several main themes:

1. Replacing anything which sounded like pseudo-code with generic terminology which describes (and still requires) the end effect.
2. Limiting implementation specific content to that which is fundamentally required for interoperability, and relevant to the user.
3. Removing MUST and SHOULD rules which applied only to the autoloader developers. Now we explain what will happen with the examples.
4. Generally make the document feel like it is applicable to everyone, not just autoloader developers. 
5. Avoided using any terms like "library" or "developer" because you cannot put everyone (or anything) using PSR-4 into boxes like that.

The PRs:

https://github.com/php-fig/fig-standards/pull/208

https://github.com/php-fig/fig-standards/pull/209

https://github.com/php-fig/fig-standards/pull/211

And now, the updated official proposal:

https://github.com/php-fig/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader.md

Andreas and myself have some issues left to work out (with the document, we're not dating) but generally we're on the same page now which is wonderful.

I am hoping these recent changes will bring Bernhard back into the fold as I believe them to be inline with his thinking - regardless of his failed attempts to explanation things previously. A conversation based on misunderstandings will never get far, and it took both sides of this conversation several hours for each of us to understand each others points. I know it was only one example of an alternative algorithm, but classmap is totally allowed by this version (as it was before).

This should also bring back Drak, who has been generally asking for "No Implementation Details". We have SOME, but these cannot be removed. 

For example I as a user really want to know that I don't need to catch exceptions from the autoloader. It is also important to state that none will (or should) EVER be thrown. If a user was using autoloader A which did not throw exceptions, but autoloader B started, I get some extremely destructive behavior introduced to my application which I was not expecting. So, this clause will stay.

-----

We're getting there people. You can pretty much ignore any of those outstanding conversations you have in your inbox about PSR-4. I mean, feel free to read everything, but you really don't need to. I'll update the meta doc shortly with links to formative conversations, but most of this happened on IRC (to avoid spamming you as badly as you've already been this last week).

Let me know if you have any feedback. Try me on IRC first.

[Donald Gilbert]

The definition of namespace prefix slightly contradicts with the inline examples. I think it was merely an oversight that the words "trailing" and "leading" were swapped.

It should read: (note the change in the second sentence)

• namespace prefix: One or more contiguous leading namespace parts with namespace separators. Given an autoloadable class name of Acme\Log\Writer\FileWriter, a namespace prefix may be Acme\, Acme\Log\, or Acme\Log\Writer\. A namespace prefix will include a trailing namespace separator, but will not include a leading namespace separator.

Other than that, it's looking good. Great work everyone putting in the extra effort.

[Amy Stephen]

Just wanted to add a good point raised by Drak so we don't forget it.

The suggestion was to move Section 5 out of the PSR. If I remember correctly, part of the new process and documentation approach, or a recent poll (?), calls for using a linked to reference for such material.

The section is clearly marked "Example" and it states the following:

The following examples MUST NOT be regarded as part of the specification.

It is followed by at least a page of specifications that are merely descriptive of one way to do it, but do not have any real relevance on compliance. In other words, instructional, informative, not conformance related. 

As a secondary point, it would be desirable to use a github repository where community can issue a PR for consideration of change.

Phil indicated this would be considered and asked that we hold on the proposal for now to allow time for others to review the new document and offer suggestions. (Which makes sense. =) ).

[Amy Stephen]

Apologize for posting this twice. I moved the two new points raised into this thread where Phil has requested we respond about PSR-4. Given the confusion and earlier frustration, it would be good to have a complete list in a single place of issues raised. That way, everyone knows concerns were addressed.

Suggestion in response to Andreas to use PHP terms, rather than create new terms for the PSR.

On Tuesday, October 22, 2013 12:59:39 PM UTC-5, Amy Stephen wrote:
Wherever possible, it would be best IMO, to use established official terms. In the case of namespaces, the PSR should link to and discuss namespacing using official terms.

• A "namespace prefix" in the PSR sense is called a namespace.
• Often a namespace will also be called an identifier.
• What is sometimes called a "slash" in the PSR sense is called a namespace separator.
• A qualified name has at least one namespace separator, ex. Foo\Bar
• A fully qualified name has a leading namespace separator. ex \Foo\Bar
  
• A class is referred to as a qualified or unqualified class name, dependent upon whether or not the leading namespace separator exists.  

Further, if there is a condition where a new term might be beneficial, it would be preferable, IMO, to issue a PR on the PHP documentation (or however one recommends such changes) to introduce the term and its associated definition so that all terms in a PSR are a part of the documentation. 

Not only will such an approach reduce unnecessary debate but it encourages using the official documentation and has immediate meaning for those who understand PHP.

Note: IMO, there is no reason for a PSR to refer to, discuss, or address a fully qualified class name since that value is never passed into a class loader. It's only relevant to PHP and resolved before the class loader is ever involved.

[Andreas Hennings (donquixote)]

A few things to be changed:

"resource"

We want to return to the "file" and "directory", and no longer talk about resources.

If this is not flexible enough, we could use the definitions section to clarify that our understanding of "file" and "directory" extends beyond the everyday meaning.

It is better to lose a bit of edge case flexibility than alienating 90% of the readers with unnecessarily abstract language.

"namespace prefix"

The definition and usage of this depends on a class. Instead, we want a relationship of namespace prefixes with directories that is _independent_ of a class.

We could do this either by extending the definition of "namespace prefix" to explain its standalone meaning, or introduce a new term.

I had "terminated namespace name" once, which I explained as namespace name with appended namespace separator.

We could say a namespace prefix, if not in the context of a specific class, means a string that could be a prefix of a class and ends with "\\".

Autoloader details?

The main issue here has been solved, by saying "... so that the following autoloader steps WOULD do the job".

I still think we could do without the steps and say this in another way. Not because of logic and semantic problems, but to get to a more elegant way to say it.

Unlike with the previous doc, this is now realistic to propose and discuss as a PR, instead of as a separate proposal.

[Paul M. Jones]

On Oct 22, 2013, at 2:34 PM, Amy Stephen <amyst...@gmail.com> wrote:

> Wherever possible, it would be best IMO, to use established official terms. In the case of namespaces, the PSR should link to and discuss namespacing using official terms.
> • A "namespace prefix" in the PSR sense is called a namespace.
> • Often a namespace will also be called an identifier.
> • What is sometimes called a "slash" in the PSR sense is called a namespace separator.
> • A qualified name has at least one namespace separator, ex. Foo\Bar
> • A fully qualified name has a leading namespace separator. ex \Foo\Bar
> • A class is referred to as a qualified or unqualified class name, dependent upon whether or not the leading namespace separator exists.

The problem I see with using the PHP vocabulary is that it is not sufficiently specific.

For example, a "namespace" may be *any portion* of the namespace portion of a class name, including a middle portion: given Foo\Bar\Baz\Dib\Qux, a valid namespace therein is "Bar\Baz".

Happy to be corrected here.


--
Paul M. Jones
pmjo...@gmail.com
http://paul-m-jones.com

[Andreas Hennings]

2013/10/22 Andreas Hennings (donquixote) <lemon....@gmail.com>

A few things to be changed:

"resource"

We want to return to the "file" and "directory", and no longer talk about resources.

If this is not flexible enough, we could use the definitions section to clarify that our understanding of "file" and "directory" extends beyond the everyday meaning.

It is better to lose a bit of edge case flexibility than alienating 90% of the readers with unnecessarily abstract language.

"namespace prefix"

The definition and usage of this depends on a class. Instead, we want a relationship of namespace prefixes with directories that is _independent_ of a class.

We could do this either by extending the definition of "namespace prefix" to explain its standalone meaning, or introduce a new term.

I had "terminated namespace name" once, which I explained as namespace name with appended namespace separator.

We could say a namespace prefix, if not in the context of a specific class, means a string that could be a prefix of a class and ends with "\\".

Autoloader details?

The main issue here has been solved, by saying "... so that the following autoloader steps WOULD do the job".

I still think we could do without the steps and say this in another way. Not because of logic and semantic problems, but to get to a more elegant way to say it.

Unlike with the previous doc, this is now realistic to propose and discuss as a PR, instead of as a separate proposal.

"conforming autoloader":
suggested change: Just define "autoloader", by "a function named __autoload() or a callback registered with spl_autoload_register()."

Whether it is "conforming" should be said further down in the spec, not in the definitions. Or should it?

[Amy Stephen]

There certainly could be a namespace Bar\Baz contained within folders so organized, but to the best of my knowledge, that namespace would have no relation to Foo\Bar\Baz\Dib\Qux. IMO, there is no relationship there, therefore no term needed to define it.

Happy to be corrected on that point, as well.

If we do find terms needed and undefined, I would volunteer to have those somehow added to the documentation. Probably should figure out how to do that, anyway.

Thanks!

[Amy Stephen]

Paul -

Looked at the definitions closely and most of them are using PHP terms, so very good work on that - it really is pretty clean.

Wanted to point out sub-namespaces as a possibility for namespace prefix. It describes a hierarchy approach and it might fit our needs.

Thought I'd toss it out there for consideration.

On Tuesday, October 22, 2013 2:55:54 PM UTC-5, pmjones wrote:

[Amy Stephen]

PR that attempts to substitute PHP terms where new terms were used. There are about a dozen commits, each made to clarify a certain point. Anything to do with a process is gone. All that is described is the input to a black box - and the output from the black box.

https://github.com/AmyStephen/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader.md

I have no expectation of anything and only hope something might be helpful. Personally, I think it gets back to some of the clarity we enjoyed early on that has been lost in trying to satisfy lots of different ideas. But, that's just my opinion. I have no expectation of how others might feel.

One important part I would appreciate consideration on is the terms. Those are much more inline with PHP. I think that will help us later.

Appreciate everyone's efforts.

[Phil Sturgeon]

 Self-Throttling.

[Marc Plotz]

Apologies for butting in but regarding the Section 5 example file - I just took the example autoload class (https://github.com/php-fig/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader-examples.php - class Psr4AutoloaderClass) and implemented it into my framework without much effort. I had originally built the framework to implement PSR-0, but wanted to test the implementation of PSR-4 as it stands. To be honest I was very impressed not only with the simplicity of the implementation but also the new class structure that not only makes more sense, but just looks better. I do understand that this is not a part of the specification, but it works. Thanks guys, keep up the good work.

On Tuesday, October 22, 2013 4:14:48 PM UTC+2, Phil Sturgeon wrote: