Section 12.5. Fundamentals

12.5. Fundamentals

In this section, you learn some fundamentals and principles that you should apply to PEAR packages that you plan to release.

12.5.1. When and How to Include Files

You can save yourself from some potential trouble by including files wisely. You should follow three principles on including files:

1. Only use include_once or require_once. Rule number one is to always use require_once or include_once to include PEAR code. If you use require, your script will likely die because of redefinition errors (or it will die sometime in the future).

2. Determine the correlation between class and file names. PEAR uses the one-class-per-file principle, with the intention that it should be trivial to generate the required file name from the class name. Replace underscores with the directory separator character, append .php, and you're finished. Here are some examples:

    Class Name                File Name PEAR                      PEAR.php XML_Parser                XML/Parser.php HTML_Quickform_textarea   HTML/QuickForm/textarea.php 

   
   

   Case is significant here because UNIX file systems are case-sensitive.

3. Encapsulate includes. Each file should use includes to express clearly which classes it depends on from other packages.

As an example, consider you're Package A, and Packages B and C provide classes with the same name. Your class, A, extends B, which in turn extends C. You do not maintain the B and C packages. See Figure 12.1.

Figure 12.1. Nested dependencies.

The only symbol directly referenced in A.php is B from B.php. It does not reference class C at all. In fact, you should assume that A.php is completely unaware that C.php even exists. By following this principle, you do not make assumptions about the internals of the B package that may change later. This makes your package more robust against changes in other packages.

12.5.2. Error Handling

PEAR code reports and catches errors through PEAR's error-handling API. This API is detailed in Chapter 7, "Error Handling."