[Summary view] [Print] [Text view]

   1  --------------------------------------------------------------------------------
   2  PEAR NOTES
   3  --------------------------------------------------------------------------------
   4  $Id: PEARNOTES,v 1.2 2004/02/14 19:02:04 jeffmoore Exp $
   5  
   6  The PHP Extension and Application Repository (PEAR: http://pear.php.net)
   7  provides a collection of architectural class for solving common problems in
   8  web applications.
   9  
  10  WACT makes use of PEAR libraries (known as "packages" in PEAR-terminology),
  11  where applicable, as foundations for "higher level" code. For example the WACT
  12  template parser relies on PEAR::XML_HTMLSax (a SAX based parser able to cope
  13  with badly formed XML such as HTML). Other PEAR packages are used for more
  14  specific functionality (e.g WACT provides a driver which adapts PEAR::DB,
  15  providing a gateway to many different types of database).
  16  
  17  To install WACT you need to be familiar with the mechanisms PEAR provides for
  18  installing packages on your system. The PEAR documentation,
  19  http://pear.php.net/manual/, provides some insight but a degree of knowledge is
  20  assumed. These notes should fill in the blanks.
  21  
  22  --------------------------------------------------------------------------------
  23  The PEAR Package Manager (PPM)
  24  --------------------------------------------------------------------------------
  25  
  26  PEAR provides the "PEAR Package Manager" (PPM) as a tool to control which
  27  packages are installed on your system. The PPM provides a client for your system
  28  which "talks" to the PPM server at http://pear.php.net using XML-RPC, allowing
  29  packages to be downloaded directly from the PEAR website and installed.
  30  
  31  All PEAR packages come with an XML file (package.xml) which the PPM client
  32  examines to determine how it should install the package. Typically a package.xml
  33  file identifies where the PHP scripts within the package should be installed,
  34  relative to your base PEAR directory (more on that in a moment).
  35  
  36  The PPM client has a number of alternative "Front Ends" (user interfaces), the
  37  most mature (and effectively the default) being the command line interface while
  38  a web interface should help you work with PEAR on a server where you do not have
  39  command line access. A PHP-GTK interface is also available (status unknown).
  40  
  41  This document will focus on the command line interface to PEAR. For a
  42  description of setting up the web based interface, see;
  43  
  44  http://www.phpkitchen.com/article.php?story=20021201062516970
  45  
  46  --------------------------------------------------------------------------------
  47  Setting up the PEAR Package Manager Command Line Interface (PPM CLI)
  48  --------------------------------------------------------------------------------
  49  
  50  With recent PHP distributions, the PPM CLI is bundled so you may already find
  51  it installed on your system. The description here starts from scratch, assuming
  52  nothing is installed. Setting up the PPM takes a little effort but once done,
  53  it makes working with PEAR very easy (so it's worth the effort).
  54  
  55  1. Make sure the php binary is in your system path, so you can execute PHP
  56     scripts from the command line. Type "php -h" and you should see the help
  57     description.
  58     On Unix based systems, where PHP is installed, it should already
  59     be available for use (typically it's located under /usr/local/bin/ or
  60     /usr/bin/). You may need to modify you accounts .profile (in your
  61     home directory) e.g. adding the line "export PATH /usr/local/bin"
  62     You may need to battle with your web host, if they have not
  63     provided you with permissions to execute the binary (consider the web
  64     interface to the PPM...).
  65     On Windows based systems you will need to update your systems path variable
  66     (Control Panel > System > Advanced > Environment Variables > System Vars).
  67     With Windows distributions there should be two versions of the php
  68     executable under your PHP installation directory. It's recommended to add
  69     the executable in <php_install_dir>\cli\php.exe to your system path variable
  70     (forget exactly why - believe this is to avoid conflicts with PHP CGI).
  71  
  72  2. Follow the instructions here:
  73     http://pear.php.net/manual/en/installation.getting.php
  74     This involves downloading a PHP script (http://go-pear.org/) which you need
  75     to execute via the command line (e.g. "php go-pear.php"). It invokes the
  76     installer which sets up the Pear Package Manager for you. You will need
  77     to answer some questions to complete the installation process. Some notes;
  78  
  79      - The install script needs access to the PEAR website, using the HTTP port
  80        (80). If you're connected directly to the Internet, no change is
  81        required. If you're behind a proxy server, you will need to provide
  82        details of the proxy server (the installer will prompt you for this).
  83  
  84      - Installation prefix: set this a base directory under which the PEAR
  85        Package Manager (and later on, packages themselves) will be installed.
  86  
  87      - Binaries directory: "binaries" actually refers to PHP or shell scripts
  88        (in particular the "pear" script) which you will execute from the command
  89        line. A good value for this setting is $prefix/bin. Once the installation
  90        is complete you should ALSO add this directory you your path variable,
  91        so you can execute the "pear" script directly from the command line.
  92  
  93      - PHP Code directory: under this directory is where the PEAR packages
  94        themselves will be installed. You should add this directory to your
  95        PHP include path, because PEAR packages will "expect" files to be
  96        available (for inclusion) relative to this directory. A good value
  97        for this setting is $prefix/lib. To modify your include path, you can
  98        either edit your php.ini file directly (assuming you have access) or
  99        use a .htaccess file (assuming Apache with the AllowOverride set
 100        correctly: http://httpd.apache.org/docs/mod/core.html#allowoverride
 101        by your host) containing;
 102  
 103        php_value "include_path" ".:/home/username/pear/lib"
 104  
 105        All else failing, you can also use the PHP function ini_set in your
 106        code e.g. "ini_set('include_path','.:/home/username/pear/lib');"
 107  
 108        Note that the "directory separator" colon is for Unix based
 109        systems. Windows uses the separator ;.
 110  
 111      - Documentation Base Directory: most PEAR packages come with examples
 112        of how to use the package. This directory specifies where the examples
 113        should be placed. If you're setting PEAR up on a development system
 114        (i.e.. where it's not publicly exposed to the Internet) you may
 115        want to set this directory to somewhere below your web servers document
 116        root directory, so you can run the examples from your browser.
 117  
 118      - Data Base Directory: some PEAR packages come with additional files
 119        containing data that package needs. This setting specifies the base
 120        location for that data (a good setting may be $prefix/data).
 121  
 122      - Tests Base Path: a few PEAR packages come with unit test script for
 123        execution with PEAR::PHP_Unit. They will be placed below this directory.
 124  
 125      - php.exe. path (Windows only): the path to the PHP executable
 126  
 127      Once the installation is complete, for Windows users, it's a good idea to
 128      run the registry file which was placed in the $prefix directory.
 129  
 130  --------------------------------------------------------------------------------
 131  Configuring the Pear Package Manager
 132  --------------------------------------------------------------------------------
 133  
 134  Assuming everything is now set up correctly, you should be able to type "pear"
 135  from the command line and get a list of subcommands that the pear script
 136  accepts.
 137  
 138  Type "pear config-show" to get a list of the current settings. If you're behind
 139  a proxy, you'll need to modify this setting to be able to install PEAR packages
 140  directly e.g.
 141  
 142  pear config-set http_proxy http://username:password@proxy.myisp.com
 143  
 144  To get help on any configuration setting, using config-help e.g.
 145  
 146  pear config-help preferred_state
 147  
 148  The preferred_state setting is import to WACT (more below). To begin with, make
 149  sure it is set to "stable".
 150  
 151  The settings are stored as a serialized PHP array in a file called pear.ini
 152  (it will attempt to place this in the same location as php.ini).
 153  
 154  --------------------------------------------------------------------------------
 155  Installing PEAR Packages
 156  --------------------------------------------------------------------------------
 157  
 158  With the Pear Package Manager set up, and the base of the PEAR library in your
 159  PHP include path (see above on PHP Code Directory) packages can now be installed
 160  directly from the command line and used in your code by including them with the
 161  relative PEAR include path.
 162  
 163  For example type;
 164  
 165  pear install Cache_Lite
 166  
 167  This will install the latest version  PEAR::Cache_Lite
 168  (http://pear.php.net/Cache_Lite) into your PEAR library directory, creating the
 169  subdirectory "Cache" below which the Cache_Lite PHP scripts are stored. In this
 170  case, the package .tgz file itself was fetched directly from the PEAR website
 171  (over XML-RPC).
 172  
 173  This is not the only way PEAR packages can be installed though. If the
 174  package file is available directly via a URL, you can install it via that URL.
 175  
 176  If I specifically want PEAR::Cache_Lite version 1.1 (rather that the current
 177  version 1.2) I can simply point the installed at the URL where it can be
 178  downloaded from e.g.
 179  
 180  pear uninstall Cache_Lite    <<< first uninstall it
 181  
 182  pear install http://pear.php.net/get/Cache_Lite-1.1.tgz
 183  
 184  A third alternative exists which is to install the package file directly
 185  from your filesystem e.g.;
 186  
 187  pear install /home/username/Cache_Lite-1.1.tgz
 188  
 189  Packages can be browsed and downloaded from http://pear.php.net/packages.php
 190  
 191  Some packages have dependances on other PEAR packages. Normally the PPM
 192  will warn you about these (assuming the the author of the package has
 193  identified the dependances in the package.xml file) and prevent you from
 194  installing a package until the required dependances have been installed.
 195  
 196  --------------------------------------------------------------------------------
 197  Installing PEAR Packages for WACT
 198  --------------------------------------------------------------------------------
 199  
 200  The following PEAR packages are used in WACT (you may not need them all);
 201  
 202  PEAR::XML_HTMLSax - required to use WACT template engine (!)
 203  PEAR::Cache_Lite - required for <cache:outputcache/> tag
 204  PEAR::Calendar - required for <calendar:month /> tag
 205  PEAR::DB (1.4.0+) - required if you wish to use the PEAR::DB driver in WACT
 206  
 207  ++ PEAR::XML_HTMLSax (2.1.2+)
 208  Make sure you have the "preferred_state" set to "stable";
 209  
 210  pear config-set preferred_state stable
 211  pear install XML_HTMLSax
 212  
 213  Alternatively;
 214  
 215  pear install http://pear.php.net/get/XML_HTMLSax-2.1.2.tgz
 216  
 217  ++ PEAR::Cache_Lite (1.1+)
 218  Make sure you have the "preferred_state" set to "stable";
 219  
 220  pear config-set preferred_state stable
 221  pear install Cache_Lite
 222  
 223  Alternatively;
 224  
 225  pear install http://pear.php.net/get/Cache_Lite-1.2.tgz
 226  
 227  ++ PEAR::Calendar (0.4+)
 228  The current version of PEAR::Calendar has "beta" status, so the preferred
 229  state has to be set accordingly;
 230  
 231  pear config-set preferred_state beta
 232  pear install Calendar
 233  
 234  Alternatively;
 235  
 236  pear install http://pear.php.net/get/Calendar-0.4.tgz
 237  
 238  ++ PEAR::DB (1.4.0+)
 239  Unless you specify otherwise, PEAR::DB is installed by default when you set
 240  up the PPM. Otherwise, to install manually;
 241  
 242  Make sure you have the "preferred_state" set to "stable";
 243  
 244  pear config-set preferred_state stable
 245  pear install DB
 246  
 247  Alternatively;
 248  
 249  pear install http://pear.php.net/get/DB-1.5.0RC2.tgz