cvs: peardoc /ja/chapters pear2cs.xml

http://cvs.php.net/viewvc.cgi/peardoc/ja/chapters/pear2cs.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/ja/chapters/pear2cs.xml
diff -u peardoc/ja/chapters/pear2cs.xml:1.1 peardoc/ja/chapters/pear2cs.xml:1.2
--- peardoc/ja/chapters/pear2cs.xml:1.1	Tue Nov 27 09:00:09 2007
+++ peardoc/ja/chapters/pear2cs.xml	Wed Nov 28 22:09:01 2007
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8" ?>
-<!-- $Revision: 1.1 $ -->
-<!-- EN-Revision: 1.5 Maintainer: takagi Status: ready -->
+<!-- $Revision: 1.2 $ -->
+<!-- EN-Revision: 1.10 Maintainer: takagi Status: ready -->
  <chapter id="pear2cs">
   <chapterinfo>
    <date>2007-11-26</date>
@@ -222,9 +222,191 @@
     </para>
      <sect3 id="pear2cs.rules.namespace.requirement">
       <title>要件</title>
-      <simpara>このルールには例外はありません</simpara>
+      <simpara>このルールには例外はありません。</simpara>
      </sect3>
    </sect2>
+
+
+   <sect2 id="pear2cs.rules.requireonce">
+    <title>include/require/require_once/include_once を使用してはいけない</title>
+    <para>
+     include/require/require_once/include_once を、
+     クラスファイルを読み込むために使用してはいけません。
+     クラスファイルを読み込むには、<literal>__autoload()</literal>
+     を使用します。あるいは上級者向けには独自の手法を用意します。
+
+      その代わりに、クラスの使用法は簡単にしなければなりません。
+      そのクラスの場所がわかるようなコメントをつけてインポートを行い、
+      内部の依存関係をすべてドキュメント化します (あとで説明します)。
+     </para>
+      <programlisting role="php">
+      <![CDATA[
+<?php
+require_once 'PEAR2/OtherPackage.php';
+$class = new PEAR2::OtherPackage;
+?>
+      ]]>
+      </programlisting>
+      <para>このような方法ではなく、次のようにシンプルに使えなければなりません。</para>
+      <programlisting role="php">
+      <![CDATA[
+<?php
+$class = new PEAR2::OtherPackage;
+?>
+      ]]>
+      </programlisting>
+      <para>
+      こうすることで、どんな場合でも
+      (ディスク上にディレクトリ構造ができている場合でも単一の大きなファイルの場合でも、
+      あるいは phar アーカイブにまとめられている場合でも)
+      変更なしにパッケージを動作させられるようになり、
+      より柔軟なものとなります。
+     </para>
+    <sect3 id="pear2cs.rules.requireonce.requirement">
+      <title>要件</title>
+      <simpara>このルールには例外はありません。</simpara>
+    </sect3>
+   </sect2>
+
+   <sect2 id="pear2cs.rules.otherclasses">
+    <title>他のクラスの読み込み</title>
+    <para>
+     オプションのコンポーネントを読み込むメソッド
+     (ファクトリメソッドやドライバの読み込みなど)
+     の内部で <methodname>class_exists</methodname>($classname, true)
+     を使用し、致命的なエラー "class not found" となることを避けます。
+     たとえばドライバの読み込みに失敗した場合は、
+     単なる致命的なエラーにしてしまうのではなく
+     わかりやすいメッセージをつけた例外を発生させて終了することをお勧めします。
+    </para>
+      <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>
+    <sect3 id="pear2cs.rules.otherclasses.requirement">
+      <title>要件</title>
+      <simpara>このルールはオプションで、推奨するコーディング手法です。</simpara>
+    </sect3>
+   </sect2>
+
+   <sect2 id="pear2cs.rules.dirstructure">
+    <title>ディレクトリ構造</title>
+    <para>PEAR2 Subversion ディレクトリ内のディレクトリ構造にしたがってください。</para>
+     <programlisting role="doc">
+     <![CDATA[
+PEAR2/Package_Name/
+    src/      <-- role="php" のファイルすべて
+    data/     <-- role="data" のファイルすべて
+    tests/    <-- role="tests" のファイルすべて
+    doc/      <-- role="doc" のファイルすべて
+    www/      <-- role="www" のファイルすべて
+    examples/ <-- role="doc" のサンプルファイル
+                  (パッケージの使用法を示す、php の実行可能ファイル)
+     ]]>
+     </programlisting>
+     <para>
+     すべての package.xml ファイルでは、src/ ディレクトリの
+     baseinstalldir に "/" を指定しなければなりません。
+     </para>
+     <programlisting role="doc">
+     <![CDATA[
+<contents>
+  <dir name="/">
+  <dir name="src" baseinstalldir="/">
+  ...
+</contents>
+     ]]>
+     </programlisting>
+    <sect3 id="pear2cs.rules.dirstructure.requirement">
+      <title>要件</title>
+      <simpara>このルールに対して例外を認めるには PEAR Group の許可が必要です。</simpara>
+    </sect3>
+   </sect2>
+
+   <sect2 id="pear2cs.rules.classtofile">
+    <title>クラス名とファイル名の対応</title>
+    <para>
+     すべての公開クラスは、そのクラス名のアンダースコア (_)
+     あるいは名前空間セパレータ (::)
+     の部分をディレクトリ区切り文字に置き換えた場所になければなりません。
+     つまり、PEAR2_PackageName_Base クラスや PEAR2::PackageName::Base
+     クラスは PEAR2/PackageName/Base.php というファイルに書くことになります
+     (これは、autoload を機能させるために必須です)。
+    </para>
+    <sect3 id="pear2cs.rules.classtofile.requirement">
+      <title>要件</title>
+      <simpara>
+        このルールに対して例外を認めるには、公開投票を行ったうえでの
+        PEAR Group の明示的な許可が必要です。
+      </simpara>
+    </sect3>
+   </sect2>
+
+   <sect2 id="pear2cs.rules.baseexception">
+    <title>基底例外クラス</title>
+    <para>
+     <classname>PEAR2::Exception</classname> が、すべての例外クラスの基底クラスとなります。
+     個々のパッケージでは、packagename_Exception
+     という名前の基底クラスを定義しなければなりません。
+     たとえば <classname>PEAR2::PackageName</classname> クラスでは、
+     次のような例外クラスを
+     <literal>PEAR2/PackageName/Exception.php</literal>
+     で定義します。
+    </para>
+      <programlisting role="php">
+      <![CDATA[
+<?php
+namespace PEAR2::PackageName;
+class Exception extends PEAR2::Exception {}
+?>
+      ]]>
+      </programlisting>
+      <para>
+       PEAR2::Exception 自身もパッケージとなります。
+      </para>
+    <sect3 id="pear2cs.rules.baseexception.requirement">
+      <title>要件</title>
+      <simpara>このルールには例外はありません。</simpara>
+    </sect3>
+   </sect2>
+
+   <sect2 id="pear2cs.rules.datafiles">
+    <title>データファイル</title>
+    <para>
+     <literal>package.xml</literal> の replacement
+     タスクを使用して php ファイルやデータファイル、
+     www ファイルのパスを取得してはいけません。
+     しかし、doc ファイルや test ファイルについては置換を使用してもかまいません。
+    </para>
+    <para>
+     パッケージのインストール先は php_dir/src であり、
+     データファイルの場所は、常に
+     php_dir/data/channel/PackageName/ となります。
+     <literal>PEAR2/PackageName/Subfile.php</literal>
+     の中からデータファイルを取得するには、このようなコードを使用します。
+    </para>
+      <programlisting role="php">
+      <![CDATA[
+<?php
+...
+// info.txt からデータを取得します
+$info = file_get_contents(dirname(__FILE__) .
+    '../../../data/pear2.php.net/PEAR2_PackageName/info.txt');
+?>
+      ]]>
+      </programlisting>
+    <sect3 id="pear2cs.rules.datafiles.requirement">
+      <title>要件</title>
+      <simpara>このルールには例外はありません。</simpara>
+    </sect3>
+   </sect2>
   </sect1>
  </chapter>