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
Last revisionBoth sides next revision
pear:rfc:pear2_standards [2009/09/16 15:29] – update namespace separator ashnazgpear:rfc:pear2_standards [2010/06/15 15:21] – Correct path to data file saltybeagle
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 6th, 2007+  * Last updated: September 20th, 2009 
 ==== 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: 
  
-   <?php +==== Base Exception interface ==== 
-   namespace PEAR2\PackageName; + 
-   class Exception extends \PEAR2\Exception {} +Each package must define a base Exception interface which is implemented by any exception thrown within the package. 
-   ?>+ 
 +**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 in its own package. 
  
 === Requirement === === Requirement ===
 No Exceptions to this rule No Exceptions to this rule
 +
  
 ==== Data files ==== ==== Data files ====
Line 231: 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.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools