Permalink
Browse files

Merge remote-tracking branch 'upstream/master'

  • Loading branch information...
evert committed Oct 22, 2012
2 parents 96c2cdf + 74ef01f commit 4234316a2697b82ab8440dead62d06e99e8e352a
Showing with 1,144 additions and 32 deletions.
  1. +85 −3 README.md
  2. +39 −29 accepted/PSR-0.md
  3. +172 −0 accepted/PSR-1-basic-coding-standard.md
  4. +803 −0 accepted/PSR-2-coding-style-guide.md
  5. +45 −0 bylaws/001-voting-protocol.md
View
@@ -1,4 +1,86 @@
-Repository for maintaining Framework Interop Group specification proposals.
+PHP Framework Interoperability Group
+====================================
-In order to propose fork, add document, send a PR. Alternatively simply create a ticket
-to start a discussion.
+
+Proposing a Standards Recommendation
+------------------------------------
+
+To propose a standards recommendation (PSR):
+
+- fork this repo, create a branch, checkout that branch, add the PSR in
+ `proposed/`, push the branch to Github, and send a pull request; or,
+
+- create a ticket to start a discussion on Github; or,
+
+- start a conversation on the [mailing list][].
+
+[mailing list]: http://groups.google.com/group/php-fig/
+
+
+Requesting Membership
+---------------------
+
+You **do not** need to be a voting member to participate in discussion on
+the [mailing list][].
+
+To become a voting member, you must send an email to the [mailing list][].
+
+- The subject line should read: `Membership Request: {$your_name} ({$project_name})`
+
+- The body should include your name, the name of (and link to) the project you
+ represent, and other details you feel are relevant.
+
+Current members will vote on your request.
+
+Do not combine separate membership requests in a single thread; one request
+per thread, please.
+
+
+Voting Members
+--------------
+
+1. Nate Abele: Lithium
+
+1. Nils Adermann: phpBB
+
+1. Brett Bieber: PEAR, PEAR2
+
+1. Guilherme Blanco: Doctrine, Doctrine2, et al.
+
+1. Jordi Boggiano: Composer, Packagist
+
+1. Karma Dordrak: Zikula
+
+1. Paul Dragoonis: PPI, PPI2
+
+1. William Durand: Propel, Propel 2
+
+1. Andrew Eddie: Joomla
+
+1. Cal Evans: the community at large
+
+1. Larry Garfield: Drupal
+
+1. Paul M. Jones: Solar Framework, Aura Project
+
+1. Robert Lemke: FLOW3
+
+1. Larry Masters: CakePHP, CakePHP 2
+
+1. Ryan Parman: Amazon Web Services SDK
+
+1. Evert Pot: SabreDAV
+
+1. Fabien Potencier: Symfony, Symfony2
+
+1. Andre Romcke: eZ Publish
+
+1. Paul Scott: Chisimba, C4
+
+1. Phil Sturgeon: PyroCMS
+
+1. Kris Wallsmith: Assetic, Buzz
+
+1. Matthew Weier O'Phinney: Zend Framework, Zend Framework 2
+
+1. David Zülke: Agavi
View
@@ -1,63 +1,73 @@
The following describes the mandatory requirements that must be adhered
to for autoloader interoperability.
-## Mandatory:
+Mandatory
+---------
+
* A fully-qualified namespace and class must have the following
- structure \<Vendor Name>\(<Namespace>\)*<Class Name>
+ structure `\<Vendor Name>\(<Namespace>\)*<Class Name>`
* Each namespace must have a top-level namespace ("Vendor Name").
* Each namespace can have as many sub-namespaces as it wishes.
-* Each namespace separator is converted to a DIRECTORY_SEPARATOR when
+* Each namespace separator is converted to a `DIRECTORY_SEPARATOR` when
loading from the file system.
* Each "\_" character in the CLASS NAME is converted to a
- DIRECTORY_SEPARATOR. The "\_" character has no special meaning in the
+ `DIRECTORY_SEPARATOR`. The "\_" character has no special meaning in the
namespace.
* The fully-qualified namespace and class is suffixed with ".php" when
loading from the file system.
* Alphabetic characters in vendor names, namespaces, and class names may
be of any combination of lower case and upper case.
-## Examples:
-* \Doctrine\Common\IsolatedClassLoader => /path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php
-* \Symfony\Core\Request => /path/to/project/lib/vendor/Symfony/Core/Request.php
-* \Zend\Acl => /path/to/project/lib/vendor/Zend/Acl.php
-* \Zend\Mail\Message => /path/to/project/lib/vendor/Zend/Mail/Message.php
+Examples
+--------
+
+* `\Doctrine\Common\IsolatedClassLoader` => `/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php`
+* `\Symfony\Core\Request` => `/path/to/project/lib/vendor/Symfony/Core/Request.php`
+* `\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php`
+* `\Zend\Mail\Message` => `/path/to/project/lib/vendor/Zend/Mail/Message.php`
+
+Underscores in Namespaces and Class Names
+-----------------------------------------
-## Underscores in namespaces and class names:
-* \namespace\package\Class_Name => /path/to/project/lib/vendor/namespace/package/Class/Name.php
-* \namespace\package_name\Class_Name => /path/to/project/lib/vendor/namespace/package_name/Class/Name.php
+* `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php`
+* `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php`
The standards we set here should be the lowest common denominator for
painless autoloader interoperability. You can test that you are
following these standards by utilizing this sample SplClassLoader
implementation which is able to load PHP 5.3 classes.
-## Example Implementation
+Example Implementation
+----------------------
Below is an example function to simply demonstrate how the above
proposed standards are autoloaded.
+```php
+<?php
- <?php
-
- function autoload($className)
- {
- $className = ltrim($className, '\\');
- $fileName = '';
- $namespace = '';
- if ($lastNsPos = strripos($className, '\\')) {
- $namespace = substr($className, 0, $lastNsPos);
- $className = substr($className, $lastNsPos + 1);
- $fileName = str_replace('\\', DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;
- }
- $fileName .= str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php';
-
- require $fileName;
+function autoload($className)
+{
+ $className = ltrim($className, '\\');
+ $fileName = '';
+ $namespace = '';
+ if ($lastNsPos = strripos($className, '\\')) {
+ $namespace = substr($className, 0, $lastNsPos);
+ $className = substr($className, $lastNsPos + 1);
+ $fileName = str_replace('\\', DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;
}
+ $fileName .= str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php';
-## SplClassLoader Implementation
+ require $fileName;
+}
+```
+
+SplClassLoader Implementation
+-----------------------------
The following gist is a sample SplClassLoader implementation that can
load your classes if you follow the autoloader interoperability
standards proposed above. It is the current recommended way to load PHP
5.3 classes that follow these standards.
* [http://gist.github.com/221634](http://gist.github.com/221634)
+
@@ -0,0 +1,172 @@
+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][].
+
+[RFC 2119]: http://www.ietf.org/rfc/rfc2119.txt
+[PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
+
+
+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 [PSR-0][].
+
+- 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:
+
+```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:
+
+```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 [PSR-0][].
+
+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:
+
+```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.
+
+```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:
+
+```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()`.
Oops, something went wrong.

0 comments on commit 4234316

Please sign in to comment.