pear:rfc:pear2_standards

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
pear:rfc:pear2_standards [2009/09/16 15:25] – update namespace separator ashnazgpear:rfc:pear2_standards [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 6: Line 6:
  
   * Title: PEAR2 Coding Standards   * Title: PEAR2 Coding Standards
-  * Version:   0.5.0+  * Version:   0.6.0
   * Status:    Draft   * Status:    Draft
   * Type:      Standards   * Type:      Standards
-  * Last updated: October 6th2007+  * Last updated: September 20th2009 
 ==== Author(s) Information ==== ==== Author(s) Information ====
 +  * Name:  Chuck Burgess
 +  * Email:  ashnazg@php.net
  
 +==== Past Author(s) Information ====
   * Name:  Gregory Beaver, Arnaud Limbourg   * Name:  Gregory Beaver, Arnaud Limbourg
   * Email: cellog@php.net, arnaud@php.net   * Email: cellog@php.net, arnaud@php.net
Line 138: Line 142:
   * construct a customized solution for loading needed files   * construct a customized solution for loading needed files
  
-In all cases, the bonus of loading needed files is shifted to the end user.  However, for beginning users, the only required step is to+In all cases, the onus of loading needed files is shifted to the end user.  However, for beginning users, the only required step is to
 load PEAR2/Autoload.php, which will be always bundled with new packages, but only extracted if used as unzip-and-go (pyrus would simply install load PEAR2/Autoload.php, which will be always bundled with new packages, but only extracted if used as unzip-and-go (pyrus would simply install
 the dependency on PEAR2, which would contain the needed base files PEAR2_Exception and PEAR2_Autoload). the dependency on PEAR2, which would contain the needed base files PEAR2_Exception and PEAR2_Autoload).
Line 162: Line 166:
  
    <?php    <?php
-   if (!class_exists("PEAR2_PackageName_Driver_$class", true)) {+   if (!class_exists("\PEAR2\PackageName\Driver\$class", true)) {
        throw new \PEAR2\PackageName\Exception('Unknown driver ' . $class .        throw new \PEAR2\PackageName\Exception('Unknown driver ' . $class .
                  ', be sure the driver exists and is loaded prior to use');                  ', be sure the driver exists and is loaded prior to use');
Line 199: Line 203:
  
 ==== Class-to-file convention ==== ==== Class-to-file convention ====
 +All public classes must be in their own file with underscores (_) or namespace separators (\) replaced by directory separator, so that PEAR2_PackageName_Base class or PEAR2\PackageName\Base class is always located in PEAR2/PackageName/Base.php (this is required to make autoload work).
  
 +=== Requirement ===
 +Exceptions may be made to this rule only with explicit approval from the PEAR Group via a public vote.
 +
 +
 +==== Class Naming convention ====
 +
 +The naming of individual classes follows these rules:
 +  * Start with capital letter, e.g. class Foo {}
 +  * CamelCase for multi-worded class names, e.g. class FooBarBaz {}
 +  * Abbreviations only start with capital letter, e.g. class MrClean {}
 +  * Acronyms should be fully capitalized, e.g. class PEARTree {}
 +  * syntax/scope hints in the class name must be suffixed rather than prefixed, e.g. abstract class FooAbstract {}
 +    * the suffix should be a full legible word, not a cryptic letter/abbreviation (e.g. FooAbst, FooA)
 +    * a suffix for an Abstract or Interface class name is *required*
 +
 +The only exception to the Interface suffix requirement is the base package exception, which must be named simply "Exception".
 +
 +
 +=== Examples ===
 +Here are some real-life examples gleaned from PEAR1 packages:
 +  * "class Text_Diff" in /Text/Diff.php becomes "class Diff"
 +  * "class DB_DataObject" in /DB_DataObject/DataObject.php becomes "class DataObject"
 +  * "class Auth_PrefManager" in /Auth_PrefManager/PrefManager.php becomes "class PrefManager"
 +  * "class Services_Amazon_SQS" in Services_Amazon_SQS/Services/Amazon/SQS.php becomes "class SQS"
 +  * "abstract class PHP_CodeSniffer_Standards_AbstractPatternSniff" in PHP_CodeSniffer/CodeSniffer/Standards/AbstractPatternSniff.php becomes "abstract class PatternSniffAbstract"
 +  * "interface Testing_DocTest_RunnerInterface" in Testing/DocTest/RunnerInterface.php becomes "interface RunnerInterface", or perhaps "interface RunnableInterface"
  
-All public classes must be in their own file with underscores (_) or namespace separators (::) replaced by directory separator, so that PEAR2_PackageName_Base class or PEAR2::PackageName::Base class is always located in PEAR2/PackageName/Base.php (this is required to make autoload work) 
  
 === Requirement === === Requirement ===
 +The only exception to this rule is the Base Package Exception Interface, which is specifically required to be named "vendor\Package\Exception" rather than "vendor\Package\ExceptionInterface".
  
-Exceptions may be made to this rule only with explicit approval from the PEAR Group via a public vote 
-==== Base Exception class ==== 
  
  
-PEAR2::Exception is used as base class for all exception classes.  Each package must define a base class that is <packagename>_Exception.  For example, the PEAR2::PackageName class defines an exception as follows in PEAR2/PackageName/Exception.php:+==== Base Exception interface ====
  
-   <?php +Each package must define a base Exception interface which is implemented by any exception thrown within the package. 
-   namespace PEAR2::PackageName; + 
-   class Exception extends PEAR2::Exception {} +**PEAR2/PackageName/Exception.php** 
-   ?>+<code php> 
 + <?php  
 + namespace PEAR2\PackageName; 
 + interface Exception {} 
 +</code> 
 + 
 + 
 +SPL exceptions are encouraged, and should be used when possible. 
 + 
 +Extending SPL Example: 
 +**PEAR2/PackageName/UnexpectedValueException.php** 
 +<code php> 
 + <?php 
 + namespace PEAR2\PackageName; 
 + class UnexpectedValueException extends \UnexpectedValueException implements Exception {} 
 +</code> 
 + 
 + 
 +Exception throwing example: 
 +<code php> 
 + <?php 
 + namespace PEAR2\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.'); 
 +         } 
 +     } 
 + } 
 +</code> 
 + 
 + 
 +User exception catching example: 
 +<code php> 
 + <?php 
 + require_once 'PEAR2/Autoload.php'; 
 + try { 
 +     $p = new \PEAR2\PackageName\Foo(); 
 +     $p->run('bar'); 
 + } catch (\PEAR2\PackageName\Exception $e) { 
 +     echo "Caught exception from PEAR2\\PackageName"; 
 + 
 +</code>
  
-''PEAR2::Exception will be its own package'' 
  
 === Requirement === === Requirement ===
 +No Exceptions to this rule
  
-'''No Exceptions to this rule''' 
  
 ==== Data files ==== ==== Data files ====
Line 233: Line 311:
    ...    ...
    // retrieve data from info.txt    // retrieve data from info.txt
-   $info = file_get_contents(dirname(__FILE__) . '../../../data/pear2.php.net/PEAR2_PackageName/info.txt');+   $info = file_get_contents(dirname(__FILE__) . '/../../../data/pear2.php.net/PEAR2_PackageName/info.txt');
    ?>    ?>
  
pear/rfc/pear2_standards.1253114722.txt.gz · Last modified: 2017/09/22 13:28 (external edit)