197 lines
5.0 KiB
ReStructuredText
197 lines
5.0 KiB
ReStructuredText
===========================
|
|
PSR-1 Basic Coding Standard
|
|
===========================
|
|
|
|
.. Note::
|
|
|
|
| The PSR1 and PSR2 Coding Standards are provided by FIG under a MIT license.
|
|
| See license details: http://www.php-fig.org/bylaws/licensing-policies/
|
|
| The original content of this page can be found at `php-fig <http://www.php-fig.org/psr/psr-1/>`__
|
|
|
|
This section of the standard comprises what should be considered the
|
|
standard coding elements that are required to ensure a high level of
|
|
technical interoperability between shared PHP code.
|
|
|
|
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 <http://www.ietf.org/rfc/rfc2119.txt>`__.
|
|
|
|
-----------
|
|
1. Overview
|
|
-----------
|
|
|
|
- Files MUST use only ``<?php`` and ``<?=`` tags.
|
|
|
|
- Files MUST use only UTF-8 without BOM for PHP code.
|
|
|
|
- Files SHOULD *either* declare symbols (classes, functions, constants,
|
|
etc.) *or* cause side-effects (e.g. generate output, change .ini
|
|
settings, etc.) but SHOULD NOT do both.
|
|
|
|
- Namespaces and classes MUST follow an "autoloading" PSR:
|
|
[`PSR-0 <https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md>`__,
|
|
`PSR-4 <https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md>`__].
|
|
|
|
- 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``.
|
|
|
|
--------
|
|
2. Files
|
|
--------
|
|
|
|
2.1. PHP Tags
|
|
-------------
|
|
|
|
PHP code MUST use the long ``<?php ?>`` tags or the short-echo
|
|
``<?= ?>`` tags; it MUST NOT use the other tag variations.
|
|
|
|
2.2. Character Encoding
|
|
-----------------------
|
|
|
|
PHP code MUST use only UTF-8 without BOM.
|
|
|
|
2.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:
|
|
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
// side effect: change ini settings
|
|
ini_set('error_reporting', E_ALL);
|
|
|
|
// side effect: loads a file
|
|
include "file.php";
|
|
|
|
// side effect: generates output
|
|
echo "<html>\n";
|
|
|
|
// 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:
|
|
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
// declaration
|
|
function foo()
|
|
{
|
|
// function body
|
|
}
|
|
|
|
// conditional declaration is *not* a side effect
|
|
if (! function_exists('bar')) {
|
|
function bar()
|
|
{
|
|
// function body
|
|
}
|
|
}
|
|
|
|
----------------------------
|
|
3. Namespace and Class Names
|
|
----------------------------
|
|
|
|
Namespaces and classes MUST follow an "autoloading" PSR:
|
|
[`PSR-0 <https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md>`__,
|
|
`PSR-4 <https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md>`__].
|
|
|
|
This means each class is in a file by itself, and is in a namespace of
|
|
at least one level: a top-level vendor name.
|
|
|
|
Class names MUST be declared in ``StudlyCaps``.
|
|
|
|
Code written for PHP 5.3 and after MUST use formal namespaces.
|
|
|
|
For example:
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
// PHP 5.3 and later:
|
|
namespace Vendor\Model;
|
|
|
|
class Foo
|
|
{
|
|
}
|
|
|
|
|
|
Code written for 5.2.x and before SHOULD use the pseudo-namespacing
|
|
convention of ``Vendor_`` prefixes on class names.
|
|
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
// PHP 5.2.x and earlier:
|
|
class Vendor_Model_Foo
|
|
{
|
|
}
|
|
|
|
-------------------------------------------
|
|
4. Class Constants, Properties, and Methods
|
|
-------------------------------------------
|
|
|
|
The term "class" refers to all classes, interfaces, and traits.
|
|
|
|
4.1. Constants
|
|
--------------
|
|
|
|
Class constants MUST be declared in all upper case with underscore
|
|
separators. For example:
|
|
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
namespace Vendor\Model;
|
|
|
|
class Foo
|
|
{
|
|
const VERSION = '1.0';
|
|
const DATE_APPROVED = '2012-06-01';
|
|
}
|
|
|
|
4.2. Properties
|
|
---------------
|
|
|
|
This guide intentionally avoids any recommendation regarding the use of
|
|
``$StudlyCaps``, ``$camelCase``, or ``$under_score`` property names.
|
|
|
|
Whatever naming convention is used SHOULD be applied consistently within
|
|
a reasonable scope. That scope may be vendor-level, package-level,
|
|
class-level, or method-level.
|
|
|
|
4.3. Methods
|
|
------------
|
|
|
|
Method names MUST be declared in ``camelCase()``.
|