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 21:42] – add note about the package naming RFC 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.1+  * Version:   0.6.0
   * Status:    Draft   * Status:    Draft
   * Type:      Standards   * Type:      Standards
-  * Last updated: September 16th, 2009+  * Last updated: September 20th, 2009
  
 ==== Author(s) Information ==== ==== Author(s) Information ====
Line 166: 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 210: Line 210:
  
 ==== Class Naming convention ==== ==== Class Naming convention ====
-A class naming rule may potentially be added to these standards, if the [[pear/rfc/pear2_class_naming]] RFC is adopted. 
  
-==== Package Naming convention ==== +The naming of individual classes follows these rules: 
-A package naming rule may potentially be added to these standards, if the [[pear/rfc/pear2_naming_standards]] RFC is adopted.+  * 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*
  
-==== Base Exception class ==== +The only exception to the Interface suffix requirement is the base package exception, which must be named simply "Exception".
-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 
-   namespace PEAR2\PackageName; 
-   class Exception extends \PEAR2\Exception {} 
-   ?> 
  
-PEAR2\Exception will be in its own package.+=== 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" 
 + 
 + 
 +=== 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". 
 + 
 + 
 + 
 +==== Base Exception interface ==== 
 + 
 +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> 
  
 === Requirement === === Requirement ===
 No Exceptions to this rule No Exceptions to this rule
  
-=== Potential Alteration === 
-This rule could potentially be altered by the [[pear/rfc/pear2_exception_policy]] RFC. 
  
 ==== Data files ==== ==== Data files ====
Line 242: 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.1253137374.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools