====== Summary ======
===== Information =====
==== Document Information ====
  * Title: PEAR2 Class Naming Conventions
  * Version: 1.0.0
  * Status: Ratified
  * Type: Informative Document
  * Wiki link:  http://wiki.php.net/pear/rfc/PEAR2_Class_Naming
  * Last Updated:  September 20th, 2009
  * Passed:  September 20th, 2009

This RFC has been incorporated into the PEAR2 Standards ([[pear/rfc/pear2_standards]]).

==== Author(s) Information ====
  * Name:  Chuck Burgess
  * Name:  Brett Bieber
  * Email: [[pear-group@php.net]]

==== Legal Information ====
  * This RFC is under the BSD License

==== Discussion List ====
This RFC is currently being discussed only by pear-group; future discussion will occur on pear-dev[[http://news.php.net/php.pear.dev]].

This RFC's content is also being influenced by the new PHP Standards group [[http://news.php.net/php.standards]].

===== Introduction =====

With the introduction of namespaces in PHP 5.3, the PEAR1 rule of Package_Subpackage_ClassName naming (for creating pseudo-namespacing) is no longer necessary.  Package naming rules will be set by the [[pear/rfc/PEAR2_Naming_Standards]] RFC, whereas class naming rules are addressed here in this RFC.

The naming of individual classes retains these PEAR1 rules [1]:
  * 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 {}

New guidelines for PEAR2:
  * syntax/scope hints in the class name must be suffixed rather than prefixed, e.g. abstract class FooAbstract {}
    * such suffixing is required for abstract classes and interfaces, for additional clarity to non-native English readers [4]

===== Issues =====
A debate was originally spurred by the use of actual classes whose names, once namespaces removes their Several_Prefix_Layers_ from the name, will be just "Abstract" or "Interface" [2].  This prompted some discussion around various forms of "Hungarian Notation" in class naming, particularly for Abstract and Interface classes.  Part of this RFC addresses the justification for requiring such naming style [4].

===== Proposed Solution =====

Initial rules and guidelines:
  * a suffix for an Abstract or Interface class name is required
    * the extra naming is more legible to non-native English speakers [4]
  * the suffix should be a full legible word, not a cryptic letter/abbreviation (e.g. FooAbst, FooA)
    * this follows other well-known conventions (e.g. Java)

The only exception to the Interface suffix requirement is the base package exception, which must be named simply "Exception". [3]

One benefit of the suffix rather than a prefix is in alphabetical-based visual listing of classes.  Using prefixes would result in all unrelated abstract classes being listed togther... the same result would apply to all unrelated intefaces.

===== Examples =====
Here are some real-life examples gleaned from PEAR1 packages

  * Demonstrating the inherited PEAR1 naming rules
    * "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"

  * Demonstrating the new rules proposed by this RFC
    * "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"    

===== References =====
  * [1]  PEAR1 Coding Standards for Class Naming -- [[http://pear.php.net/manual/en/standards.naming.php]]
  * [2]  [[weierophinney]]'s original post about potential naming conflicts once Namespaces arrive -- [[http://weierophinney.net/matthew/archives/181-Migrating-OOP-Libraries-and-Frameworks-to-PHP-5.3.html]]
  * [3]  PHP Standards Group's first meeting decisions, from 2009 php|tek -- [[http://news.php.net/php.standards/2]]
  * [4]  [[weierophinney]]'s points on choosing Hungarian Notation, from the Standards meeting -- [[http://news.php.net/php.standards/22]]