LoginSignup
1
2

More than 3 years have passed since last update.

@tatsuo-iriyamainユアマイスター株式会社

PSR-1: Basic Coding Standard 読了

Last updated at Posted at 2020-02-02

PSRとは

  • PSR（PHP Standards Recommendations）とは、PHP-FIG（PHP Framework Interop Group）が策定しているPHPコーディング規約を指す

PSR-1: Basic Coding Standard

PSR-1: Basic Coding Standard

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.

  • PHPコードの運用性を確保するために必要な標準となるコーディング要素について記されてる
  • いくつか登場するキーワード（MUST, MUST NOT etc...）は、RFC 2119で説明されてるような解釈とする

内容の構成は章立てされており、いくつかの章では節に当たる項目が用意されてる
引用に関しては全てPSR-1のものである
箇条書きされてる箇所は 和訳＋個人の解釈 の入った内容となってる

※以下、学習の一環として自分の解釈とコードを交えた内容を記載しますが、間違いあればコメント頂けますと幸いです。早急に対応しますのでご遠慮なく。

概要

・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, PSR-4].
・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.

  • 上から順に
    • <?php および <?= tags を使用しなければならない
    • 文字コードは、UTF-8（BOM無し）を使用しなければならない
    • 同一ファイル内で、シンボル（クラス、関数、定数など）を宣言する、あるいは副作用（出力の生成、.ini設定の変更など）を行うべきではない
    • 名前空間、クラスはオートロードPSR（PSR-0, PSR-4）に準拠する必要がある
    • クラス名は、StudlyCaps記法で宣言しなければならない
      • StudlyCaps：単語の先頭を大文字にする記法（例：hoge → Hoge）
    • クラス定数名は、アンダースコア区切りで全て大文字で宣言しなければならない
      • アンダースコア区切りで全て大文字：hoge hoge → HOGE_HOGE
    • メソッド名はキャメルケース記法で宣言しなければならない
      • キャメルケース：単語の先頭を大文字にする記法（例：hoge hoge → HogeHoge）
      • ここではおそらくローワーキャメルケース（先頭の単語だけ小文字にし、後続の単語の先頭は大文字にする記法）を指してるだろう（例：hoge hoge → hogeHoge）

ファイル

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:

  • 概要の章で記載されてる内容とほとんど同じ内容が記載されてるが、一部実例が紹介されてる
    • 2.1では、PHPタグについて
      • PHPコードでは、<?php ?> および <?= ?> 以外のタグを使用してはいけない
    • 2.2では、文字コードについて
      • 文字コードは、UTF-8（BOM無し）を使用しなければならない
    • 2.3では、副作用について
      • 同一ファイル内で、シンボル（クラス、関数、定数など）を宣言する、あるいは副作用（出力の生成、.ini設定の変更など）を行うべきではない
      • 「副作用」とは、クラス、関数、定数などの宣言に直接関係しないロジックの実行を意味する
      • 以下のコードはシンボルの宣言と副作用の両方が記述されてるファイルの一例であり避けるべきものの例である
<?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:

  • 以下のコードは副作用のない宣言を含むファイルの例であり参考にすべきものの一例である
<?php
// declaration
function foo()
{
    // function body
}

// conditional declaration is *not* a side effect
if (! function_exists('bar')) {
    function bar()
    {
        // function body
    }
}

名前空間とクラス名

Namespaces and classes MUST follow an “autoloading” PSR: [PSR-0, PSR-4].

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.

  • 概要の章で記載されてる内容とほとんど同じ内容であるがこちらでは実例も記載されてる
    • 名前空間、クラスはオートロードPSR（PSR-0, PSR-4）に準拠する必要がある
    • クラス名は、StudlyCaps記法で宣言しなければならない
      • StudlyCaps：単語の先頭を大文字にする記法（例：hoge → Hoge）
    • PHP5.3以降のコードでは名前空間をしようしなければならない
    • 下記のコードはその一例
<?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.

  • PHP5.2.x以前のコードは、擬似名前空間規則としてクラス名の接頭辞（プレフィックス）にVendor_を使用する必要がある
  • 以下のその例を示す
<?php
// PHP 5.2.x and earlier:
class Vendor_Model_Foo
{
}

クラス定数、プロパティおよびメソッド

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.

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().

※4.1のサンプルコードは後続で記したいため上記には記載していない

  • 概要の章で記載されてる内容とほとんど同じ内容であるがこちらでは実例も記載されてる

    • 4.1 定数
      • クラス定数名は、アンダースコア区切りで全て大文字で宣言するしなければならない
        • アンダースコア区切りで全て大文字：hoge hoge → HOGE_HOGE
    • 4.2 プロパティ
      • このガイドでは、プロパティ名（StudlyCaps・camelCase・under_score）に関する推奨事項を避けてる
      • どのような命名規則が使用されても妥当な範囲内で一貫して適用されてる必要がある
      • スコープは、ベンダーレベル、パッケージレベル、クラスレベル、またはメソッドレベル
    • 4.3 メソッド
      • メソッド名はキャメルケース記法で宣言しなければならない
        • キャメルケース：単語の先頭を大文字にする記法（例：hoge hoge → HogeHoge）
        • ここではおそらくローワーキャメルケース（先頭の単語だけ小文字にし、後続の単語の先頭は大文字にする記法）を指してるだろう（例：hoge hoge → hogeHoge）

  • 4.1での定数に関する例を以下に記す

<?php
namespace Vendor\Model;

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

所感

  • なるほど感はあったがPHP歴1.5年生なのでさほど新鮮味はなかった
  • クラス名で提唱されてるStudlyCaps記法（≒キャメルケース）は初めて聞いたので「ほー、」という感じ
  • 当たり前のように記述してたコードに対して根拠が持てるようになった点は大きい、今一度規約を見返すことは有意義なことだと感じた

注意

  • 冒頭でも述べたように、主に箇条書きされてる箇所については、 和訳＋個人の解釈 の入った内容になっているため、参考程度の理解としていただきたい
  • また、表現に誤りがある場合、遠慮なくコメントいただけると幸いです（この内容に関しては表現の誤りは致命的なため）
  • 学習の一環としてアウトプットしたいため投稿したので、その点暖かい目で読んで頂けると嬉しい
1
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
2