[Sommaire] [Imprimer]

   1  
   2    I N S T A L L I N G    P R O P E L
   3    ==================================
   4  
   5    This is a quick guide for installing Propel and building the provided sample
   6    bookstore application.  For more information on installation / configuration
   7    see the online user guide available from main site: http://propel.phpdb.org
   8    
   9    
  10    Prerequisites
  11    -------------
  12  
  13    Before you can install and run Propel you will need to have the following:
  14    
  15      * PHP >= 5.0.0
  16        Propel will only work with PHP5.  Additionally, you must have a command-
  17        line version of PHP5 in order to use PHING to build the classes and SQL
  18        files for your data model.  PHP must also have compiled in XML (libxml2, xsl)
  19        support in order to take advantage of all build options.
  20  
  21        * PHING >= 2.0.0
  22        Propel uses the PHING build system to build the classes and SQL definition
  23        files for your data model.  PHING is an open-source project build system
  24        based on Apache ANT.  PHING 2 is the (development) version built for PHP5.
  25        See http://phing.tigris.org/ to learn how to install Phing (it's easy).
  26        
  27      * Creole >- 1.0.0      
  28        Creole is a Uniform DB API framework for PHP5. Creole is available as a PEAR 
  29        package or can be installed in a more traditional manner. See 
  30        http://creole.phpdb.org/ to get a copy of the Creole classes.
  31      
  32      * A supported RDBMS
  33        Creole currently supports MySQL, MS SQL Server, PostgreSQL, and SQLite.  We 
  34        are working on support for Oracle and the new MySQLi drivers but this should 
  35        be considered alpha, at best.
  36  
  37    Quick Install (PEAR)
  38    --------------------
  39    
  40    It is now possible to install both the Propel runtime and the generator classes as
  41    PEAR packages.  This is the quickest way to get up and running with Propel, but may
  42    not be quite as easy to configure as the traditional installation method.
  43    
  44    * Propel Generator:
  45    
  46      % pear install http://propel.phpdb.org/pear/propel_generator-current.tgz
  47    
  48    To use the generator to build sql, php classes, etc. simply use the propel-gen shell 
  49    script:
  50      
  51      % propel-gen /path/to/my/projectdir
  52      
  53    (See the sample bookstore project directory in your PEAR data directory for a sample 
  54    projectdir.)
  55      
  56    * Propel Runtime:
  57    
  58      %  pear install http://propel.phpdb.org/pear/propel_runtime-current.tgz
  59    
  60    It is recommended that you read over the traditional install guide also, so that you
  61    understand the roles of some of the various files.  In the PEAR install these files
  62    (e.g. the main build.properties and the sample bookstore project) are stored in the
  63    PEAR data dir (e.g. /usr/local/lib/php/data, C:\PHP\PEAR\data).
  64    
  65    
  66    Traditional Installation
  67    ------------------------
  68    
  69    Installation of Propel involves a few steps because Propel is composed of a generator
  70    and runtime classes which are (now) packaged separately.
  71    
  72    Begin installation of Propel by choosing a base directory and unpacking the archive. 
  73    
  74    For the sake of simplicity, we'll assume that you are installing from a package 
  75    (instead of CVS) into /var/www/php/.
  76  
  77      % cd /var/www/php
  78      % tar zxf /path/to/propel-x.x.x.tar.gz
  79      % ln -s propel-x.x.x propel  
  80    
  81    A. Propel Generator
  82    
  83    The Propel generator classes don't need any special setup.  The classes and Phing 
  84    scripts are located in the propel-generator/ directory (which in our example is
  85    /var/www/php/propel/generator).
  86    
  87    B. Runtime Classes 
  88  
  89    The runtime classes were unpacked to the propel/ directory (in this example, 
  90    /var/www/php/propel). In order to use these classes in runtime applications, you will 
  91    need to make sure that they are on the PHP include_path.  In our example, the 
  92    following directory would need to be added to your PHP include_path: 
  93    /var/www/php/propel/classes.  You could also copy the 
  94    /var/www/php/propel/classes/propel directory to a location that is already on your 
  95    include_path, e.g. the directory where PEAR classes are located:
  96    
  97      % cp -r /var/www/php/propel/runtime/classes/propel /usr/local/lib/php/
  98    
  99    Another option on *nix systems is to create a symlink:
 100    
 101      % ln -s /var/www/php/propel/runtime/classes/propel /usr/local/lib/php/propel  
 102    
 103    
 104    Quick Test
 105    ----------
 106    
 107    If you want to quickly test & see whether your installation is working, you can use 
 108    the default configuration which will build the example application using SQLite.
 109    
 110    Here is how to run the simple test on Unix (use corresponding commands for Windows).
 111    If you  run into trouble, don't panic -- just continue reading the INSTALL guide and 
 112    consult the  Installation chapter of the online user guide at http://propel.phpdb.org.
 113    
 114    Change to your propel-generator dir (e.g.)
 115    $> cd /var/www/php/propel/generator
 116    
 117    If using Propel from CVS, copy/rename the build.properties-sample file:
 118    $> cp build.properties-sample build.properties
 119    
 120    Run Phing to build the classes and SQL files, specifying the bookstore project
 121    $> phing -Dproject=bookstore
 122    
 123    Run the 'insert-sql' target which will add the tables to the SQLite db
 124    $> phing -Dproject=bookstore insert-sql
 125    
 126    Run the test script that uses the generated classes against the bookstore db:
 127    $> cd test/
 128    $> php -f bookstore-test.php
 129    
 130    You should see a bunch of output as it tests use cases.  Hopefully there aren't any 
 131    "FAILED" messages. If you get a failed message immediately indicating that it can't 
 132    find one of the tables make sure that you a) ran the 'insert'-sql' target and that 
 133    you are running the bookstore-test.php script from the main propel directory *and* 
 134    that you call PHP with the -qC options so that it won't chdir() into the scripts 
 135    directory.  (The path for the bookstore.db is ./test/bookstore.db so you can see 
 136    that you need to be in the main propel directory for that to work.)
 137    
 138      
 139    Configure
 140    ---------
 141    
 142    To get Propel to work with your own db setup, create a new project (easiest way is 
 143    to use the bookstore project directory as a template). Create your datamodel schema, 
 144    modify the build.properties for that project to specify database connection 
 145    information, and set the db connection runtime properties in runtime-conf.xml.
 146    
 147    
 148    Build
 149    -----
 150    
 151    This assumes that you have already installed and configured a copy of PHING 2.
 152  
 153      % cd /var/www/php/propel/generator  
 154      % phing -Dproject=mykillerapp    
 155  
 156    This will build the SQL files and the object & peer classes based on your datamodel 
 157    schema XML file.
 158  
 159    The resulting files will be placed in: 
 160      /var/www/php/propel/generator/projects/mykillerapp/build
 161  
 162    If you encounter any problems, try adding -verbose or -debug to get more output 
 163    from the PHING build process.
 164    
 165  
 166    You're Done!
 167    ------------
 168    
 169    At this point hopefully you have successfully built the classes and SQL definitions 
 170    for the sample bookstore application.  If you encountered problems, please visit 
 171    http://propel.phpdb.org to read additional documention, browse through the users 
 172    mailing list, or add a bug report.
 173    
 174    Enjoy!
 175    
 176    --$Id: INSTALL,v 1.4 2005/03/24 00:24:07 hlellelid Exp $