pear:rfc:pear2_standards
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
pear:rfc:pear2_standards [2009/09/16 14:55] – 5.3.0 is indeed the one introducing namespaces ashnazg | pear: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: | + | * Version: |
* Status: | * Status: | ||
* Type: Standards | * Type: Standards | ||
- | * Last updated: | + | * Last updated: |
==== Author(s) Information ==== | ==== Author(s) Information ==== | ||
+ | * Name: Chuck Burgess | ||
+ | * Email: | ||
+ | ==== Past Author(s) Information ==== | ||
* Name: Gregory Beaver, Arnaud Limbourg | * Name: Gregory Beaver, Arnaud Limbourg | ||
* Email: cellog@php.net, | * Email: cellog@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: | ||
- | '' | + | <? |
- | | + | |
class Request {} | class Request {} | ||
- | ?>'' | + | ?> |
As such, underscores are no longer required of any classes if there is a namespace. | As such, underscores are no longer required of any classes if there is a namespace. | ||
- | instead becomes PEAR2::HTTP::Request. | + | instead becomes PEAR2\HTTP\Request. |
Package names, however, will use underscores, | Package names, however, will use underscores, | ||
Line 108: | Line 112: | ||
<? | <? | ||
| | ||
- | | + | |
?> | ?> | ||
Line 114: | Line 118: | ||
<? | <? | ||
- | | + | |
?> | ?> | ||
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/ | load PEAR2/ | ||
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, | class_exists($classname, | ||
would be confusing. | would be confusing. | ||
- | with helpful error message is preferrable | + | with helpful error message is preferable |
<? | <? | ||
- | if (!class_exists(" | + | if (!class_exists(" |
- | throw new PEAR2::PackageName::Exception(' | + | throw new \PEAR2\PackageName\Exception(' |
', | ', | ||
} | } | ||
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/ | ||
+ | === 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, | ||
+ | * syntax/ | ||
+ | * the suffix should be a full legible word, not a cryptic letter/ | ||
+ | * 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 " | ||
+ | |||
+ | |||
+ | === Examples === | ||
+ | Here are some real-life examples gleaned from PEAR1 packages: | ||
+ | * "class Text_Diff" | ||
+ | * "class DB_DataObject" | ||
+ | * "class Auth_PrefManager" | ||
+ | * "class Services_Amazon_SQS" | ||
+ | * " | ||
+ | * " | ||
- | 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:: | ||
=== Requirement === | === Requirement === | ||
+ | The only exception to this rule is the Base Package Exception Interface, which is specifically required to be named " | ||
- | Exceptions may be made to this rule only with explicit approval from the PEAR Group via a public vote | ||
- | ==== Base Exception class ==== | ||
- | PEAR2::Exception | + | ==== Base Exception |
- | <?php | + | Each package must define a base Exception interface which is implemented by any exception thrown within the package. |
- | | + | |
- | | + | **PEAR2/ |
- | ?> | + | <code php> |
+ | <?php | ||
+ | | ||
+ | | ||
+ | </ | ||
+ | |||
+ | |||
+ | SPL exceptions are encouraged, and should be used when possible. | ||
+ | |||
+ | Extending SPL Example: | ||
+ | **PEAR2/ | ||
+ | <code php> | ||
+ | <? | ||
+ | | ||
+ | | ||
+ | </ | ||
+ | |||
+ | |||
+ | Exception throwing example: | ||
+ | <code php> | ||
+ | <? | ||
+ | | ||
+ | class Foo | ||
+ | { | ||
+ | | ||
+ | { | ||
+ | | ||
+ | case ' | ||
+ | case ' | ||
+ | case ' | ||
+ | | ||
+ | | ||
+ | | ||
+ | throw new UnexpectedValueException($method . ' is not a valid method.' | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | User exception catching example: | ||
+ | <code php> | ||
+ | <? | ||
+ | | ||
+ | try { | ||
+ | $p = new \PEAR2\PackageName\Foo(); | ||
+ | | ||
+ | } catch (\PEAR2\PackageName\Exception | ||
+ | echo " | ||
+ | } | ||
+ | </code> | ||
- | '' | ||
=== Requirement === | === Requirement === | ||
+ | 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__) . ' | + | $info = file_get_contents(dirname(__FILE__) . '/../ |
?> | ?> | ||
pear/rfc/pear2_standards.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1