BeikeShop

# Coding style

BeikeShop follows the PSR1 (PSR-12) coding standard and the PSR-4 automatic loading standard

# PSR1 Basic Coding Standards

This specification sets standards for basic elements of code to ensure a high degree of technical interoperability between shared PHP code.

The modal verbs 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 (opens new window).

# 1. Overview

  • PHP code files MUST start with the <?php or <?= tag;

  • PHP code files MUST be encoded in UTF-8 without BOM;

  • PHP code should either declare any flag (class, function, constant, etc.) or cause side effects (if a function modifies resources outside of its scope, it is called a side effect, such as: generating output and modifying .ini configuration files, etc.), but it should not have both.

  • Namespaces and classes MUST conform to one of the following PSR-compliant autoloaders: [PSR-0 (opens new window) (deprecated) or PSR-4 (opens new window)].

  • Class names must follow the StudlyCaps camel case naming convention;

  • All letters in the constants in the class must be capitalized, and words are separated by underscores;

  • Method names MUST conform to the camelCase convention.

# 2. document

# 2.1. PHP Tags

PHP code must use <?php ?> long tags or <?= ?> short output tags;
must not use other custom tags.

# 2.2. Character set encoding

PHP code MUST only be encoded as UTF-8 without BOM.

# 2.3. side effect

A PHP file should either only define new declarations, such as classes, functions or constants, that do not produce side effects, or only perform logical operations that produce side effects, but it should not have both.

The term "side effects" means logical operations performed simply by including files, without directly declaring classes, functions, constants, etc.

"Side effects" include but are not limited to: generating output, explicitly using require or include, connecting to external services, modifying ini settings, emitting errors or exceptions, modifying global or static variables, reading or writing a file, etc.

The following is a counterexample, a code that contains "function declaration" and produces "side effects":

<?php
//「Side effect」：Modify ini configuration
ini_set('error_reporting', E_ALL);

// 「Side effect」: Import files
include "file.php";

// 「Side effect」: Generate Output
echo "<html>\n";

// Declaring a function
function foo()
{
    // function body
}

Here is an example of a code that contains only declarations and does not produce "side effects":

<?php
// Declaring a function
function foo()
{
    // Function body
}

// Conditional statement **NOT** considered a "side effect"
if (! function_exists('bar')) {
    function bar()
    {
        // Function body
    }
}

# 3. Namespaces and class names

Namespaces and class names must follow the autoloading specification: [PSR-0 (opens new window)， PSR-4 (opens new window)]。

This means that each class is a separate file and is within at least one level of namespace: the top-level organization name（vendor name）。

Class names MUST be declared in StudlyCaps style.

Code written for PHP 5.3 and higher MUST use formal namespaces.

For example：

<?php
// PHP 5.3 and higher:
namespace Vendor\Model;

class Foo
{
}

PHP 5.2 and below SHOULD use pseudo-namespaces, by convention, prefixing class names with the top-level organization name, Vendor_:

<?php
// PHP 5.2.x and below:
class Vendor_Model_Foo
{
}

# 4. Class constants, properties, and methods

The "class" here refers to all classes, interfaces, and reusable code blocks（traits）。

# 4.1 constant

All letters in class constants must be capitalized, and words must be separated by underscores. For example：

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}

# 4.2 property

The attribute naming of the class can follow:

  • CamelCase ($StudlyCaps)
  • CamelCase ($camelCase)
  • Underline delimiter ($under_score)

This specification does not require that you use the same naming convention, but you should use the same convention within a certain scope. This scope can be the entire team, the entire package, the entire class, or the entire method.

# 4.3 method

Method names MUST conform to the camelCase() convention.

# PSR-4 Autoloading Specification

In order to avoid ambiguity, the document uses a lot of "motivational verbs", and the corresponding explanations are as follows:

  • MUST: absolutely, strictly follow, please do as required, unconditionally comply;
  • MUST NOT: prohibition, strictly prohibited;
  • SHOULD: strongly recommended, but not mandatory;
  • SHOULD NOT: strongly not recommended, but not mandatory;
  • MAY and OPTIONAL: more selective, this word is used less in this document;

See also：RFC 2119 (opens new window)

# 1. Overview

PSR-4 describes the specification for autoloading (opens new window) classes from a file path. It has very good compatibility and can be used in any autoloading specification, including PSR-0 (opens new window). The PSR-4 specification also describes where to place the autoload file (which is what we often introduce as vendor/autoload.php).

# 2. specification

  1. The term "class" refers to classes, interfaces, traits, and other similar constructs.

  2. A fully qualified class name has the following form:

 \<NamespaceName>(\<SubNamespaceNames>)*\<ClassName>

  1. A fully qualified class name MUST have a top-level namespace name, also called a vendor namespace.

  2. A fully qualified class name MAY have one or more sub-namespace names.

  3. A fully qualified class name must have a final class name (which I guess means you can't do <NamespaceName>(<SubNamespaceNames>)*` to represent a complete class).

  4. Underscores do not have any special meaning in fully qualified class names (as they do in PSR-0 (opens new window)).

  5. The fully qualified class name can be any combination of uppercase and lowercase letters.

  6. All references to class names MUST be case-sensitive.

  7. Loading process of fully qualified class name

    1. In a fully qualified class name (a "namespace prefix"), the contiguous namespace consisting of one or more leading namespaces and subnamespaces, excluding the leading namespace separator, corresponds to at least one "root directory".

    2. The adjacent sub-namespaces following the "namespace prefix" correspond to the directory names under the root directory (and must be case-sensitive), where the namespace separator represents the directory separator.

    3. The final class name is consistent with the file name ending in .php, and the name of this file must match the final class name (meaning that if the class name is FooController, then the file name where this class is located must be FooController.php).

  8. Automatically loading files is not allowed to throw exceptions, not allowed to have errors of any level, and not recommended to have return values.

# 3. example

The following table shows the path to the file that corresponds to a given fully qualified class name, namespace prefix, and root directory.

Fully Qualified Class Name Namespace Prefix Base Directory Resulting File Path
\Acme\Log\Writer\File_Writer Acme\Log\Writer ./acme-log-writer/lib/ ./acme-log-writer/lib/File_Writer.php
\Aura\Web\Response\Status Aura\Web /path/to/aura-web/src/ /path/to/aura-web/src/Response/Status.php
\Symfony\Core\Request Symfony\Core ./vendor/Symfony/Core/ ./vendor/Symfony/Core/Request.php
\Zend\Acl Zend /usr/includes/Zend/ /usr/includes/Zend/Acl.php

For an example of a conforming autoloader implementation see the examples file (opens new window). The example autoloader MUST NOT be considered part of the specification and is subject to change at any time.

← Laravel Directory Structure →