PHP-FIG: PSR 1 and 2 Accepted

By | June 4, 2012

Earlier today, the PHP Framework Interoperability Group accepted two standards recommendations:

  • PSR-1, “Basic Coding Standard”, passed with 17 in favor and none against.

  • PSR-2, “Coding Style Guide”, passed with 13 in favor and 4 against, 1 abstaining.

There’s been a lot of commentary about these proposals over the past two weeks, some of it positive and some of it negative. Here’s a taste:

I’d like to address some of the negative commentary here; I don’t expect to change many minds, but I do want to make sure the comments are answered.

(Full disclosure: I’m a voting member in the group, and have been since its beginning. I did not introduce the original measure that led to PSR-1 and PSR-2; that honor belongs to Klaus Silveira, a non-voting member. However, I did shepherd the PSR-1 and PSR-2 recommendations through the voting process to their acceptance by the group.)

Regarding The Group

Q: What the hell is the “PHP Standards” group? I’ve never heard of it before now.

The name isn’t “PHP Standards” any more; it’s the “Framework Interoperability Group” (FIG). We did start off as “PHP Standards” because, well, we all worked in PHP, but realized pretty quickly that the name was too broad, and renamed it the “Framework Interoperability Group.” (That name turns out to be too narrow, as the group now has representatives from library and CMS projects as well.)

The idea behind the group is for project representatives to talk about the commonalities between our projects and find ways we can work together. Our main audience is each other, but we’re very aware that the rest of the PHP community is watching. If other folks want to adopt what we’re doing, that’s cool, but it’s not what we’re focused on.

Q: Then why is the mailing list called “PHP Standards” instead of “FIG Whatever” ?

The Google Groups mailing list does still bear the original name of “PHP Standards.” It’s a legacy issue. To reduce continued misconception, we need to change that to the reflect the new name, but I don’t know when that will happen. (The Github repository for the group does use the new name.)

Q: Why are you guys so secretive and closed?

Just because you haven’t heard of the list, doesn’t mean we’re keeping it a secret. There’s a lot of discussion groups out there. ;-)

We did start out with a closed list years ago, but we opened it up pretty quickly thereafter. Anyone can join in and make their voice heard.

There’s nothing “closed” about the list or the decision-making process. Anyone who wants to drive the group to open even further is free to join the list and make suggestions for doing so. (I’m looking at you Anthony Ferrara. ;-)

Q: So once I join the list, I can vote on PHP-FIG Standards Recommendations? Sweet!

Sorry, no. The only people who can vote on a measure are the voting members. But anyone can discuss the measures on the list.

Voting is reserved for people who represent a member project. If you want to vote, then participate on the list for a while, and submit your project for membership. If enough other existing members vote in favor of your request, then you’re in and can vote on measures thereafter.

Q: I knew it. You’re a bunch of self-appointed elitist jerks.

“Self-appointed” is probably accurate; “elitist jerks” we can discuss. ;-)

Regardless, the group is currently composed of representatives who have volunteered from the following projects:

  • Agavi
  • CakePHP, CakePHP 2
  • Chisimba, C4
  • Composer, Packagist
  • Doctrine, Doctrine2, et al.
  • Drupal
  • eZ Publish
  • FLOW3
  • Joomla
  • Lithium
  • PEAR, PEAR2
  • phpBB
  • PPI, PPI2
  • Propel, Propel 2
  • SabreDAV
  • Solar Framework, Aura Project
  • Symfony, Symfony2
  • Zend Framework, Zend Framework 2
  • Zikula

Some of these projects are large, and some are small (for various definitions of “large” and “small”). They’re all very different from each other in lots of ways, and have very different ideas on how to approach various problems.

Q: Whatever. I don’t need you guys telling me what to do. If I don’t want to follow your so-called “standards” then you can’t make me.

We’re not trying to make anyone do anything. Hell, not even all of the member projects subscribe to all of the standards recommendations. What we’re trying to do is find commonalities between the projects so that we (the members) can all eventually share similar practices and techniques.

Regarding PSR-1 and PSR-2

Q: Who the hell are you to define a “standard” for coding style?

It bears repeating: the primary audience for the recommendations is the group itself. If others in the wider PHP community want to adopt the recommendations, I think that’s a positive outcome, but it’s certainly not mandatory in any way.

Q: Coding style is all personal preferences. How can you make a “standard” out of them?

On one hand, you’re right: a style guide is a collection of preferences. On the other hand, it’s not exactly personal when a lot of different projects run by a lot of different people indpendently arrive at a similar set of rules.

Q: How did you come up with this stupid “standard” ?

Somebody on the list mentioned that it would be nice to have a single style guide for member projects, code in different projects would look similar. He included an initial set of guidelines. Several of the voting members agreed that it was a good idea, and we expanded on that initial set of rules.

After some back-and-forth, someone else brought up the idea of doing a survey among the member projects, to see exactly how many projects are following which points of style. We ended up with 22 projects in the survey. The results made it pretty clear what the majority of projects were using for their standards.

Q: Only 22 projects, out of the whole world of PHP code? That’s not a valid sample size!

Recall that our primary audience is the group itself. If you have the time, energy, and inclination to do a survey of defined coding styles across the entire PHP community and analyze the results using a statistically valid methodology, I will be very interested to see your report on it.

Q: Where’s this survey at? I bet you’re hiding it so nobody can see the results.

Here is the original Google spreadsheet. It is also incorporated into the PSR-2 document as an appendix.

Q: Oh my God, you’re saying we MUST use spaces and not tabs? But I hate spaces!

If the majority of surveyed projects had used tabs, the recommendation would have been to use tabs. A super-majority (two to one!) use spaces, so that’s the recommendation.

Neither tabs nor spaces has any moral superiority over the other. If you hate spaces so much that you simply cannot adjust to them, that’s fine. Your project won’t adhere to PSR-2, but then, nobody says you have to.

Q: Why can’t the rule be “use either tabs or spaces, as long as you’re consistent within a project?”

The focus of these recommendations is not “indivudal projects by themselves.” The focus is on “working with/on lots of different projects.” If one project wants to use tabs, cool; if another wants to use spaces, fine; but if you end up working on both, you want the rules to be the same for each one. Thus, we have to pick something to apply identically across lots of projects at the same time.

Q: The standard is inconsistent: braces in one place sometimes, and in another place at other times. Dumb!

I’ll refer you back to the survey; the brace rules are what the majority of member projects have already picked for themselves. (A minority of projects consistently put braces on the same line, and a different minority consistently put braces on the next line, but there was no majority that consistently put them in the same place.)

Q: Wait, you mean the rules are defined by a survey, and there’s no design involved at all? Brain-dead!

The “design” portion happened in the individual member projects. The survey identified common elements of design across those projects. The follow-up discussions refined the broad commonalities, and the proposal codified them.

Q: There are lots of other standards out there. Why not just pick one of those?

In a way, we did, although in a very roundabout way. The survey revealed that the majority of member projects are already adhering to a large subset of the PEAR standard (itself the oldest existing common standard in PHP land.)

Conclusion

If you have other questions or comments, please leave them below. I know this kind of topic inflames passion, so please, follow the example of the FIG members: be civil and constructive. I reserve the right to police comments according to my own whims. ;-)

21 thoughts on “PHP-FIG: PSR 1 and 2 Accepted

  1. Richard Ayotte

    I like the standard, even with the few inconsistencies like the braces. The few things that I would add or change would be:

    Drop the first switch, case indentation. I don’t find the extra indentation helpful.

    switch ($expr) {
    case 0:
        echo 'First case, with a break';
        break;
    case 1:
        echo 'Second case, which falls through';
        break;
    default:
        echo 'Default case';
        break;
    }
    

    I usually append lines to the bottom, not insert at the top so a leading instead of trailing comma make more sense. It also makes the commas more obvious and helps reduce the number of errors caused by leaving extra trailing commas or forgetting commas.

    $longArgs_noVars = function (
        $longArgument
        , $longerArgument
        , $muchLongerArgument
        , $muchMuchLongerArgument
    ) {
       // body
    };
    

    I also noticed that WordPress is missing from the list of participating projects. I would have thought that they would have been more involved.

    Reply
  2. pmjones Post author

    Hi Richard:

    Everyone has their preferences.

    Regarding switch/case, that was one of the options (it’s the PEAR standard, and I use it myself). The majority of projects surveyed use the extra indent, so that’s the rule now (and I’ll be switching my own work to use it).

    Regarding WordPress (and other projects not represented), they are free to join if they feel like they’ll get something out of it.

    Reply
  3. Jon

    Regarding braces, I believe that classes and methods should use the brace on a new line (ie as the guide says) because it helps to clearly define those blocks. Ifs, fors, etc become too clunky if the brace is on a new line. Again, I guess it’s what I like, but I’m glad these guides have been created – it’s a good step forward I believe.

    Paul – regarding spaces versus tabs, maybe you can add a note to your article in favour of spaces that 1) git diffs are easier to read and 2) code on GitHub is viewed easier with 4 spaces because it’s more compact. I was against spaces in the beginning but I believe they are superior now.

    Reply
  4. John Steele

    Coming from several decades of C programming (which of course PHP and most serious languages are written in) this is a very old conversation. Every news agency was all over Jobs passing, almost none covered one of the greatest programmers of all time – Dennis Ritchie.

    Put the brace on the line with the conditional, and indent (tabs are obviously superior in typing time and storage, but if you need spaces …) the logic that follows below it.

    
    if($this) {    // the PDP does exist
        // there was R.
    }
    
    // there was also K.
    echo 'K & R - Except no substitutes.';
    
    switch($said) {
        case 'Nuff':  echo 'Marvel-ous.';  break;
        default:  echo 'Jobs says you no use pointers';
    }
    
    Reply
  5. MrGrygson

    Nice article! Now, I’m trying to find something simillar about comments.

    Reply
    1. pmjones Post author

      Some of the guys on the list claimed they were putting together a recommendation on docblocks and comments; you may wish to join the list and ask about it directly.

      Reply
  6. Tony Marston

    This is yet another set of standards that I will *NOT* be following. The idea that you think that you can dictate how everyone should write code just so that it looks the same as code you write is preposterous.

    I agree with the notion that code should be readable, maintainable and properly structured, but your petty little rules just annoy the hell out of me. Programming is an art, not a science, and following a set of arbitrary rules in a dogmatic fashion is absolutely *NO* guarantee of becoming a good programmer.

    I am pragmatic, not dogmatic, so it’s results than concern me, not rules. Provided that the code is readable is all that matters. If someone says to me “your code is unreadable because you’re using the wrong case for for function and variable names” my reply will consist of two words, with the second being “off”.

    Reply
  7. Pingback: PSR-0 PSR-1 PSR-2, Drupal, and You! | Devnotes

  8. Marty Penner

    Thanks for this, Paul. I appreciate the work being done here. It’s unfortunate that some folks here are misunderstanding the purpose of the standards. As stated in the preface to the PSR1 coding standard, the standard:

    “…comprises what should be considered the standard coding elements that are required to ensure a high level of technical interoperability between shared PHP code.”

    This set of standards will be of less worth on a single project with no dependencies (though PSR-1 will still be valuable to keep side effects and declarations separated). The value increases when there are multiple libraries or frameworks in use. I agree, Tony, that these “rules” do not guarantee good programming, but they never claimed to.

    As far as code readability, the PSR2 coding guide states:

    “The intent of this guide is to reduce cognitive friction when scanning code from different authors. It does so by enumerating a shared set of rules and expectations about how to format PHP code.”

    It’s not a question of whether or not code is readable; one could argue that virtually all code out in the wild is readable. A better question would be “how” readable. I don’t know any developer who would claim that some code is unreadable, simply because the capitalization doesn’t follow the standard. There are many other, more important factors that make code unreadable long before capitalization becomes an issue. But the fact is, when multiple vendors/organizations follow the same standards, it makes a happier time for everyone.

    Reply
  9. evilthug

    These documents are very helpful. I don’t understand some of the negative comments here. This isn’t required. It’s helpful if you want to play well with others. Other professions are far less forgiving.

    Reply
  10. LC

    “This is yet another set of standards that I will *NOT* be following. The idea that you think that you can dictate how everyone should write code just so that it looks the same as code you write is preposterous.”

    @Tony Marston: Did you even read the post?! Nobody is trying to dictate anybody. It’s a set of standards for a groups of projects. You can choose to follow them if you wish. Rhetorical question by the way.

    Personally, I think in general they’re great. Yes there may be differences here and there depending on your project/team/preference, but overall I certainly think it’s positive, and for the sake of being able to write code in a manner that would be “compatible” with these large/popular projects, I can’t see that being a hindrance to me as I progress as a developer.

    So much hate. Damn. That’s like being outraged that Red Bull introduced a new flavour that I didn’t like. Just don’t drink it. Damn.

    Reply
  11. Pingback: PHP i standardy PSR na Mariusz Tarnaski "MariuszT"

  12. AntoxaGray

    It’s better to have standart than not to have it.

    p.s. I hate spaces, imma the tab guy.

    Reply
  13. Typical

    I’m so sick of these goddamn stupid rules especially the tabs-spaces one. Also 80 chars wide max? really? Computers back in the late 80s were 80 columns. This readability bullshit has gone way to far. Way too goddamn far.

    Reply
  14. Daniel Craig Jallits

    @Typo regarding your stated kvetch hard/soft limits

    I would like to point out that line limits have absolutely nothing to do with screen resolutions, but legibility for the human eye and mind. Actually 80 characters is a bit much as most researchers claim optimal line length should be between 50-60 characters.

    Reply
  15. Jair Humberto

    PSR-0 is very ugly ¬¬. Underlines in class names? Why don’t people use namespaces instead? And use class names with first capital letter in each word? With a pattern like ([A-Z][A-Za-z0-9]*)? It’s more usual.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *