rspec/rules/S1808/php/rule.adoc

== 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[]