cvs: peardoc /en/chapters pear2cs.xml

arnaud		Wed Nov 28 08:55:00 2007 UTC

  Modified files:              
    /peardoc/en/chapters	pear2cs.xml 
  Log:
  transferring document from the wiki
  
http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/pear2cs.xml?r1=1.5&r2=1.6&diff_format=u
Index: peardoc/en/chapters/pear2cs.xml
diff -u peardoc/en/chapters/pear2cs.xml:1.5 peardoc/en/chapters/pear2cs.xml:1.6
--- peardoc/en/chapters/pear2cs.xml:1.5	Tue Nov 27 00:50:51 2007
+++ peardoc/en/chapters/pear2cs.xml	Wed Nov 28 08:54:59 2007
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8" ?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
  <chapter id="pear2cs">
   <chapterinfo>
    <date>2007-11-26</date>
@@ -219,6 +219,98 @@
       <simpara>No Exceptions to this rule</simpara>
      </sect3>
    </sect2>
+
+
+   <sect2 id="pear2cs.rules.requireonce">
+    <title>use of include/require/require_once/include_once not allowed</title>
+    <para>
+     include/require/require_once/include_once is not allowed for loading class
+     files.  Users will be expected to
+     load files either with __autoload() or a customized solution for more
+     advanced users.
+
+      Instead, classes should simply be used.  import with a comment describing
+      the class's location
+      must be used to document all internal dependencies (as written below).
+      Instead of: 
+      <programlisting role="php">
+      <![CDATA[
+<?php
+require_once 'PEAR2/OtherPackage.php';
+$class = new PEAR2::OtherPackage;
+?>
+      ]]>
+      </programlisting>
+         this class should simply be used:
+      <programlisting role="php">
+      <![CDATA[
+<?php
+$class = new PEAR2::OtherPackage;
+?>
+      ]]>
+      </programlisting>
+      This allows packages to work without modification no matter how they are
+      structured on-disk, including running out of a single large file, inside
+      a phar archive, and provides much-needed flexibility.
+    </para>
+    <sect3 id="pear2cs.rules.requireonce.requirement">
+      <title>Requirement</title>
+      <simpara>No Exceptions to this rule</simpara>
+    </sect3>
+   </sect2>
+
+   <sect2 id="pear2cs.rules.otherclasses">
+    <title>Loading other classes</title>
+    <para>
+     Inside optional component loading methods (like factory or driver
+     loading, etc.)
+     <methodname>class_exists</methodname>($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
+     with helpful error message is preferrable to the fatal error:
+
+      <programlisting role="php">
+      <![CDATA[
+<?php
+if (!class_exists("PEAR2_PackageName_Driver_$class", true)) {
+    throw new PEAR2::PackageName::Exception('Unknown driver ' .
+    $class . ', be sure the driver exists and is loaded
+    prior to use');
+}
+?>
+      ]]>
+      </programlisting>
+    </para>
+    <sect3 id="pear2cs.rules.otherclasses.requirement">
+      <title>Requirement</title>
+      <simpara>This rule is optional and is a suggested coding practice</simpara>
+    </sect3>
+   </sect2>
+
+   <sect2 id="pear2cs.rules.dirstructure">
+    <title>Directory structure</title>
+    <para>
+     Follows the directory structure in the PEAR2 Subversion repository:
+     <programlisting role="doc">
+     <![CDATA[
+PEAR2/Package_Name/
+    src/      <-- all role="php"
+    data/     <-- all role="data"
+    tests/    <-- all role="tests"
+    doc/      <-- all role="doc"
+    www/      <-- all role="www"
+    examples/ <-- role="doc" example files 
+                  (php executable files that exemplify package usage)
+     ]]>
+     </programlisting>
+    </para>
+    <sect3 id="pear2cs.rules.dirstructure.requirement">
+      <title>Requirement</title>
+      <simpara>Exceptions may be made to this rule with approval from the PEAR
+      Group</simpara>
+    </sect3>
+   </sect2>
   </sect1>
  </chapter>