PSR-1 Coding Style Guide (multi-chapter)

proposed/psr-1-coding-style-guide/0000-preamble.md

@@ -0,0 +1,21 @@
+Preamble
+========
+
+The goal for this guide is to increase consistency in style across disparate
+PHP projects written by multiple authors. It is intended to serve as a
+reference for reasonable expectations so as to reduce cognitive friction when
+scanning code from different projects.
+
+This style guide is not a moral or ethical statement. It is an attempt to
+agree upon a common set of rules, requirements, recommendations, idioms, and
+approaches for code formatting. Any such guide is by nature arbitrary. The
+benefit is in the adherence to the rules, not in the rules themselves.
+
+There are times when a particular rule or recommendation will not make sense
+in a particular limited context. Breaking the rule or recommendation in that
+particular limited context does not mean the remainder of the codebase under
+consideration is not PSR-1 compliant; instead, it is to be recognized as a
+regrettable but necessary departure from the guide for that one circumstance.
+
+This guide is derived from commonalities between Horde, PEAR, Solar, Symfony,
+Zend, and other projects.

proposed/psr-1-coding-style-guide/0100-php-tags.md

@@ -0,0 +1,9 @@
+PHP Tags
+========
+
+Use the long `<?php ?>` tags for PHP code. Use of short-echo `<?= ?>` tags is
+also allowed. Do not use the other tag variations.
+
+Cf. <http://php.net/manual/en/language.basic-syntax.phpmode.php>
+
+In files that contain only PHP, leave out the closing PHP tag.

proposed/psr-1-coding-style-guide/0200-indenting-and-line-length.md

@@ -0,0 +1,45 @@
+Indenting and Line Length
+=========================
+
+Indenting
+---------
+
+Use an indent of 4 spaces. Do not use tabs. The use of spaces helps to avoid
+problems with diffs, patches, history, and annotations, and provides
+fine-grained sub-indentation when aligning elements on consecutive lines.
+
+Line Length
+-----------
+
+Lines should be limited to 75-85 characters in length. This is based on known
+human cognitive limitations, not the technical limitations of screen windows
+or text editors. When necessary, it is allowed to split a single statement
+across subsequent lines, per rules noted elsewhere in this guide.
+
+Some further insight into the 75-85 characters rule:
+
+> How many words per line can a person scan, and still be able to grasp the
+> content of the line in the context of the surrounding lines? Printing and
+> publishing typographers figured out a long time ago that most people can
+> read no more than 10 to 12 words per line before they have trouble
+> differentiating lines from each other. (A “word” is counted as five
+> characters on average.) Even allowing for a 25% to 50% increase, that
+> brings us up to 15 words. Times 5 characters per word, that means 75
+> characters on a line.
+> 
+> So the style guide limitation on line length is not exactly arbitrary. It
+> is about the developer’s ability to effectively scan and comprehend
+> strings of text, not about the technical considerations of terminals and
+> text-editors.
+
+-- "Line Length, Volume, and Density"
+   <http://paul-m-jones.com/archives/276>
+
+
+Other Considerations
+--------------------
+
+Code blocks may have as many blank lines as needed to increase readability
+and comprehension.
+
+Do not add trailing spaces at the end of lines.

proposed/psr-1-coding-style-guide/0300-namespace-use-and-class.md

@@ -0,0 +1,54 @@
+`namespace`, `use`, and `class`
+===============================
+
+All namespaces and classes should be named with PSR-0 in mind. This means each
+class should be in a file by itself, and should be in a namespace of at least
+two levels: a top-level vendor name, and a second-level package name within
+that vendor.
+
+Class names are always in `StudlyCase`. The class declaration should have one
+empty line above it. The opening and closing braces for the class go on their
+own line.
+
+    <?php
+    namespace Vendor\Package;
+
+    class ClassName
+    {
+        // constants, properties, methods
+    }
+
+The `use` declarations go immediately after the namespace declaration with no
+line separating them. There should be one `use` keyword per declaration.
+
+    <?php
+    namespace Vendor\Package;
+    use FooClass;
+    use BarClass as Bar;
+    use OtherVendor\OtherPackage\BazClass;
+
+    class ClassName
+    {
+        // constants, properties, methods
+    }
+
+The `extends` and `implements` keywords should be on the same line as the
+class name. Lists of `implements` that exceed the line length limit may be
+split across multiple lines, where each subsequent line is indented once.
+List only one interface per line.
+
+    <?php
+    namespace Vendor\Package;
+    use FooClass;
+    use BarClass as Bar;
+    use OtherVendor\OtherPackage\BazClass;
+
+    class ClassName extends ParentClass implements
+        InterfaceName,
+        AnotherInterfaceName,
+        YetAnotherInterface,
+        InterfaceInterface
+    {
+        // constants, properties, methods
+    }
+

proposed/psr-1-coding-style-guide/0400-constants.md

@@ -0,0 +1,29 @@
+Constants
+=========
+
+The PHP keywords `true`, `false`, and `null` are all lower case all the time.
+
+All other user-defined constants are all upper case all the time, with
+underscore separators.
+
+    <?php
+    namespace Vendor\Package;
+
+    class ClassName
+    {
+        const CONSTANT_NAME = 'constant value';
+    }
+
+Global constants are strongly discouraged. Instead, create namespaced
+constants for the vendor and package:
+
+    <?php
+    namespace Vendor\Package;
+    const CONSTANT_NAME = 'constant_value';
+
+If a global constant is absolutely unavoidable, prefix it with the vendor and
+package name:
+
+    <?php
+    define('VENDOR_PACKAGE_CONSTANT_NAME', 'constant_value');
+

proposed/psr-1-coding-style-guide/0500-variable-and-property-names.md

@@ -0,0 +1,32 @@
+Variable And Property Names
+===========================
+
+This guide expressly avoids any requirement regarding the use of
+`$StudlyCase`, `$camelCase`, or `$under_score` variable and property names. It
+is often the case that variable names map directly field names in external
+data sources. Changing between naming conventions when changing contexts
+merely to suit a style guide would be counterproductive in such cases.
+
+Some projects prefix property names with a single underscore to indicate a
+protected or private visibility. This guide discourages but does not disallow
+that practice.
+
+Whatever naming convention is used should be applied consistently within a
+reasonable scope. That scope may be vendor-level, package-level, class-level,
+or function-level.
+
+Class properties should explicitly note the visibility keyword.
+
+    <?php
+    namespace Vendor\Package;
+
+    class ClassName
+    {
+        public $property = null;
+    }
+
+Global variables are strongly discouraged. If a global variable is absolutely
+unavoidable, it should be prefixed with the vendor and package name.
+
+    <?php
+    $Vendor_Package_VariableName = 'variable_value';

proposed/psr-1-coding-style-guide/0600-variable-and-property-assignment.md

@@ -0,0 +1,86 @@
+Variable and Property Assignment
+================================
+
+Single Assignment
+-----------------
+
+Assignment looks like the following.
+
+    $foo = 'value';
+
+To support readability, contiguous assignments may be aligned on the equals
+sign:
+
+    $short  = fooBar($baz);
+    $longer = dibGir($zim);
+
+
+Multi-Line Assignment
+---------------------
+
+Assignments may be split onto several lines when the line length limit is
+exceeded. The equals sign has to be positioned onto the following line, and
+indented once.
+
+    $this->longArrayPropertyName[$this->someOtherPropertyValue]
+        = $object->getFunctionResult(ClassName::CONSTANT_VALUE);
+
+Similarly, when concatenating strings across multiple lines, align the dot
+operator with the equals:
+
+    $foo = 'prefix string '
+         . $object->getSomeStringResult()
+         . ' suffix string';
+
+    $bar .= 'prefix string '
+          . $object->getSomeStringResult()
+          . ' suffix string';
+
+
+Ternary Assignment
+------------------
+
+Ternary assignments may be split onto subsequent lines when the exceed the
+line length limit, or when the would be more readable. Align the question mark
+and colon with the equals sign.
+
+    $foo = ($expression1 && $expression2)
+         ? $foo
+         : $bar;
+
+    $bar = ($expression3 && $expression4)
+         ? $a_very_long_variable_name
+         : $bar;
+
+
+Assignment By Reference
+-----------------------
+
+When assigning by reference, the `&` should be attached to the variable, not
+the operator:
+
+    // incorrect
+    $foo =& $bar;
+
+    // correct
+    $foo = &$bar;
+
+
+Array Assignment
+----------------
+
+Array assignments may be split across subsequent lines if they would otherwise
+break the line length limit, or if it would improve readability. They should be
+indented once per array, and should be aligned on the `=>` double arrow. The
+last value in each array should have a trailing comma; this is valid syntax
+and reduces the chance of syntax violations when adding new elements.
+
+    $an_array = [
+        'foo'      => 'bar',
+        'subarray' => [
+            'baz'  => 'dib',
+            'zim'  => 'gir',
+        ],
+        'irk'      => 'doom',
+    ];
+

proposed/psr-1-coding-style-guide/0700-function-and-method-declarations.md

@@ -0,0 +1,90 @@
+Function And Method Declarations
+================================
+
+Function and method names are in `camelCase`.
+
+Some projects prefix function and method names with a single underscore to
+indicate a protected or private visibility. This guide discourages but does
+not disallow that practice.
+
+
+Functions
+---------
+
+A function declaration looks like the following. Note the placement of
+parentheses, commas, spaces, and braces:
+
+    <?php
+    namespace Vendor\Package;
+
+    function fooBarBaz($arg1, &$arg2, $arg3 = [], $arg4 = null)
+    {
+        // function body
+    }
+
+This guide encourages using static class methods rather than functions; doing
+so helps to support autoloading.
+
+Global functions are strongly discouraged. If a global function is
+unavoidable, prefix it with the vendor and package name.
+
+    <?php
+    function Vendor_Package_FunctionName()
+    {
+        // function body
+    }
+
+
+Methods
+-------
+
+Class methods are always be prefixed with an explicit visibility keyword:
+
+    <?php
+    public function fooBarBaz($arg1, &$arg2, $arg3 = [], $arg4 = null)
+    {
+        // function body
+    }
+
+Static methods always have the `static` keyword before the visibility keyword:
+
+    <?php
+    static public function fooBarBaz($arg1, &$arg2, $arg3 = [], $arg4 = null)
+    {
+        // function body
+    }
+
+
+Arguments
+---------
+
+Arguments with default values always go at the end of the argument list.
+
+Argument lists that exceed the line length limit may be split across
+subsequent indented lines. There is only one argument per line. The closing
+parenthesis and opening brace are placed together on their own line.
+
+    <?php
+    static public function fooBarBaz(
+        ClassTypeHint $arg1,
+        &$arg2,
+        array $arg3 = [],
+        $arg4 = null
+    ) {
+        // function body
+    }
+
+Anonymous Functions and Closures
+--------------------------------
+
+Declaration of anonymous functions looks like this; note the placement of
+parentheses, commas, spaces and braces:
+
+    $foo = function ($bar, $baz) use ($zim, $gir) {
+        // body of the function
+    };
+
+This is a departure from the "normal" function and method declaration. Because
+`function` is a keyword, it gets a space after it; the same is true for `use`.
+The opening brace goes on the same line as the declaration; the body is
+indented once; and the closing brace goes on its own outdented line.