Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/indentno/sempro-psr-2-style-guide
https://github.com/indentno/sempro-psr-2-style-guide
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/indentno/sempro-psr-2-style-guide
- Owner: indentno
- Created: 2014-05-07T07:02:26.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2016-11-07T11:13:44.000Z (about 8 years ago)
- Last Synced: 2023-09-18T16:40:56.572Z (over 1 year ago)
- Size: 10.7 KB
- Stars: 0
- Watchers: 9
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Coding Style Guide
==================
This guide extends and expands on [PSR-1], the basic coding standard.
The intent of this guide is to reduce cognitive friction when scanning code
from different authors. It does so by enumerating a shared set of rules and
expectations about how to format PHP code.
The style rules herein are derived from commonalities among the various member
projects. When various authors collaborate across multiple projects, it helps
to have one set of guidelines to be used among all those projects. Thus, the
benefit of this guide is not in the rules themselves, but in the sharing of
those rules.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in [RFC 2119].
[RFC 2119]: http://www.ietf.org/rfc/rfc2119.txt
[PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
[PSR-1]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md
1. Overview
-----------
- Code MUST follow a "coding style guide" PSR [[PSR-1]].
- Code MUST use 4 spaces for indenting, not tabs.
- There MUST NOT be a hard limit on line length; the soft limit MUST be 120
characters; lines SHOULD be 80 characters or less.
- 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.
- Opening braces for methods 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.
- Control structure keywords MUST have one space after them; method and
function calls MUST NOT.
- Opening braces for control structures MUST go on the same line, and closing
braces MUST go on the next line after the body.
- Opening parentheses for control structures MUST NOT have a space after them,
and closing parentheses for control structures MUST NOT have a space before.
### 1.1. Example
This example encompasses some of the rules below as a quick overview:
```php
$b) {
$foo->bar($arg1);
} else {
BazClass::bar($arg2, $arg3);
}
}
final public static function bar()
{
// method body
}
}
```
2. General
----------
### 2.1 Basic Coding Standard
Code MUST follow all rules outlined in [PSR-1].
### 2.2 Files
All PHP files MUST use the Unix LF (linefeed) line ending.
All PHP files MUST end with a single blank line.
The closing `?>` tag MUST be omitted from files containing only PHP.
### 2.3. Lines
There MUST NOT be a hard limit on line length.
The soft limit on line length MUST be 120 characters; automated style checkers
MUST warn but MUST NOT error at the soft limit.
Lines SHOULD NOT be longer than 80 characters; lines longer than that SHOULD
be split into multiple subsequent lines of no more than 80 characters each.
There MUST NOT be trailing whitespace at the end of non-blank lines.
Blank lines MAY be added to improve readability and to indicate related
blocks of code.
There MUST NOT be more than one statement per line.
### 2.4. Indenting
Code MUST use an indent of 4 spaces, and MUST NOT use tabs for indenting.
> N.b.: Using only spaces, and not mixing spaces with tabs, helps to avoid
> problems with diffs, patches, history, and annotations. The use of spaces
> also makes it easy to insert fine-grained sub-indentation for inter-line
> alignment.
### 2.5. Keywords and True/False/Null
PHP [keywords] MUST be in lower case.
The PHP constants `true`, `false`, and `null` MUST be in lower case.
[keywords]: http://php.net/manual/en/reserved.keywords.php
3. Namespace and Use Declarations
---------------------------------
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.
For example:
```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.
```php
bar(
$longArgument,
$longerArgument,
$muchLongerArgument
);
```
```php
$localFilename,
'description' => Input::get('description'),
'status' => 'approved',
)
);
```
```php
'facebook.photo.store',
'uses' => 'FacebookPhotoController@store'
)
);
```
```php
'ecrmnn',
'password' => Hash::make('password')
);
$user = new User($userdata));
$user->save();
```
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 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`, `elseif`, `else`
An `if` structure looks like the following. Note the placement of parentheses,
spaces, and braces; and that `else` and `elseif` are on the same line as the
closing brace from the earlier body.
```php
$value) {
// foreach body
}
```
### 5.6. `try`, `catch`
A `try catch` block looks like the following. Note the placement of
parentheses, spaces, and braces.
```php
bar(
$arg1,
function ($arg2) use ($var1) {
// body
},
$arg3
);
```
7. Models
-----------
Models in laravel projects should be structured in a way that allows us to always have a common structure across repositories.
Properties in a model should be defined at the top of the model. All methods in a model should be split into sections where each section has a large comment block attached.
The order of methods should be:
- Accessors
- Mutators
- Scopes
- Methods
- Relationships
### Example
```php
attributes['icon'] = null;
} else {
$this->attributes['icon'] = $value;
}
}
/*
|-------------------------------------------------------------------------------------------------------------------
| Scopes
|-------------------------------------------------------------------------------------------------------------------
*/
public function scopeIcon($query, $icon)
{
return $query->where('icon', '=', $icon);
}
/*
|-------------------------------------------------------------------------------------------------------------------
| Methods
|-------------------------------------------------------------------------------------------------------------------
*/
public function hasImage()
{
return $this->image_id !== 0;
}
public function featuredImage()
{
return 'defaults/2560x720.jpg';
}
/*
|-------------------------------------------------------------------------------------------------------------------
| Relationships
|-------------------------------------------------------------------------------------------------------------------
*/
public function image()
{
return $this->belongsTo(Image::class);
}
}
```
8. Conditional statements VS Switch statements
----------------------------------------------
Always choose conditional statements over switch statements.
Performance is not a concern here, but readability is.
9. Naming Conventions
---------
### 9a. Controller Naming
Controllers should always use the singular form of the resource you are working with.
- **Correct:** PageController
- **Wrong:** PagesController
- **Correct:** EmployeeController
- **Wrong:** EmployeesController
### 9b. Controller Method Naming
Try to only use the following method names in a controller
``index, create, store, show, edit, update, delete``
This order of methods is also recommended.
~~If you find yourself in a situation where you have a ``PageController`` with all the methods above, but want to add an ``updateOrder`` method, you should instead make a dedicated controller ``PageOrderController`` with an ``update`` method.~~
### 9c. Route aliases
Should always be ``resource.method``
Example: A route to the ``update`` method on a ``PageController`` should be aliased to ``page.update``
### 9d. FormRequest
Should always be ``[Method][Resource]Request``.
**Correct:** ``StorePageRequest`` ``UpdatePageRequest`` ``DeletePageRequest``
10. Conclusion
--------------
There are many elements of style and practice intentionally omitted by this
guide. These include but are not limited to:
- Declaration of global variables and global constants
- Declaration of functions
- Operators and assignment
- Inter-line alignment
- Comments and documentation blocks
- Class name prefixes and suffixes
- Best practices
Future recommendations MAY revise and extend this guide to address those or
other elements of style and practice.