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 14:55] – 5.3.0 is indeed the one introducing namespaces 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 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 84: Line 88:
 Classes may use longer namespaces, for instance an HTTP_Request class may instead choose to use this declarative syntax: Classes may use longer namespaces, for instance an HTTP_Request class may instead choose to use this declarative syntax:
  
-   ''<?php +   <?php 
-   namespace PEAR2::HTTP;+   namespace PEAR2\HTTP;
    class Request {}    class Request {}
-   ?>''+   ?>
  
 As such, underscores are no longer required of any classes if there is a namespace.  Class PEAR2_HTTP_Request As such, underscores are no longer required of any classes if there is a namespace.  Class PEAR2_HTTP_Request
-instead becomes PEAR2::HTTP::Request.+instead becomes PEAR2\HTTP\Request.
  
 Package names, however, will use underscores, making PEAR2_HTTP_Request the package name. Package names, however, will use underscores, making PEAR2_HTTP_Request the package name.
Line 108: Line 112:
    <?php    <?php
    require_once 'PEAR2/OtherPackage.php';    require_once 'PEAR2/OtherPackage.php';
-   $class = new PEAR2::OtherPackage;+   $class = new \PEAR2\OtherPackage;
    ?>    ?>
  
Line 114: Line 118:
  
    <?php    <?php
-   $class = new PEAR2::OtherPackage;+   $class = new \PEAR2\OtherPackage;
    ?>    ?>
        
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 159: Line 163:
 class_exists($classname, true) should be used where a "class not found" fatal error class_exists($classname, true) should be used where a "class not found" fatal error
 would be confusing.  For example, when loading a driver, a graceful exit via exception would be confusing.  For example, when loading a driver, a graceful exit via exception
-with helpful error message is preferrable to the fatal error:+with helpful error message is preferable to the fatal error:
  
    <?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.1253112929.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools