cvs: peardoc /en/chapters pear2cs.xml

arnaud		Wed Nov 28 20:05:26 2007 UTC

  Modified files:              
    /peardoc/en/chapters	pear2cs.xml 
  Log:
  first draft
  
  
http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/pear2cs.xml?r1=1.9&r2=1.10&diff_format=u
Index: peardoc/en/chapters/pear2cs.xml
diff -u peardoc/en/chapters/pear2cs.xml:1.9 peardoc/en/chapters/pear2cs.xml:1.10
--- peardoc/en/chapters/pear2cs.xml:1.9	Wed Nov 28 13:07:25 2007
+++ peardoc/en/chapters/pear2cs.xml	Wed Nov 28 20:05:25 2007
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8" ?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
  <chapter id="pear2cs">
   <chapterinfo>
    <date>2007-11-26</date>
@@ -323,6 +323,76 @@
       Group</simpara>
     </sect3>
    </sect2>
+
+   <sect2 id="pear2cs.rules.classtofile">
+    <title>Class-to-file convention</title>
+    <para>
+     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)
+    </para>
+    <sect3 id="pear2cs.rules.classtofile.requirement">
+      <title>Requirement</title>
+      <simpara>Exceptions may be made to this rule only with explicit approval
+      from the PEAR Group via a public vote</simpara>
+    </sect3>
+   </sect2>
+
+   <sect2 id="pear2cs.rules.baseexception">
+    <title>Base Exception class</title>
+    <para>
+     <classname>PEAR2::Exception</classname> is used as base class for all exception classes.  Each
+     package must define a base class that is packagename_Exception.  For
+     example, the <classname>PEAR2::PackageName</classname> class defines an exception as follows in
+     <literal>PEAR2/PackageName/Exception.php</literal>:
+    </para>
+      <programlisting role="php">
+      <![CDATA[
+<?php
+namespace PEAR2::PackageName;
+class Exception extends PEAR2::Exception {}
+?>
+      ]]>
+      </programlisting>
+      <para>
+       'PEAR2::Exception will be its own package'
+      </para>
+    <sect3 id="pear2cs.rules.baseexception.requirement">
+      <title>Requirement</title>
+      <simpara>No Exceptions to this rule</simpara>
+    </sect3>
+   </sect2>
+
+   <sect2 id="pear2cs.rules.datafiles">
+    <title>Data files</title>
+    <para>
+     <literal>package.xml</literal> replacement tasks should not be used to retrieve path
+     locations for php, data, or www files.  Replacements
+     are still allowed in doc and test files.
+    </para>
+    <para>
+     The installation structure of a package has implicit php_dir/src
+     installation location, and data files are always located in
+     php_dir/data/channel/PackageName/.  To retrieve a data file within
+     <literal>PEAR2/PackageName/Subfile.php</literal>, you would use this code:
+    </para>
+      <programlisting role="php">
+      <![CDATA[
+<?php
+...
+// retrieve data from info.txt
+$info = file_get_contents(dirname(__FILE__) .
+    '../../../data/pear2.php.net/PEAR2_PackageName/info.txt');
+?>
+      ]]>
+      </programlisting>
+    <sect3 id="pear2cs.rules.datafiles.requirement">
+      <title>Requirement</title>
+      <simpara>No Exceptions to this rule</simpara>
+    </sect3>
+   </sect2>
   </sect1>
  </chapter>