Recommended PHP style guide?

[MarcC]

I like to use the style of whatever system I'm working with, be it a language, app framework or CMF or whatever. I had been using the CodeIgniter style guide previously, where you use Allman-style indenting like:

if (blah)

{

stuff

{

instead of

if (blah) {

stuff

}

I also had been using underscores in my variables. But I noticed that Ryan uses camel case and the non-Allman indenting (whatever it's called). So I started mixing the two sometimes and that's not good.

Is there a style guide (external to the ProcessWire project) that fits this style? Guessing not, but just wondering since CodeIgniter has one.

[apeisa]

This is interesting topic, since there is this PSR movement going to make different PHP-frameworks and applications to follow same style. I do like the PW standard, but it is pretty far from the PSR-2: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md

Biggest differences being using tabs instead of 4 spaces and not using Allman-style indenting. I have always preferred tabs, but it seems that it is good way to mess with version control (lot's of white space diff when people mess with spaces and tabs). Spaces are more bulletproof on that regard.

Of course PSR-stuff are just recommendations, but looking at the big picture and php-community at large, it might be a good idea to slowly gear towards that? Or what says Ryan?

[SiNNuT]

You could look at the PHP Framework Interop Group and their PSR-1 and PSR-2 coding standard and style guide.

There are a lot of of big names amongst their members so it does have some weight to it.

Fun fact: they settled on using 4 spaces for indenting, which was cause for some debate.

http://paul-m-jones.com/archives/2312

It would be good for PW to encourage the use of some coding style. This will benefit stuff like modules greatly in the long run.

- darned, beat to it -

[ryan]

PW's coding style is visible in any core file. But it's the same idea whether we're talking about code, graphic design, architecture or really anything someone would create:

Don't put in extra crap that doesn't help communication

When it comes to code, that translates mostly to not adding extra unnecessary bytes:

• Avoid having an opening bracket "{" on its own line. Instead, just use a single space before an opening bracket. Only closing brackets "}" should be on their own line.
  
• Avoid use spaces for indentation, just tabs. This is what tabs were made for, not spaces. Use just one tab per indentation, of course.
  
• Avoid extra spaces around parenthesis unless you think it's really necessary. For example, it's preferable to use function(a, b) not function ( a, b )
  
• Put a space after a comma, just so the comma doesn't visually melt into one of the adjacent letters.
  
• Don't put a closing PHP tag "?>" at the end of a file.
  
• Use camelCase for most variable and function names except for when the variable resolves to a database column or ProcessWire 'name', then use lowercase and underscores.
  
• Use camelCase for class names except always have the first character be uppercase, i.e 'CamelCase' (there may be a more specific term for this).
  
• Put a space before and after the concatenation operator, as it's small and disappears (or becomes a sentence period) too easily. For example use "a . b" and not "a.b".
  
• And of course, comment as much as possible. Comments are bytes that are always appreciated for communication. Outside of internal comments within the body of functions/methods, PHPdoc style is the standard we prefer.
  

Honestly the biggest one for me is just the opening bracket thing. I can't follow code that contains opening brackets on their own line. It makes the opens and closes so visually similar that I can't can't easily tell them apart. It could be that my eyes aren't great, but at least for me that coding style creates legibility problems. I have to "fix" code before I can read it. With the style I'm using, when I see a bracket on a line (before I see the nuances of the serifs), at least I know it is always closing something.

[Pete]

I like this because it was already what I was doing

The closing PHP tag is something I've picked up from coding with PW.

[ryan]

Btw, I'm not suggesting this is the style everyone should use in their 3rd party modules unless they want to. I understand that there are different preferences in this area. Of course I'm not going to shoot down anyones preferences. So this standard is just for PW core stuff. I do see us pursuing the PSR-0 standard with the way we use namespaces in the near future, and we already have a lot in common with much of PSR-1 and PSR-2. But I don't fully agree with all the standards recommended in PSR-1 & 2. I think PSR-1 & 2 would mainly be worthwhile as a compromise for a leaderless project or a compromise for a project with a lot of leaders that don't agree.

[DaveP]

Use camelCase for class names except always have the first character be uppercase, i.e 'CamelCase' (there may be a more specific term for this).

Methinks PascalCase.

[jbroussia]

One of the first reasons I fell in love with PW was the coding style, because I use the same rules Though I'm only a casual PHP programmer, I'm mostly programming in Delphi, but the same rules apply for me.

[SiNNuT]

Btw, I'm not suggesting this is the style everyone should use in their 3rd party modules unless they want to. I understand that there are different preferences in this area. Of course I'm not going to shoot down anyones preferences. So this standard is just for PW core stuff. I do see us pursuing the PSR-0 standard with the way we use namespaces in the near future, and we already have a lot in common with much of PSR-1 and PSR-2.

Definitely +1 for PSR-0 because that seems to me like having a lot of benefits and has gained a lot of traction with stuff like Composer|Packagist. It just seems like a great idea that you can easily and reliably add third party packages to a PW project. (and possibly vice versa?)

But I don't fully agree with all the standards recommended in PSR-1 & 2. I think PSR-1 & 2 would mainly be worthwhile as a compromise for a leaderless project or a compromise for a project with a lot of leaders that don't agree.

Projects aren't isolated islands. A lot of projects have the potential to be a mix and match of tools. Maybe PW, a templating system and your favorite validation package. Wouldn't it be neat if there was some sort of consistency between php projects? Don't argue about tabs vs spaces, snake_case or stuff like that but just settle on a standard and be done with it. Of course for a standard to be effective it should make at least some sense (you don't necessarily have to agree with everything) and have widespread adoption.

I wouldn't consider PSR-1&2 to be something very important but it wouldn't be bad if PW was compliant with it.

[ryan]

I wouldn't consider PSR-1&2 to be something very important but it wouldn't be bad if PW was compliant with it.

I like PSR-0 because it really does have a point and provides that potential for mix and match of tools as you mentioned. This is one I want to implement. But I don't feel the same about PSR-1&2, at least when it comes to some of the code style aspects. Intentional choices about some of these aspects were already made in ProcessWire. While some of these are subjective, I think the choices already made are far better than those in PSR-1&2. So PSR-1&2 won't ever be on the roadmap for the code I maintain, but PSR-0 will.

[Martijn Geerts]

From ProcessWire I learned the single quote markup attributes. I love those & never used it before I started to work with PW. For associative arrays i like closing parenthese receive an extra tab & the key => value pares to have 2 tabs.

$array = array(
       "foo" => "bar",
       "bar" => "foo",
   );

Now with ProcessWire, I struggle less with php style cause I like the style used in the core & modules.

[ryan]

This forum makes code indentation nearly impossible to translate, but this is how I usually do it with an associative array:

$a = array(
 "foo" => "bar",
 "bar" => "foo"
 ); 

[ceberlin]

I like the drupal codings standards a lot. Very clear and comprehensive:

https://drupal.org/coding-standards

[MikeB]

This is my first post to PW forum, hope it is a useful contribution.

I agree 100% with @ceberlin (not sure how to quote other users here).

Drupal code documentation is great and improving all the time, their coding standards are excellent.

I think that adopting some standards from them could help a lot here.

One thing in particular that bugs me is extra long lines of comments.

Would it be difficult to adopt an 80 character limit as Drupal has?

Also, a quick thanks to Ryan for his great work on an excellent system. I love the control, coupled with the freedom that PW gives me. Still a noob here, but loving every minute of the learning process.

[netcarver]

@mbrett5062

Hello, welcome to the PW forums, and thank you for posting!

I am not personally familiar with Drupal but I have become familiar with PSR-0/1/2 in the last year, along with composer and packagist (nice mention @SiNNuT) -- both of which I highly recommend as they have really helped me kickstart various projects since I found out about them.

@all

Although my (now historical) personal coding style preferences were not reflected in PSR-1 and PSR-2 I have now adopted them for all my PHP work and it probably took all of a week after making the decision to adopt them to start using them fluently. It really wasn't hard once the decision was made. As one of the maintainers of the Textile formatting library I was starting to get feedback from users who were dropping textile because it wasn't PSR-1 and 2 compliant. This meant that including the textile library in their projects was causing their projects to fail compliance tests (many folks were using things like phpcs as part of a CI setup.) Going PSR-1 + 2 compliant fixed that, widening my experience in the process.

Whilst I don't see PW being used in quite the same way as textile, having textile up on packagist has been a big win for our little project. As PW does come at things as a content management framework (not just a CMS) it may well reap some benefit from PSR-0 compliance and packaging for composer, as that will gain it more exposure and make it really easily accessible as a component in larger projects.

Bottom line: I'd love to see PW move over to at least PSR-0 compatibility and available via composer.

The other bottom line: My old preferences as to coding style were holding back textile - I'm now glad I switched.

[MikeB]

Another question/request around the subject of standards. As I go through my first week looking through PW coming straight from Drupal, I am finding it difficult to understand the structure of the file system/layout.

One thing that throws me, and that I think could be helped easily, is the naming of files.

i.e Looking through the blog profile that Ryan created, I am trying to grasp the structure, what comes first, what is pulled in and were is that used.

I believe the adoption of a simple structure would make a significant difference along with a simple documentation page explaining the structure.

So in the blog profile we have currently (for instance)

templates/main.inc  (markup for whole page)

templates/blog.inc   (functions to be used by markup)

templates/post.php (functions)

templates/posts.php  (functions)

templates/markup/post.php (markup)

templates/markup/posts.php (markup)

templates/widget-recent-posts.php (markup & functions)

Just a few for example

So while not impossible to understand I think a few simple changes could help new users grasp this easier.

Something like this.

Widgets in a widgets directory. As they are (or seem to me) standalone/reusable.

Template function files could be distiguished with  .tpl or .fnc  for example "post.tpl.php" or "post.fnc.php"

Markup files could be distinguished with .html for example "post.html.php" or something like that.

I realise that markup is in a "markup" directory, but thats not always apparent while editing.

I guess what I am trying to get to is that it's not immediatly apparent that a complete template consists of a functions file that creates data/variables for a markup file to output.

Also maybe the includes files could be in a seperate directory "inc".

I hope I am getting across my point, and not just showing my 'newbie' status.

Possibly there is nothing wrong with current system, and I just need a documentation page explaining what goes were and why.

Forgive me if this all exists and I just have not found/understood it yet.

[kongondo]

MikeB, welcome to PW and the forums!

 

Thanks for your input. I can understand why things seem to be confusing regarding structure of the file system/layout. I'll give you a straight answer. When it comes to profiles (e.g. the blog profile) and templating, there are no standard or recommended structures of the file system/layout . That is all down to the developer's preference!

 

So, in the blog profile, that is Ryan's preference for structuring the file system/layout. The blog profile is not part of the core. Have a look at the other profiles as well to see the differences in approaches.

 

If you look in the default profile (the default install) that ships with ProcessWire, it is also different (although that is necessarily so to align to a common structuring approach that would be familiar to those coming in to PW with some PHP background). Have a look at the followings thread for discussions about the different templating approaches people use. Some even mix approaches depending on need.

 

http://processwire.com/talk/topic/740-a-different-way-of-using-templates-delegate-approach/

 

So, in a nutshell, some of us prefer .tpl, .inc, others don't, others prefer to have a /views/ directory inside /site/templates/, others don't, etc., etc.

 

 

Having said that, when it comes to naming modules, there is a recommended approach: 

http://processwire.com/talk/topic/741-a-guideline-for-module-naming/

http://processwire.com/talk/topic/2394-how-to-present-your-module/

 

Edit: Members' attempts at MVC

 

http://processwire.com/talk/topic/4892-an-almost-mvc-approach-to-using-templates/

http://processwire.com/talk/topic/3587-templates-mvc-recursion-etc/

http://processwire.com/talk/topic/4947-the-pw-mvc-project/

http://processwire.com/talk/topic/4507-pw-best-practices-application-structure-form-handling/

 

Since you are comfortable with using the MVC pattern, this may be the way you want to go in ProcessWire too. ProcessWire is very much supportive of the MVC pattern, it's just that it doesn't require it. ProcessWire is providing your models, your template files provide your controllers, and you provide the views with the TemplateFile class (or some other view loader of your own if preferred). You can also choose to target some template files/pages as views and call $page->render() on them. If you are interested, the Blog profile does use an MVC-style approach and would be worth looking at. But after you spend some time with ProcessWire, I recommend finding the approach that best suits a particular situation rather than locking yourself down to using the same one all the time. ProcessWire is giving you a lot more in some areas than a typical MVC framework does, so you may find even faster and more maintainable ways to structure your code, depending on the situation.

http://processwire.com/talk/topic/4507-pw-best-practices-application-structure-form-handling/?p=44338 Edited February 19, 2014 by kongondo

[Martijn Geerts]

@MikeB,

How you structure your projects is up-to-you. The blog profile is just one way to do it. but there's no best way.

The beauty of processwire is that you as developer are totally free how to handle those structures.

[Joss]

Hi Mike and welcome!

The thing about PW is that it really does not have any fixed structure - it is up to you how you want to work.

There is one fixed rule, however - for a file to be available as a template file is must have a php ending and it must be directly in the templates folder.

And that is it. After that is is up to you.

For instance, I tend to have my main templates like home, basic-page, gallery - whatever I think I need. But things like my header and footer I put in an includes folder within templates and the just include them into the file.

Likewise, I split out much of my logic into functions in one or more functions.inc files and stick those in the includes folder.

It doesn't make any difference to PW itself, but it help me think my way through it.

PW is a lot less restrictive than drupal!

[adrian]

Mike,

The great thing about PW is that you can structure and name files however you want and put them in whatever subfolders you want. The only real restriction is that your main template files (the ones that relate to the templates you set up in the PW admin) must be in the site/templates directory. The only other restriction is that if you want to call any scripts directly, they need to be above the sitefolder. Other than that, you can do whatever you want. Feel free to add as many include folders and name files however best suits your workflow.

I haven't used Drupal so I may not be the best person to comment, and maybe you can do this is Drupal too.

Bottom line: I'd love to see PW move over to at least PSR-0 compatibility and available via composer.

It's on the roadmap:

http://processwire.com/about/roadmap/

[Joss]

Okay, three four of us posted at once!

There is a good reason for that, however. The reason we all love working in PW is it is a little like wandering off to do some nice happy HTML with a powerful database and API attached.

For instance, I use Bootstrap and sometimes Foundation and lots of JQuery plugins - but none of them have to be changed to suit PW, you can use them out of the box, just as you would in a static site.

This makes it incredibly powerful - nothing is off limits or requires someone to produce the "PW" version of something as you would in Drumlapress.

So, just write your templates, or bits and pieces to be included into templates, as you would any other html page - but do it with the PW API supplying the content.

[DaveP]

Damn, you guys are quick.

What Martijn said.

Oh, and I use tpl-filename.php or inc-filename.php because

• Files then sort into type easily
• Notepad++ knows they are php

[Joss]

Oh, I told my text editor that .inc is the same as .php - it tried to go all logical and objectionable on me but I beat it into submission in the end.

[kongondo]

The reason we all love working in PW is it is a little like wandering off to do some nice happy HTML with a powerful database and API attached.

 

For instance, I use Bootstrap and sometimes Foundation and lots of JQuery plugins - but none of them have to be changed to suit PW, you can use them out of the box, just as you would in a static site.

 

This makes it incredibly powerful - nothing is off limits or requires someone to produce the "PW" version of something as you would in Drumlapress.

 

So, just write your templates, or bits and pieces to be included into templates, as you would any other html page - but do it with the PW API supplying the content.

 

Nice quotes in here Joss!

[pwired]

The only other restriction is that if you want to call any scripts directly, they need to be above the sitefolder.

Not sure what you mean. I just put all my scripts inside  /site/templates/scripts/