PSR Checklist
Entries will be marked upon being completed and committed to the master codebase.
PSR-1
The following markable items must be implemented.
phpMussel versions/releases <1.0.0 don't use classes, so, the following four PSR-1 items aren't relevant for versions/releases <1.0.0; There's nothing to mark here. Any class-based phpMussel versions/releases =>1.0.0 WILL use classes, so, the following four PSR-1 items will BECOME relevant for versions/releases =>1.0.0; We will ensure that we adhere to these items during class implementation and thereafter (this should be completed prior to any official =>1.0.0 version/release).
- Namespaces and classes MUST follow an "autoloading" PSR: [PSR-0, PSR-4].
- Class names MUST be declared in StudlyCaps.
- Class constants MUST be declared in all upper case with underscore separators.
- Method names MUST be declared in camelCase.
PSR-2
1. Overview.
The following markable items must be implemented.
The following non-markable items relate to the implementation of classes, which versions/releases <1.0.0 don't use; This item, therefore, isn't currently relevant, but will BECOME relevant from versions/releases =>1.0.0 and thereafter. We will ensure that we adhere to these items during class implementation and thereafter (this should be completed prior to any official =>1.0.0 version/release).
- There MUST be one blank line after the
namespace
declaration, and there MUST be one blank line after the block of use
declarations.
- Opening braces for classes MUST go on the next line, and closing braces MUST go on the next line after the body.
- Visibility MUST be declared on all properties and methods;
abstract
and final
MUST be declared before the visibility; static
MUST be declared after the visibility.
The following markable items must be implemented.
2. General.
2.1 Basic Coding Standard
2.2 Files
2.3 Lines
Writing that we MAY do something, but NOT writing that we MUST do something; I think this can be marked by default..?
2.4 Indenting
2.5 Keywords and True/False/Null
3. Namespace and Use Declarations
phpMussel versions/releases <1.0.0 don't use namespace
or use
, so, the following non-markable items aren't relevant for versions/releases <1.0.0; Any class-based phpMussel versions/releases =>1.0.0 WILL use namespace
(and possibly will use use
), so, the following non-markable items will BECOME relevant for versions/releases =>1.0.0; We will ensure that we adhere to these items during development of 1.0.0 and thereafter (this should be completed prior to any official =>1.0.0 version/release).
- When present, there MUST be one blank line after the
namespace
declaration.
- When present, all
use
declarations MUST go after the namespace
declaration.
- There MUST be one
use
keyword per declaration.
- There MUST be one blank line after the
use
block.
4. Classes, Properties, and Methods
This will be addressed by phpMussel version/release 1.0.0; This won't be relevant for prior versions/releases.
5. Control Structures
6. Closures
PSR-3
This will be addressed begin exploring a classful implementation in the future.
PSR-4
This will be addressed begin exploring a classful implementation in the future.
PSR-6
This will be addressed begin exploring a classful implementation in the future.
PSR-7
This will be addressed begin exploring a classful implementation in the future.
I've recently been reading through the PSR guidelines for PHP standards, and, although I have mixed feelings about some of their guidelines, I'm going to try to adopt at least some of them.
In particular, in PSR-2, under 2.2 Files, they write:
The closing ?>
tag MUST be omitted from files containing only PHP.
This, principally, is something I've never liked doing, due to that for most programming languages, generally, anything opened should always be closed, and code should generally follow a logical order and be contained within a logical hierarchical tree (at least, so I've always read and so I've always been led to believe).
Currently, phpMussel always closes its PHP (and so, doesn't omit any closing PHP tags).
Here is an interesting article, where the author has posed the question of whether or not we should omit closing tags, and some of the comments (although many of them are now more than a few years old) are very interesting. There seem to be people with very strong views on both sides of the fence, and although many of these views contradict each other, I think many of them, on both sides, have valid points.
Minimising the risk of accidentally inserting bugs or errors in the future is definitely a good thing, but I've always felt that correctly closing any opened tag seemed more professional, so, I was at odds about this.
So, to omit, or not to omit; That is (or was..) the question.. Until I found this:
If a file is pure PHP code, it is preferable to omit the PHP closing tag at the end of the file. This prevents accidental whitespace or new lines being added after the PHP closing tag, which may cause unwanted effects because PHP will start output buffering when there is no intention from the programmer to send any output at that point in the script.
Considering it's also recommended on the PHP site itself to omit closing tags for pure PHP files (and I wasn't aware of this until just now), I think this is a change I'll need to implement for phpMussel.
Under the same section, they also write this:
All PHP files MUST end with a single blank line.
phpMussel doesn't currently do this, for the very reason that including any whitespace after a closing PHP tag could result in headers being prematurely sent, and this is something we don't want happening. However, if I'm to remove the closing PHP tags, then, appending the extra newline to the end of PHP files is something that can be easily done (because the risk of headers being prematurely sent won't be there anymore).
All PHP files MUST use the Unix LF (linefeed) line ending.
This, we're already doing (as well as quite a few other things recommended, though not everything); Figured that one out a long time ago, before I'd ever heard of PSR. 👍
Anyhow. There's a lot to read through, and a lot to do to here, so, this may be in multiple commits, but, it's something to do nonetheless. Posting this as an issue for until this is done.