This week several minor bug fixes were applied to the dev branch as version 2.7.1 and this will likely be pulled into the master branch next week, replacing the current 2.7.0 stable version. The big news of this week is the introduction of the ProcessWire PHP Coding Style Guide, which is something that several have asked for over time, and now we've finally published it!


Introducing the ProcessWire PHP coding style guide

The ProcessWire PHP coding style guide represents the coding style preferred for the ProcessWire core. It is also recommended (though certainly not required) for 3rd party modules and other code using the ProcessWire API, unless an existing coding standard is already in place or preferred. Use of the coding style guide is however requested for code submissions (pull requests) to the ProcessWire core.

The ProcessWire coding style guide is based on PSR-1 and PSR-2, but with several important differences and additions (some ProcessWire specific). Some notable differences from the PSR style guides include:

  • The style guide delves into many things that are absent from the PSR style guides, such as operator usage, documenting code, string and quote usage, multi-language translation, and more. The style guide also gets into ProcessWire-specific topics such as hooks, translatable strings and more. Essentially, it's quite a bit more thorough in many areas.

  • The style guide advocates for consistent usage of open and close brackets, regardless of context. The PSR standards advocate different bracket usages depending on context (control structure vs. method declaration and class declaration).

  • The style guide advocates using tabs as tabs, rather than using groups of spaces to look like tabs. The PSR standards advocate using groups of spaces as tabs, and with certainly good reasons. But in our mind, using spaces as tabs is kind of like using <br> tags to separate paragraphs in HTML… convenient, but semantically incorrect. Conveniences aside, we'd rather use spaces for spaces and tabs for tabs, sticking to the original purpose of these characters.

  • The style guide advocates using consistent spacing around control structures, closures, method and function declarations, and calls to them.

  • We believe code documentation is just as important to code style as the actual code, so our style guide covers this with an emphasis on the PHPDoc standard. The PSR standards don't cover this aspect, likely because their context (PHP in general) is broader than ours (PHP with ProcessWire), and it may be considered out of scope for the PSR standards.

In general, we feel that for developers using ProcessWire, the ProcessWire coding style guide offers a more consistent vision of code style relative to the PSR guides. That's in large part because we don't advocate changing usages of spacing, brackets, parenthesis or naming conventions for different code contexts. Perhaps there is value in having such context changes in the bigger PHP picture, but when it comes to ProcessWire we prefer greater consistency in these areas, and you'll see that reflected in the style guide.

It's worth noting that the PSR-2 standard has wide adoption and is used by many projects. If the Processwire Coding Style Guide doesn't suit your needs, we'd certainly suggest using the PSR-2 style guide. While we feel PSR-2 is a compromise in many ways, that can also be a good thing in the bigger PHP context.

Consider this version 1 of the coding style guide, and we may have more to add or change as time goes on. If there's anything you think we've missed or anything you have reactions to, please let us know too.

See the ProcessWire Coding Style Guide


Do as we say, not as we do ;-)

After looking at the coding style guide, you might notice that even the ProcessWire core doesn't always follow these rules, at least not all of the time. We wrote it as much for us as we did for others that have requested it. As we shift more into ProcessWire 3.0 development we'll be putting more emphasis on making sure our own code always lives up to all the recommendations in the style guide. We have a lot of optimizations still to make, especially when it comes to making sure everything is covered with PHPDoc.


Vote for ProcessWire as “Best CMS for Developers” at CMS Critic

ProcessWire has been nominated as the Best CMS for Developers at CMS Critic, and the awards are now open for voting. If you have a minute, and believe ProcessWire is the Best CMS for Developers (we do!) please go there and vote for ProcessWire. Thanks for voting!

That's all for this week! Hope that you all have a great weekend/week ahead and remember to visit the ProcessWire Weekly this weekend.


Comments

  • Gabriel T

    Gabriel T 2 years ago 20

    Are there any tools to automate the formatting required by this guide?
    A Sublime Text plugin, maybe :D ?

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.