PHP on T R A X
Rapid Application Development Made Easy

Changeset 78 for trunk/README

Show
Ignore:
Timestamp:
12/05/05 01:03:56 (3 years ago)
Author:
john
Message:

updated README

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/README

    r49 r78  
    2727 
    2828== Getting Started 
     29goto: http://svn.phpontrax.com/wiki/HowToCreateATraxApplication 
    2930 
    30 1. edit config/environment.php 
    31     set if its development/test/production environment 
    32 2. edit config/database.ini 
    33     set database parameters 
    34 3. edit public_html/.htaccess 
    35     set the path to your pear installation (/usr/local/lib/php - on my box)  
    36     set the path to the config dir for trax (/home/<username>/trax/config) 
    37     example: .htaccess - php_value include_path .:/usr/local/lib/php:/home/<username>/trax/config    
    38 4. set the owner of your log files to the webserver user (www, apache, nobody, ...) or  
    39    chmod them to 777 so the web server can write to the logs. 
    40    example:  
    41     cd /path/to/log/ 
    42     chown www * 
    43     or 
    44     chmod 777 * 
    45 4. create your database and use script/generator.php to  
    46    generate model, controller, and view files 
    47    ./generate.php model user (singular names must be used) 
    48    ./generate.php controller [controller name] [view1 view2 view3 ...] 
    49 5. main site layouts should be in app/views/layouts 
    50    default: public.phtml 
    51    content from view files are displayed in the layout phtml file 
    52    by using the variable <?= $content_for_layout ?> 
    53  
    54 == Naming Schema 
    55  
    56 * controller names should be Camelized (MyClass).  
    57 * models should be use singular names such as customer not customers. 
    58 * table names should always be plural. 
    59 * foriegn keys should always be singular with _id on the end. 
    60  
    61  
    62 == ActiveRecord 
    63  
    64 *Table Relationships 
    65  
    66 In each model class you can define table relationships. 
    67 Allowed relationships in model classes are:  
    68 * belongs_to: means that there is a foreign key from another table in in this table. 
    69     public $belongs_to = "foreign_table_name,foreign_table_name2,etc..."; 
    70     or 
    71     public $belongs_to = array("foreign_table_name" => null); 
    72     - foreign table name is always singular. 
    73 * has_one: means that there is a foreign key in another table to this table 
    74     public $has_one = "foreign_table_name,foreign_table_name2,etc..."; 
    75     or 
    76     public $has_one = array("foreign_table_name" => null); 
    77      - foreign table name is always singular. 
    78 * has_many: means that there is a foreign key in another table to this table 
    79     public $has_many = "foreign_table_name,foreign_table_name2,etc..."; 
    80     or 
    81     public $has_many = array("foreign_table_name" => null); 
    82      - foreign table name is always plural. 
    83 * has_and_belongs_to_many: means there is a join with another table into a third joining table 
    84     public $has_and_belongs_to_many = "foreign_table_name,foreign_table_name2,etc..."; 
    85     or 
    86     public $has_and_belongs_to_many = array("foreign_table_name" => null); 
    87      - foreign table name is always plural. 
    88      - joining table must be named table1_table2 (plural names for both in alphabetical order) 
    89  
    90 In place of the null you can specify an array of parameters such as "foreign_key". 
    91     public $belongs_to = array("table_name" => array("foreign_key" => "otherkey_id"));  
    92  
    93 If the models name isn't the singular name of the corresponding table it goes with, you can in 
    94 the model specify the table name.  (public $table_name = "different_name";)  
    95  
    96 * Functions 
    97    
    98     * find_all([conditions], [orderings], [limit], [joins]) 
    99         $array_of_objects = $model->find_all(); // everything 
    100         $array_of_objects = $model->find_all("id > 10"); // everyone with id > 10 
    101  
    102     * find(id, [orderings], [limit], [joins]) 
    103         $object = $model->find($id); // one object where id=$id 
    104     id can be where conditions name='John', an array of ids or a single id. 
    105  
    106     * find_first([conditions]) 
    107         $object = $model->find_first("last_name = 'Smith'"); // one object , first row in result set where last_name='Smith' 
    108  
    109     * find_all_by_[param1]_or|and_[param2]...(param1,param2,etc...,[ordering]) 
    110         $array_of_objects = $model->find_all_by_lastname_and_firstname_or_last_name("Smith","John","Jones","last_name DESC"); // everything 
    111         - lastname and firstname are fields in the table.  
    112         - the function params are the matching order for the fields in the function name 
    113         - optional last param is the ordering. 
    114  
    115     for aggregrations you can do the following: ("count","sum","avg","max","min") 
    116         $model->count_all("field",[conditions]); (sum_all, avg_all, etc) 
    117      
    118 for auto updating datetime fields there are 2 arrays defined. Any table with fields with these names 
    119 will be auto updated when inserting or updating. If you want to turn off auto updating you can set the 
    120 class var $auto_timestamps = false;     
    121     protected $auto_update_timestamps = array("updated_at","updated_on"); 
    122     protected $auto_create_timestamps = array("created_at","created_on");   
    123  
    124  
    125 == Logging 
    126  
    127 Log files for php errors or if you put in your code error_log("whatever") will be writen to 
    128 the trax/log folder in development|test|production.log file depending on the TRAX_MODE 
    129  
    130 If your application has errors or if you want to print something to the log, then 
    131 any where in your code if you use the built in php function "error_log('some message')" 
    132 it will write the message to the trax/log/development.log or whatever mode your in log file. 
    133      
    134 == Description of contents 
    135  
    136 trax/app 
    137   Holds all the code that's specific to this particular application. 
    138  
    139 trax/app/controllers 
    140   Holds controllers that should be named like weblog_controller.php for 
    141   automated URL mapping. All controllers should descend from 
    142   ActionController. 
    143  
    144 trax/app/libs 
    145   Application specific libraries. Basically, any kind of custom code that doesn't 
    146   belong controllers, models, or helpers. This directory is in the includes path. 
    147  
    148 trax/app/models 
    149   Holds models that should be named like post.rb. 
    150   Most models will descent from ActiveRecord. 
    151    
    152 trax/app/views 
    153   Holds the template files for the view that should be named like 
    154   weblog/index.phtml for the WeblogController->index action. 
    155  
    156 trax/app/helpers 
    157   Holds view helpers that should be named like weblog_helper.php. 
    158   
    159 trax/config 
    160   Configuration files for the Trax environment, the routing map, the database, and other dependencies. 
    161  
    162 trax/lib 
    163   Trax libraries. This directory is in the includes path. 
    164  
    165 trax/script 
    166   Helper scripts for automation and generation. 
    167      
    168 public / public_html 
    169   The directory available for the web server. Contains sub-directories for images, stylesheets, 
    170   and javascripts. Also contains the .htaccess, dispatcher, and default HTML files. 
    171  
    172 == Notes 
    173  
    174 Any thing set as a class variable in the controller with become a regular variable in the view file. 
    175 example: ($this->users becomes $users in the view file as with any class ($this->xxx) variable) 
    176     url: /browse/show_all 
    177  
    178     controller (browse_controller.php): 
    179         function show_all() {     
    180             $user = new User(); 
    181             $this->users = user->find_all(); 
    182         } 
    183          
    184     view file (show_all.phtml): 
    185         <? if(count($users) > 0): ?> 
    186             <? foreach($users as $user): ?> 
    187                 <?=$user->first_name?> <?=$user->last_name?><br> 
    188             <? endforeach; ?> 
    189         <? endif; ?>          
    190  
    191     view results: 
    192         john smith 
    193         joe smith 
    194         larry king 
    195         ... 
    196  
    197          
    198 == Example App 
    199  
    200 URL: 
    201 http://traxtest.mytechsupport.com 
    202  
    203 Trax Code: 
    204  
    205 ###   config/database.ini ### 
    206 [development] 
    207   phptype = mysql 
    208   database =  mydb_development 
    209   host = localhost 
    210   username = user 
    211   password = ****** 
    212   persistent = 1 
    213  
    214 ###   MySQL Table: ### 
    215 CREATE TABLE `files` ( 
    216   `id` int(11) NOT NULL auto_increment, 
    217   `owner` varchar(50) NOT NULL default '', 
    218   `name` varchar(50) NOT NULL default '', 
    219   `contents` text NOT NULL, 
    220   `created_at` datetime NOT NULL default '0000-00-00 00:00:00', 
    221   PRIMARY KEY  (`id`) 
    222 );   
    223  
    224 ###   config/routes.php ### 
    225 // this tells trax to route the root domain to the file_list controller 
    226 // same as just going to http://traxtest.mytechsupport.com/file_list 
    227 $router->connect( "", array(":controller" => "file_list") ); 
    228  
    229 ###   app/controllers/file_list_controller.php  #### 
    230 class FileListController extends ApplicationController { 
    231     function index() { 
    232         $file = new File(); 
    233         $this->files = $file->find_all(); 
    234     } 
    235  
    236     function edit() { 
    237         $file = new File(); 
    238         $this->file = $file->find($_REQUEST['id']); 
    239         if($_POST) { 
    240             if(!$this->file->save($_REQUEST['file'])) { 
    241                 $_SESSION['flash']['error'] = @implode("<br>",$this->file->errors); 
    242             } else { 
    243                 $_SESSION['flash']['notice'] = "File saved successfully."; 
    244                 $this->redirect_to = "/file_list"; 
    245             } 
    246         } 
    247     } 
    248  
    249     function add() { 
    250         $this->file = new File($_REQUEST['file']); 
    251         if($_POST) { 
    252             if(!$this->file->save()) { 
    253                 $_SESSION['flash']['error'] = @implode("<br>",$this->file->errors); 
    254             } else { 
    255                 $_SESSION['flash']['notice'] = "File added successfully."; 
    256                 $this->redirect_to = "/file_list"; 
    257             } 
    258         } 
    259     } 
    260  
    261     function delete() { 
    262         $file = new File(); 
    263         $this->file = $file->find($_REQUEST['id']); 
    264         if(is_object($this->file)) { 
    265             if(!$this->file->delete()) { 
    266                 $_SESSION['flash']['error'] = "Error deleting file."; 
    267                 $this->render_action = "edit"; 
    268             } else { 
    269                 $_SESSION['flash']['notice'] = "File deleted successfully."; 
    270                 $this->redirect_to = "/file_list"; 
    271             } 
    272         } else { 
    273             $_SESSION['flash']['error'] = "Error can't find file to delete."; 
    274             $this->render_action = "edit"; 
    275         } 
    276     } 
    277 } 
    278  
    279 Model 
    280 ###   app/models/file.php  #### 
    281 class File extends ActiveRecord { 
    282  
    283     function validate_name() { 
    284         return array(!empty($this->name), 'Please don\'t leave name blank.'); 
    285     } 
    286  
    287     function validate_owner() { 
    288         return array(!empty($this->owner), 'Please don\'t leave owner blank.'); 
    289     } 
    290  
    291     function validate_contents() { 
    292         if(strlen($this->contents) < 15) 
    293             return array(false, 'Contents needs to be at least 15 characters long.'); 
    294         else 
    295             return array(true, null); 
    296     } 
    297  
    298 } 
    299  
    300 Views 
    301 ###   app/views/file_list/add.phtml  #### 
    302 <h1>FileList->add</h1> 
    303 <form method="post" action="/file_list/add"> 
    304 <? $this->render_partial("form") ?> 
    305 </form> 
    306 <br> 
    307 <a href="/file_list">back</a> 
    308  
    309 ###   app/views/file_list/edit.phtml  #### 
    310 <h1>FileList->edit</h1> 
    311 <form method="post" action="/file_list/edit/<?=$file->id?>"> 
    312 <? $this->render_partial("form") ?> 
    313 </form> 
    314 <br> 
    315 <a href="/file_list">back</a> &nbsp; <a href="/file_list/delete/<?=$file->id?>">delete</a> 
    316  
    317 Partial Views 
    318 ###  app/views/file_list/_form.phtml  #### 
    319 <table> 
    320 <tr> 
    321     <td>Id: </td> 
    322     <td><?=$file->id?></td> 
    323 </tr> 
    324 <tr> 
    325     <td>Name: </td> 
    326     <td><input type="text" name="file[name]" value="<?=$file->name?>"/></td> 
    327 </tr> 
    328 <tr> 
    329     <td>Owner: </td> 
    330     <td><input type="text" name="file[owner]" value="<?=$file->owner?>"/></td> 
    331 <tr> 
    332     <td valign="top">Contents: </td> 
    333     <td><textarea name="file[contents]" rows="10" cols="80"><?=$file->contents?></textarea></td> 
    334 </tr> 
    335 <tr> 
    336     <td>Created: </td> 
    337     <td><?=$file->created_at?></td> 
    338 </tr> 
    339 <tr> 
    340     <td colspan="2"><input type="submit" value=" Save "/></td> 
    341 </tr> 
    342 </table> 
    343  
    344 Site layout file: 
    345 ### app/layouts/public.phtml 
    346 <html> 
    347 <head> 
    348 <title>PHP on Trax</title> 
    349 </head> 
    350 <body> 
    351  
    352 <? if($_SESSION['flash']['notice']): ?> 
    353     <font color="green"><?=$_SESSION['flash']['notice']?></font><br><br> 
    354 <? elseif($_SESSION['flash']['error']): ?> 
    355     <font color="red"><?=$_SESSION['flash']['error']?></font><br><br> 
    356 <? endif; ?> 
    357  
    358 <?=$content_for_layout?> 
    359  
    360 </body> 
    361 </html> 
    362  
     31== Small Demo Application 
     32goto: http://traxtest.mytechsupport.com 
     33download demo: http://www.phpontrax.com/downloads 
    36334