16f6c0aecf
Inline adoc files when they are included exactly once. Also fix language tags because this inlining gives us better information on what language the code is written in.
246 lines
10 KiB
Plaintext
246 lines
10 KiB
Plaintext
== Why is this an issue?
|
||
|
||
Shared coding conventions make it possible for a team to collaborate efficiently.
|
||
This rule raises issues for failures to comply with formatting standard.
|
||
|
||
By default, this rule conforms to the PER (PHP Evolving Recommendation) standard.
|
||
|
||
== How to fix it
|
||
|
||
Fix the issue related to conforming to formatting standards.
|
||
|
||
=== Code examples
|
||
|
||
==== Noncompliant code example
|
||
|
||
[source,php,diff-id=1,diff-type=noncompliant]
|
||
----
|
||
use FooClass; // Noncompliant; the "use" declaration should be placed after the "namespace" declaration
|
||
|
||
namespace Vendor\Package;
|
||
use FooClass; // Noncompliant; the "namespace" declaration should be followed by a blank line
|
||
$foo = 1; // Noncompliant; the "use" declaration should be followed by a blank line
|
||
|
||
class ClassA { // Noncompliant; an open curly brace should be at the beginning of a new line for classes and functions
|
||
function my_function(){ // Noncompliant; curly brace on wrong line
|
||
if ($firstThing) // Noncompliant; an open curly brace should be at the end of line for a control structure
|
||
{
|
||
...
|
||
}
|
||
|
||
if ($secondThing) { // Noncompliant; there should be exactly one space between the closing parenthesis and the opening curly brace
|
||
...
|
||
}
|
||
|
||
if($thirdThing) { // Noncompliant; there should be exactly one space between the control structure keyword and the opening parenthesis
|
||
...
|
||
}
|
||
else { // Noncompliant; the close curly brace and the next "else" (or "catch" or "finally") keyword should be located on the same line
|
||
...
|
||
}
|
||
|
||
try{ // Noncompliant; there should be exactly one space between the control structure keyword and the curly brace
|
||
...
|
||
} catch (Exception $e) {
|
||
}
|
||
|
||
analyse( $fruit ) ; // Noncompliant; there should not be any space after the opening parenthesis and before the closing parenthesis
|
||
|
||
for ($i = 0;$i < 10; $i++) { // Nomcompliant; there should be exactly one space after each ";" in the {{for}} statement
|
||
...
|
||
}
|
||
|
||
pressJuice($apply ,$orange); // Noncompliant; the comma should be followed by one space and not preceded by any
|
||
|
||
do_something (); // Noncompliant; there should not be any space after the method name
|
||
|
||
foreach ($fruits as $fruit_key => $fruit) { // Noncompliant; in the foreach statement there should be one space before and after "as" keyword and "=>" operator
|
||
...
|
||
}
|
||
}
|
||
}
|
||
|
||
class ClassB
|
||
extends ParentClass // Noncompliant; the class name and the "extends" / "implements" keyword should be on the same line
|
||
{
|
||
...
|
||
}
|
||
|
||
class ClassC extends ParentClass implements \ArrayAccess, \Countable,
|
||
\Serializable // Noncompliant; the list of implemented interfaces should be correctly indented
|
||
{
|
||
|
||
public function aVeryLongMethodName(ClassTypeHint $arg1, // Noncompliant; the arguments in a method declaration should be correctly indented
|
||
&$arg2, array $arg3 = []) {
|
||
|
||
$noArgs_longVars = function () use ($longVar1, // Noncompliant; the arguments in a function declaration should be correctly indented
|
||
$longerVar2,
|
||
$muchLongerVar3
|
||
) {
|
||
...
|
||
};
|
||
|
||
$foo->bar($longArgument, // Noncompliant; the arguments in a method call should be correctly indented
|
||
$longerArgument,
|
||
$muchLongerArgument); // Noncompliant; the closing parenthesis should be placed on the next line
|
||
|
||
$closureWithArgsAndVars = function($arg1, $arg2)use ($var1, $var2) { // Noncompliant; the closure declaration should be correctly spaced - see (5)
|
||
...
|
||
};
|
||
}
|
||
}
|
||
----
|
||
|
||
==== Compliant solution
|
||
|
||
[source,php,diff-id=1,diff-type=compliant]
|
||
----
|
||
namespace Vendor\Package; // Compliant; the "namespace" declaration is followed by a blank line
|
||
|
||
use FooClass; // Compliant; the "use" declaration is placed after the "namespace" declaration
|
||
// Compliant; the "use" declaration is followed by a blank line
|
||
$foo = 1;
|
||
|
||
class ClassA
|
||
{ // Compliant; the open curly brace is at the beginning of a new line for the class
|
||
function my_function()
|
||
{ // Compliant; the open curly brace is at the beginning of a new line for the function
|
||
if ($firstThing) { // Compliant; the open curly brace is at the end of line for the control structure
|
||
...
|
||
}
|
||
|
||
if ($secondThing) { // Compliant; there is exactly one space between the closing parenthesis and the opening curly brace
|
||
...
|
||
}
|
||
|
||
if ($thirdThing) { // Compliant; there is exactly one space between the control structure keyword and the opening parenthesis
|
||
...
|
||
} else { // Compliant; the close curly brace and the next "else" (or "catch" or "finally") keyword are located on the same line
|
||
...
|
||
}
|
||
|
||
try { // Compliant; there is exactly one space between the control structure keyword and the curly brace
|
||
...
|
||
} catch (Exception $e) {
|
||
...
|
||
}
|
||
|
||
analyse($fruit); // Compliant: there is no space after the opening parenthesis, nor before the closing parenthesis
|
||
|
||
for ($i = 0; $i < 10; $i++) { // Compliant: there is exactly one space after each ";" in the {{for}} statement
|
||
...
|
||
}
|
||
|
||
pressJuice($apply, $orange); // Compliant; the comma is followed by one space and is not preceded by any
|
||
|
||
do_something(); // Compliant; there is no space after the method name
|
||
|
||
foreach ($fruits as $fruit_key => $fruit) { // Compliant; in the foreach statement there is one space before and after "as" keyword and "=>" operator
|
||
...
|
||
}
|
||
}
|
||
}
|
||
|
||
/* The idea here is to make it obvious at first glance that a class extends
|
||
* some other classes and/or implements some interfaces. The names of
|
||
* extended classes or implemented interfaces can be located on subsequent lines.
|
||
*/
|
||
class ClassB1 extends ParentClass // Compliant; the class name and the "extends" (or "implements") keyword are located on the same line
|
||
{
|
||
...
|
||
}
|
||
|
||
class ClassB2 extends // Compliant; the class name and the "extends" (or "implements") keyword are located on the same line
|
||
ParentClass {
|
||
...
|
||
}
|
||
|
||
/* Lists of implements may be split across multiple lines, where each subsequent line
|
||
* is indented once. When doing so, the first item in the list should be on the next line,
|
||
* and there should be only one interface per line.
|
||
*/
|
||
class ClassC extends ParentClass implements
|
||
\ArrayAccess, // Compliant; the list of implemented interfaces is correctly indented
|
||
\Countable,
|
||
\Serializable
|
||
{
|
||
/* Argument lists may be split across multiple lines, where each subsequent line
|
||
* is indented once. When doing so, the first item in the list should be on the next line,
|
||
* and there should be only one argument per line. Also, when the argument list is
|
||
* split across multiple lines, the closing parenthesis and opening brace should be
|
||
* placed together on their own line with one space between them.
|
||
*/
|
||
public function aVeryLongMethodName(
|
||
ClassTypeHint $arg1, // Compliant; the arguments in a method/function declaration are correctly indented
|
||
&$arg2,
|
||
array $arg3 = []
|
||
) {
|
||
$noArgs_longVars = function () use (
|
||
$longVar1, // Compliant; the arguments in a method/function declaration are correctly indented
|
||
$longerVar2,
|
||
$muchLongerVar3
|
||
) {
|
||
...
|
||
};
|
||
|
||
|
||
/* Argument lists may be split across multiple lines, where each subsequent line is
|
||
* indented once. When doing so, the first item in the list should be on the next line,
|
||
* and there should be only one argument per line.
|
||
*/
|
||
$foo->bar(
|
||
$longArgument, // Compliant; the arguments in the method call are be correctly indented
|
||
$longerArgument,
|
||
$muchLongerArgument
|
||
); // Compliant; the closing parenthesis is placed on a separate line
|
||
|
||
/* Closures should be declared with a space after the "function" keyword,
|
||
* and a space before and after the "use" keyword.
|
||
*/
|
||
$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) { // Compliant; the closure declaration is correctly spaced
|
||
...
|
||
};
|
||
}
|
||
}
|
||
----
|
||
|
||
== Resources
|
||
|
||
=== Standards
|
||
|
||
* https://www.php-fig.org/per/coding-style/#22-files[PER Coding Style 2.0 - Files]
|
||
|
||
|
||
|
||
ifdef::env-github,rspecator-view[]
|
||
|
||
'''
|
||
|
||
== Implementation Specification
|
||
|
||
(visible only on this page)
|
||
|
||
=== Message
|
||
|
||
* Add a blank line after this "namespace XXX" declaration.
|
||
* Move the use declarations after the namespace declarations.
|
||
* Add a blank line after this "use" declaration.
|
||
* Move this open curly brace to the end of the previous line.
|
||
* Move this open curly brace to the beginning of the next line.
|
||
* Put [only] one space between the closing parenthesis and the opening curly brace.
|
||
* Put [only] one space between this "XXXX" keyword and the opening [parenthesis|curly brace].
|
||
* Remove all space [after the opening parenthesis |& before the closing parenthesis].
|
||
* Put exactly one space after each ";" character in the ``++for++`` statement.
|
||
* [Remove any space before comma separated arguments] [Put exactly one space after comma separated arguments]
|
||
* Remove all space between the method name "XXXX" and the opening parenthesis.
|
||
* Put exactly one space after and before [``++as++``|``++=>++``] in ``++foreach++`` statement.
|
||
* Move this ["else"|"catch"|"finally"] to the same line as the previous closing curly brace.
|
||
* [Either split this list into multiple lines or move it on the same line.] [Align all interfaces in this list at column "XX".]
|
||
* [Either split this list into multiple lines, aligned at column "XX" or put all elements on line "YYY".] [Align all arguments in this list at column "XX".] [Move the closing parenthesis with the opening brace on the next line.]
|
||
* [Either split this list into multiple lines, aligned at column "xx" or put all arguments on line "yyy".] [Align all arguments in this list at column "XX".] [Move the closing parenthesis on the next line.]
|
||
* [Put exactly one space between the "function" keyword and the opening parenthesis.] [Put exactly one space before and after the "use" keyword.]
|
||
* Move ["extends"] [and] ["implements"] keyword[s] on line {0} to the same line as the declaration of its class name, "XX".
|
||
|
||
|
||
endif::env-github,rspecator-view[]
|