cvs: peardoc /en/chapters pear2cs.xml

arnaud		Mon Nov 26 22:07:24 2007 UTC

  Added files:                 
    /peardoc/en/chapters	pear2cs.xml 
  Log:
  add draft of PEAR2CS (transerring from the wiki)
  
  

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/pear2cs.xml?view=markup&rev=1.1
Index: peardoc/en/chapters/pear2cs.xml
+++ peardoc/en/chapters/pear2cs.xml
<?xml version="1.0" encoding="utf-8" ?>
<!-- $Revision: 1.1 $ -->
 <chapter id="pear2cs">
  <chapterinfo>
   <date>2007-11-26</date>
  </chapterinfo>
  <title>PEAR2 Coding Standards</title>
  <subtitle>Coding Standards to be used in PEAR2</subtitle>
  <simpara>
   <itemizedlist>
    <listitem>
     This document describes the coding standards and coding conventions for the
     new PEAR2 repository.
    </listitem>
    <listitem>
     These coding standards will expire on March 1, 2008, and must be reviewed
     and renewed by the PEAR Group in
     order to continue
    </listitem>
    <listitem>
     Packages that wish to be accepted into the PEAR2 repository must conform to
     these standards
    </listitem>
    <listitem>
     The minimum PHP version supported will be the earliest version that
     supports namespaces,
     most likely PHP version 5.3.0.  This RFC will be updated as soon as the
     exact version is
     known.
    </listitem>
    <listitem>
     No Exceptions to this rule
    </listitem>
    <listitem>
     package.xml 2.0 or newer is required for all packages
    </listitem>
   </itemizedlist>
  </simpara>


  <sect1 id="pear2cs.introduction">
   <title>Introduction</title>
   <para>
    PEAR 1.x is very successful at managing the universe of PEAR-installable
    code.
    The new Pyrus installer is designed to expand that universe to include
    code that
    can also be easily embedded in non-PEAR applications and that runs
    identically
    when simply unzipped and when installed.  The PEAR2 repository must adhere
    to
    different coding conventions than the PEAR repository to make this
    possible.

    This document itemizes all the changes to existing rules and coding
    standards.
   </para>

   <para>
    require_once introduces a rigidity to package structure that limits the
    possible uses of a PEAR package.
    Some of the problems:

    <itemizedlist>
     <listitem>
     require_once can introduce up to a 10% performance penalty on
     high-volume sites using multi-processor web servers due to increased
     latency.  However, most users would experience at most 2% performance
     penalty on single-processor systems (as measured by Yahoo! engineer
     Gopal Vijayaraghavan)
     </listitem>
     <listitem>
     include_path is required in order to use a package.  This makes it
     difficult to bundle a PEAR package within another application with its
     own include_path, to create a single file containing needed classes, to
     move a PEAR package to a phar archive without extensive source code
     modification.
     </listitem>
     <listitem>
     when top-level require_once is mixed with conditional require_once, this
     can result in code that is uncacheable by opcode caches such as APC,
     which will be bundled with PHP 6.
     </listitem>
     <listitem>
     relative require_once requires that include_path already be set up to
     the correct value, making it impossible to use a package without proper
     include_path
     </listitem>
    </itemizedlist>
   </para>

   <para>
    Some of the benefits of require_once:
    <itemizedlist>
     <listitem>
      you know right away if a file is missing, with a Fatal Error: missing
      file X (this is mitigated by using __autoload() with PEAR2_Autoload())
     </listitem>
     <listitem>
      end-users don't need to know what files are within a package to use it.
      (also mitigated by using __autoload() with PEAR2_Autoload())
     </listitem>
    </itemizedlist>
   </para>

   <para>
    The removal of require_once necessitates another method for loading
    internal dependencies, both files within a package and external files.
    This proposal introduces 2 possible methods for doing this:
    <itemizedlist>
     <listitem>
      use __autoload() in conjunction with PEAR2's custom autoload solution
      (found
      <ulink
       url="http://svn.pear.php.net/wsvn/PEARSVN/Autoload/trunk/src/Autoload.php?op=file">
       here</ulink> in svn)
     </listitem>
     <listitem>
      construct a customized solution for loading needed files
     </listitem>
    </itemizedlist>
   </para>

   <para>
    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
    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).
    <programlisting role="php">
     <![CDATA[
       <?php
         require '/full/path/to/PEAR2/Autoload.php';
         // now you can start using all PEAR2 packages
       ?>
     ]]>
    </programlisting>
    PEAR2/Autoload.php automatically sets up include_path if it does not
    contain the correct value, and also automatically declares __autoload() if
    the user has not defined it.
   </para>
  </sect1>

  <sect1 id="pear2cs.rules">
   <para>
    We will describe the list of rules that form the standards
   </para>

   <sect2 id="pear2cs.rules.namespace">
    <title>Namespace prefix</title>
     All classes and functions must have a namespace of at the minimum PEAR2.  An example:

     <programlisting role="php">
     <![CDATA[
       <?php
       namespace PEAR2;
       class MyClass {}
       ?>
     ]]>
     </programlisting>

     Classes may use longer namespaces, for instance an HTTP_Request class may instead choose to use this declarative syntax:

     <programlisting role="php">
     <![CDATA[
       <?php
       namespace PEAR2::HTTP;
       class Request {}
       ?>
     ]]>
     </programlisting>

     As such, underscores are no longer required of any classes if there is a namespace.  Class PEAR2_HTTP_Request
     instead becomes PEAR2::HTTP::Request.

     Package names, however, will use underscores, making PEAR2_HTTP_Request the package name.

     <sect3 id="pear2cs.rules.namespace.requirement">
      <title>Requirement</title>
      <simpara>No Exceptions to this rule</simpara>
     </sect3>
   </sect2>
  </sect1>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->