https://github.com/gtap-dev/php

PHP code guidelines
https://github.com/gtap-dev/php

Last synced: about 2 months ago
JSON representation

PHP code guidelines

• Host: GitHub
• URL: https://github.com/gtap-dev/php
• Owner: gtap-dev
• Created: 2020-08-14T11:37:22.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2021-09-09T11:08:53.000Z (over 3 years ago)
• Last Synced: 2023-02-28T23:06:36.232Z (almost 2 years ago)
• Size: 13.7 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# PHP Coding Style Guide

A mostly reasonable approach to PHP

This is a superset of the [PSR-12].

**We suggest you familiarize yourself with the [clean-code] principles first.** 

## 1. Overview

### 1.1. Previous language versions

Throughout this document, any instructions may be ignored if they do not exist in versions

of PHP supported by your project.

## 2. Basic Coding Standard

## 2.1 Overview

- Files must use only `(\)*\

- The fully qualified class name must have a top-level namespace name,

   also known as a "vendor namespace".

- The fully qualified class name may have one or more sub-namespace

   names.

- The fully qualified class name must have a terminating class name.

- Underscores have no special meaning in any portion of the fully

   qualified class name.

- Alphabetic characters in the fully qualified class name may be any

   combination of lower case and upper case.

- All class names must be referenced in a case-sensitive fashion.

- When loading a file that corresponds to a fully qualified class name ...

- A contiguous series of one or more leading namespace and sub-namespace

    names, not including the leading namespace separator, in the fully

    qualified class name (a "namespace prefix") corresponds to at least one

    "base directory".

- The contiguous sub-namespace names after the "namespace prefix"

    correspond to a subdirectory within a "base directory", in which the

    namespace separators represent directory separators. The subdirectory

    name must match the case of the sub-namespace names.

- The terminating class name corresponds to a file name ending in `.php`.

    The file name must match the case of the terminating class name.

- Autoloader implementations must not throw exceptions, must not raise errors

    of any level, and should not return a value.

 

## 2.3 Files

All PHP files must use the Unix LF (linefeed) line ending only.

All PHP files must end with a non-blank line, terminated with a single LF.

The closing `?>` tag must be omitted from files containing only PHP.

PHP code must use the long `` tags, it must not use the other tag variations.

PHP code must use only UTF-8 without BOM.

### 2.3.1 Lines

There must not be a hard limit on line length.

The soft limit on line length must be 120 characters.

There must not be trailing whitespace at the end of lines.

Blank lines may be added to improve readability and to indicate related

blocks of code except where explicitly forbidden.

There must not be more than one statement (statement ends with a semicolon) per line.

### 2.3.2 Indenting

Code must use an indent of 4 spaces for each indent level, and must not use

tabs for indenting.

### 2.3.3 Side Effects

A file should declare new symbols (classes, functions, constants,

etc.) and cause no other side effects, or it should execute logic with side

effects, but should not do both.

The phrase "side effects" means execution of logic not directly related to

declaring classes, functions, constants, etc., *merely from including the

file*.

"Side effects" include but are not limited to: generating output, explicit

use of `require` or `include`, connecting to external services, modifying ini

settings, emitting errors or exceptions, modifying global or static variables,

reading from or writing to a file, and so on.

The following is an example of a file with both declarations and side effects;

i.e, an example of what to avoid:

~~~php

';

// declaration

function foo() {

    // function body

}

~~~

The following example is of a file that contains declarations without side

effects; i.e., an example of what to emulate:

~~~php

    

~~~

Declare statements must contain no spaces and must be exactly `declare(strict_types=1)`

(with an optional semi-colon terminator).

Block declare statements are allowed and must be formatted as below. Note position of

braces and spacing:

~~~php

declare(ticks=1) {

    // some code

}

~~~

## 4. Classes, Properties, and Methods

The term "class" refers to all classes, interfaces, and traits.

Any closing brace must not be followed by any comment or statement on the

same line.

When instantiating a new class, parentheses must always be present even when

there are no arguments passed to the constructor.

~~~php

new Foo();

~~~

### 4.1 Extends and Implements

The `extends` and `implements` keywords must be declared on the same line as

the class name.

The opening brace for the class must go on the same line; the closing brace

for the class must go on the next line after the body.

Opening braces must be on the same line and must not be preceded or followed

by a blank line.

Closing braces must be on their own line and must not be preceded by a blank

line.

~~~php

bar($arg1);

Foo::bar($arg2, $arg3);

~~~

Argument lists may be split across multiple lines, where each subsequent line

is indented once. When doing so, the first item in the list must be on the

next line, and there must be only one argument per line. A single argument (except for anonymous function) being

split across multiple lines (as might be the case with an anonymous function or

array) constitutes splitting the argument list itself.

~~~php

bar(

    $longArgument,

    $longerArgument,

    $muchLongerArgument

);

~~~

~~~php

get('/hello/{name}', function ($name) use ($app) {

    return 'Hello ' . $app->escape($name);

});

~~~

## 5. Control Structures

The general style rules for control structures are as follows:

- There must be one space after the control structure keyword

- There must not be a space after the opening parenthesis

- There must not be a space before the closing parenthesis

- There must be one space between the closing parenthesis and the opening

  brace

- The structure body must be indented once

- The body must be on the next line after the opening brace

- The closing brace must be on the next line after the body

The body of each structure must be enclosed by braces. This standardizes how

the structures look and reduces the likelihood of introducing errors as new

lines get added to the body.

### 5.1 `if`, `else if`, `else`

An `if` structure looks like the following. Note the placement of parentheses,

spaces, and braces; and that `else` and `else if` are on the same line as the

closing brace from the earlier body.

~~~php

 $value) {

    // foreach body

}

~~~

### 5.6 `try`, `catch`, `finally`

A `try-catch-finally` block looks like the following. Note the placement of

parentheses, spaces, and braces.

~~~php

 $b) {

    $foo = $a + $b * $c;

}

~~~

### 7.3. Ternary operators

The conditional operator, also known simply as the ternary operator, must be

preceded and followed by at least one space around both the `?`

and `:` characters:

~~~php

$variable = $foo ? 'foo' : 'bar';

~~~

When the middle operand of the conditional operator is omitted, the operator

must follow the same style rules as other binary [comparison][] operators:

~~~php

$variable = $foo ?: 'bar';

~~~

## 8. Closures

Closures must be declared with a space after the `function` keyword, and a

space before and after the `use` keyword.

The opening brace must go on the same line, and the closing brace must go on

the next line following the body.

There must not be a space after the opening parenthesis of the argument list

or variable list, and there must not be a space before the closing parenthesis

of the argument list or variable list.

In the argument list and variable list, there must not be a space before each

comma, and there must be one space after each comma.

Closure arguments with default values must go at the end of the argument

list.

If a return type is present, it must follow the same rules as with normal

functions and methods; if the `use` keyword is present, the colon must follow

the `use` list closing parentheses with no spaces between the two characters.

A closure declaration looks like the following. Note the placement of

parentheses, commas, spaces, and braces:

~~~php

bar(

    $arg1,

    function ($arg2) use ($var1) {

        // body

    },

    $arg3

);

~~~

## 9. Anonymous Classes

Anonymous Classes must follow the same guidelines and principles as closures

in the above section.

~~~php

total = 0;

    }

}

~~~

## Resources

- [PHP Manual][PHP]

- [PHP Standards Recommendations][PSR]

- [PHP Clean Code][clean-code], please do read this

[PSR]: https://www.php-fig.org/psr/

[PHP]: https://www.php.net/manual/en/

[PSR-12]: https://www.php-fig.org/psr/psr-12/

[PSR-1]: https://www.php-fig.org/psr/psr-1/

[PSR-2]: https://www.php-fig.org/psr/psr-2/

[keywords]: http://php.net/manual/en/reserved.keywords.php

[types]: http://php.net/manual/en/reserved.other-reserved-words.php

[arithmetic]: http://php.net/manual/en/language.operators.arithmetic.php

[assignment]: http://php.net/manual/en/language.operators.assignment.php

[comparison]: http://php.net/manual/en/language.operators.comparison.php

[bitwise]: http://php.net/manual/en/language.operators.bitwise.php

[logical]: http://php.net/manual/en/language.operators.logical.php

[string]: http://php.net/manual/en/language.operators.string.php

[type]: http://php.net/manual/en/language.operators.type.php

[clean-code]: https://github.com/jupeter/clean-code-php