PHP Standards and Best Practices for PHP 5.3+ Frameworks and Libraries

Here are the minutes made by Brett Bieber after the meeting we had at PHP|Tek Greetings, We were able to get a group together with participants from many of the large frameworks, libraries, and community members to discuss standards regarding namespace usage, class/interface/abstract naming standards, and exceptions for 5.3+ PHP code. To summarize the discussion, three major issues regarding PHP 5.3+ standards, guidelines, and best-practices were discussed: **Namespaces** Namespaces should be all lowercase and must follow the following conention: <vendor>\<package_name>\ Examples: <?php namespace pear2\text_diff; namespace zend\controller; Underneath each namespace, the package can declare further sub-namespaces and classes. Each level under the namespace must be in a new directory and classes must map to the traditional PEAR1 style class name to directory structure. A patch will be submitted to php-src for PHP 5.3.x that will modify the SPL autoload functionality to attempt to autoload classes in the include_path using this schema. **Class and Interface naming** All classes, interfaces, and abstracts must begin with an uppercase character. They may contain additional capital letters and underscores. Any underscores in class names will be converted to the DIRECTORY_SEPARATOR when attempting to auto-load. Interfaces must be suffixed with Interface, abstract interfaces must be suffixed with Abstract. The only exception is a package base exception, which may be an interface or concrete class, but shall always be 'catchable' with: catch (vendor\packagename\Exception $exception), more details on exceptions in the Exceptions and Exception Handling section below. Examples: vendor\pacakgename\My_FooInterface -- maps to -> include_path/vendor/packagename/My/FooInterface.php vendor\pacakgename\HumanInterface -- maps to -> incude_path/vendor/packagename/HumanInterface.php vendor\pacakgename\TraversableInterface -- maps to -> incude_path/vendor/packagename/TraversableInterface.php vendor\pacakgename\CarAbstract -- maps to -> incude_path/vendor/packagename/CarAbstract.php vendor\pacakgename\Exception -- maps to -> incude_path/vendor/packagename/Exception.php **Exceptions and Exception Handling** Each package must provide a base exception of the following name: vendor\package\Exception This exception may be either an interface or class (concrete or abstract). Each exception thrown by "vendor\package" must throw exceptions that either extend or implement this base exception. Examples: File - vendor/packagename/Exception.php <?php namespace vendor\packagename; interface Exception {} File - vendor/packagename/UnexpectedValueException.php <?php namespace vendor\packagename; class UnexpectedValueException extends UnexpectedValueException implements Exception {} Exception throwing example: File - vendor/packagename/Foo.php; <?php namespace vendor\packagename; class Foo { function run($method) { switch($method) { case 'add': case 'del': case 'up': $this->$method(); break; default: throw new UnexpectedValueException($method . ' is not a valid method.'); } } } User exception catching example: <?php try { $p = new vendor\packagename\Foo(); $p->run('bar'); } catch (vendor\packagename\Exception $e) { echo "Caught exception from vendor\\packagename"; } The goal of this meeting was to develop a set of common standards which PHP projects can strive towards adopting. Each project may have specific standards which may extend and further define how these standards should be used, but the goal being a set of PHP standards provided as a resource for all PHP developers. A central, moderated mailing list to discuss PHP coding standards was proposed, to be hosted on lists.php.net. The list shall have public archives and unmoderated posting privileges will be granted by election by those with posting privileges. Each major project may have more than one member, but each project shall have only 1 vote towards standards decisions and membership. A list of those present at the meeting on 2009-05-21: Agavi - David Zülke Cake - Nate Abele PEAR - Brett Bieber, David Coallier, Helgi Þormar Þorbjörnsson, Travis Swicegood, Phing - Travis Swicegood Solar - Paul Jones Symfony - Stefan Koopmanschap Zend Framework - Matthew Weier O'Phinney and the always amiable (i.e., at-large community member), Cal Evans. I think I speak for everyone when I say THANK YOU for participating in the discussion and sharing your opinions. :-)