cvs: /pearweb/public_html/doc pear.xml

ssb Sun Feb 27 21:31:11 2000 EDT Modified files: /pearweb/public_html/doc pear.xml Log: more details on naming conventions Index: pearweb/public_html/doc/pear.xml diff -u pearweb/public_html/doc/pear.xml:1.1 pearweb/public_html/doc/pear.xml:1.2 --- pearweb/public_html/doc/pear.xml:1.1 Sun Feb 27 20:21:45 2000 +++ pearweb/public_html/doc/pear.xml Sun Feb 27 21:30:41 2000 @@ -4,41 +4,45 @@ <article id="pear"> <artheader> <title>PEAR: PHP Extension and Add-on Repository</title> - <author> - <firstname>Stig</firstname> - <surname>Bakken</surname> - </author> + <authorgroup> + <author> + <firstname>Stig</firstname> + <surname>Bakken</surname> + </author> + </authorgroup> + <revhistory> + <revision> + <revnumber>$Revision: 1.2 $</revnumber> + <date>$Date: 2000/02/28 05:30:41 $</date> + <authorinitials>$Author: ssb $</authorinitials> + </revision> + </revhistory> </artheader> - <para>PEAR is dedicated to Malin Bakken, born 1999-11-21.</para> + <simpara>PEAR is dedicated to Malin Bakken, born 1999-11-21.</simpara> + <simpara> + This document is incomplete. For now it only contains a brief + description of PEAR and "Coding Rules and Guidelines". The rules + and guidelines are initial suggestions, and this part is still open + to discussion. + </simpara> + <section id="pear-whatis"> <title>What is PEAR?</title> <simpara> PEAR is a code repository for PHP extensions and PHP library code - similar to TeX's CTAN and Perl's CPAN. + inspired by TeX's CTAN and Perl's CPAN. </simpara> <simpara> - The intention behind PEAR is to provide a means for library - code authors to organize their code in a standard way shared by - other developers, and to give the PHP community a single source and - single set of tools for getting such code. + The intention behind PEAR is to provide a means for library code + authors to share their code with other developers, to give the PHP + community an infrastructure for using third-party code, to define + standards that help developers write code that runs in different + PHP configurations, and to provide tools for code maintenance and + distribution. </simpara> - </section> - <section id="pear-admin"> - <title>Administration</title> - <simpara> - This section will describe the rules for how files are structured - and how functions and classes should be named. - </simpara> - </section> - - <section id="pear-tools"> - <title>Tools</title> - <simpara> - This section will describe the tools provided to PEAR users. - </simpara> </section> <section id="pear-rules"> @@ -49,16 +53,79 @@ to PEAR, please read this section carefully and follow these rules, or someone will yell at you. :-) </simpara> + + <section id="pear-names"> + <title>Naming Conventions</title> - <section id="pear-rules-filenames"> - <title>File Naming Conventions</title> <simpara> Use the extension <filename role="extension">.php</filename> for - all files with PHP code in them. + all files with PHP code (files that when included don't output + anything, but only define variables, constants, functions or + classes). </simpara> + + <para> + A related set of one or more classes and functions in PEAR are + called packages. Not modules, since this term is already taken by + Apache, and not extensions, because that is what PHP's bundled + "modules" of C code are called. "Packages" it is. + </para> + + <para> + The main structure in PEAR is the package structure. Although + this structure maps 1:1 down to the file system, it is + conceptually not a filesystem structure. The structure is based + on the developer's view when writing code, which is the parameters + to "use" or "import" (PEAR is currently using "include" though). + An example: + <informalexample> + <literallayout>DB + DB/common + DB/mysql +HTML + HTML/Form +</literallayout> + </informalexample> + Here, the names listed are the parameters the user will give the + "use" or "import" PHP statements. It maps down to the filesystem + level by adding <filename role="extension">.php</filename>. This + means that each "top-level" node will have both a file and a + directory in the top-level directory. But we have an excuse for + this: the PEAR structure is conceptually different from the + filesystem structure, as explained above. So there. + </para> + + <section id="pear-funcnames"> + <title>Function and Method Names</title> + <simpara> + Functions (not methods), should be named with underscores, like + this: <function>my_function</function>. Methods should be named + with initial lower-case studlycaps like this: + <function>myFunction</function>. + </simpara> + </section> + + <section id="pear-classnames"> + <title>Class Names</title> + <para> + Class names are not as straightforward. PEAR should never have + name conflicts among its classes (and preferably ditto for + functions, but that can be solved using static methods in + classes). Since PHP doesn't have packages or name spaces yet, we + need to "brute force" it. The solution is currently not too + pretty, maybe it serves as inspiration for the Zend authors to + implement name spaces :-). + </para> + <para> + The basic class name rule is to use the package name and + substitute slashes with underscores. The package "DB/mysql" has + its code in the file "DB/mysql.php" and defines a class called + "DB_mysql". + </para> + </section> </section> - <section id="pear-rules-options"> + <section id="pear-options"> <title>Depending on Optional Features</title> <simpara> PEAR code is meant to be useable with all (reasonable) @@ -81,7 +148,7 @@ </informalexample> </para> - <section id="pear-rules-phptags"> + <section id="pear-phptags"> <title>PHP Code Block Tags</title> <simpara> Always use the <command>&lt;?php ?&gt;</command> syntax, the @@ -90,7 +157,7 @@ </simpara> </section> - <section id="pear-rules-gpcvars"> + <section id="pear-gpcvars"> <title>HTTP_*_VARS</title> <simpara> GET/POST/cookie can be configured to not be set in the global @@ -105,7 +172,7 @@ </simpara> </section> - <section id="pear-rules-scope"> + <section id="pear-scope"> <title>Scope Issues</title> <simpara> If you need to set some global variables in the top-level part of @@ -159,9 +226,20 @@ </article> -<!-- 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-exposed-tags:nil sgml-local-catalogs:nil -sgml-local-ecat-files:nil sgml-default-dtd-file:"article.ced" -sgml-auto-insert-required-elements:nil End: --> +<!-- 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-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-default-dtd-file:"article.ced" +sgml-auto-insert-required-elements:nil +End: +-->