Coding Style Guidelines
From version 5.7 and onward, concrete5 is adopting the PHP Framework Interoperability Group's PSR-2 coding standard. This standard dictates a number of things, including spaces vs. tabs, brace placement, method naming, and more. Please read it and adhere to it.
Like a lot in life, coding standards are deeply personal. I myself strongly disagree with several decisions in this standard (and, to spare myself the inevitable arguments, I'll leave which these are to your imagination.) That said, there is a lot of good in here, and I think it can only help the ecosystem. So I, too, will bite the bullet.
We're in the same boat, people. Let's set sail!
File Naming and Location
From version 5.7 and onward, concrete5 is adopting a modified naming standard based on PHP Framework Interoperability Group's PSR-4. Our built-in autoloader will automatically find classes that adhere to this system.
All core libraries adhere to PSR-4 with no modifications. What does that mean? That means that our namespaced core libraries like the Page class
Can be found at
PSR-4 basically states that projects can map different namespace prefixes to arbitrary starting directories. That's what we're doing.
If you are writing code that belongs in the core source directory, you must adhere to PSR-4 as is. Classes must be capitalized, etc...
For classes that do not exist within the src/ directory (such as block controllers, attribute controllers, etc...) We ask that you name your controllers with the same capitalization that PSR-4 requires, but you name your files with concrete5's classic lowercase + underscore method. These files will be converted by camelcasing those filenames on the fly.
What does that mean? The blocks directory and its contents still looks the same as concrete5 before 5.7. For example, the Page List block's controller is still located at
If you were strictly following PSR-4, you would need to name your class
inside the name space
This is ugly and causes other problems. So instead, when we request the class
We first check to see if
exists (since that is the default PSR-4 autoloading behavior.)
If it does not (and it won't, for blocks, attributes, single page controllers, etc...) – then we uncamelcase using our own methods, starting at the item after blocks. Backslashes become directory separatores, and camelcasing becomes underscores.
And that's how we handle non-library classes in concrete5 5.7.
We have already taken care of moving files to support these updated naming and directory standards. For coding style (including spaces vs. tabs, braces, etc...) we will be modifying existing core code to support this code base as needed. This is not a high priority, but we will accept pull requests quickly that modify this code for us.
If you submit a pull request for this type of cleanup, please keep each request to one file – for the sake of vetting your pull request. Please do not run the entire concrete5 source through a cleanup tool and send that to us. We could do that ourselves ;-)
- Use four spaces for indention, for tool consistency and consistency with existing core code.
- When saving a reference to "this," use "my" instead of "_this."
File Naming and Location
Again, if you submit a pull request for this type of cleanup, please keep each request to one or just a few files – for the sake of vetting your pull request. Please do not run the entire concrete5 source through a cleanup tool and send that to us. We could do that ourselves ;-)
Your CSS/LESS is largely your business, but we do ask that all selectors be lowercased, with dashes as their delimiters. If coding something for the core, please prefix it with 'ccm-' and try and be consistent.
File Naming and Location
CSS file names should be all lowercase, with dashes the only non alphanumeric character allowed in the filenames before the extension.
CSS should go in the standard css/ directories only. Unless it is explicitly allowed by the core (e.g. view.css files in blocks.)
Most of our CSS has been moved into LESS files as of 5.7. We will accept pull requests for minor syntax changes here and there, but we're generally pretty pleased with this cleanup so far, and it doesn't require too much.
The names of our CSS files definitely don't currently support these standards. We will be handling the renaming of files as needed. Please do not submit pull requests renaming core files.
Again, if you submit a pull request for this type of cleanup, please keep each request to one or just a few files – for the sake of vetting your pull request.
These decisions have not been made lightly, and they're probably going to upset some (including some core developers – gulp). But hopefully this can lead to a cleaner, more uniform concrete5 source.
For more discussion on this, including any addendums, additions or fixes, please post in the Documentation Forum.