PHP on T R A X
Rapid Application Development Made Easy

How to Create A Trax Application

Step 1 - Getting the source code.

download: 

 http://www.phpontrax.com/downloads

check out of svn: 

svn co svn://svn.phpontrax.com/trax_repository/trax/trunk trax

Step 2 - Untar / Checkout into your home directory.

There are 2 folders "trax" and "public". You can rename public to public_html or what ever your Document Root is on your server. Typically you will have your trax folder on the same level as the public / public_html folder so its not accessible via the web for security.

If my accounts home folder was /home/john, then the directory structure would probably look something like this: 

/home/
   john/
      trax/
         app/
            controllers/
            helpers/
            models/
            views/
               layouts/
         components/
         config/
         db/
         doc/ <= this is for phpDoc generated output
         lib/
         log/
         script/
         tutorials/ <= this is for phpDoc tutorials that go with generated output
         vendor/
            PEAR/ (this is optional, should already be installed in servers php lib dir)
            trax/
      public/
         images/
         javascripts/
         stylesheets/

Step 3 - Input settings for your application.

There are only a few things that need to be set for Trax to work properly. The first thing is in your public / public_html folder there is a .htaccess file. Open that file in the editor of your choice and you need to change two things:
1. You have to let Trax know where your PEAR installation is so it can use PEAR::DB and PEAR:Mail_mime. Edit the file config/environments.php and set where your php libs directory is at, the directory where your PEAR install is located. 

# include path for your php libs (PEAR etc)
define("PHP_LIB_ROOT",      "/usr/local/lib/php");


2. Change part below ":/home/<username>/trax/config" to be whatever the full path to your trax config folder is. For this example it would be ":/home/john/trax/config".

.htaccess Before: 

# php include_path to Trax config directory
php_value include_path .:/home/<username>/trax/config

.htaccess After: 

# php include_path to Trax config directory
php_value include_path .:/home/john/trax/config

Only other thing to setup is if your going to use a database then put in the database settings. The config file for the database is in trax/config/database.ini. Again open database.ini and change the apropriate settings.
Depending on what mode Trax is in it will use the corresponding database settings. 

[development]
  phptype = mysql
  database = mydatabase_development <= change
  hostspec = localhost
  username = root <= change
  password = ***** <= change
  persistent = true

[test]
  use = development  <= this can be used on any level to use other levels settings

[production]
  phptype = mysql
  database = database
  hostspec = localhost
  username = root
  password =
  persistent = true

Step 4 - Chown logs.

In order for your webserver to be able to write to the log files for Trax you have to do one of the following things.

First cd to the trax folder then do one of the following:

1. Chown the logs folder to the webserver user (www, apache, etc). 

chown -R www logs

2. Chmod the logs folder so the world can write to it (777). 

chmod -R 777 logs

Step 5 - Creating Models, Controllers, and Views.

Now that you have steps 1-3 done you should be able to go in your browser to your domain.com and see the default Trax Congradulations page. If that works then you are ready to start using Trax to build your application. In the trax/scripts folder there is a file named generate.php. That file is a commandline php script to generate Models, Controllers, and Views.

If you type at the commandline ./generate.php controller or ./generate.php model it will show you helps on the correct syntax.

Creating a Model ( model names should always be singular ): 

[root@bsd1 /home/john/trax/script]# ./generate.php model
Usage: ./generate.php model ModelName
Description:
        The model generator creates functions for a new model.
        The generator takes a model name as its argument.  The model name may be
        given in CamelCase or under_score and should not be suffixed with 'Model'.
        The generator creates a model class in app/models.
Example:
        ./script/generate.php model Account
        This will create an Account model:
                Model:      app/models/account.php

Creating a controller: 

[root@bsd1 /home/john/trax/script]# ./generate.php controller
Usage: ./generate.php controller ControllerName [view1 view2 ...]

Description:
        The controller generator creates functions for a new controller and its views.

        The generator takes a controller name and a list of views as arguments.
        The controller name may be given in CamelCase or under_score and should
        not be suffixed with 'Controller'.  To create a controller within a
        module, specify the controller name as 'folder/controller'.
        The generator creates a controller class in app/controllers with view
        templates in app/views/controller_name.

Example:
        ./script/generate.php controller CreditCard open debit credit close

        Credit card controller with URLs like /credit_card/debit.
                Controller: app/controllers/credit_card_controller.php
                Views:      app/views/credit_card/debit.phtml [...]

Folders Example:
        ./script/generate.php controller 'admin/credit_card' suspend late_fee

        Credit card admin controller with URLs /admin/credit_card/suspend.
                Controller: app/controllers/admin/credit_card_controller.php
                Views:      app/views/admin/credit_card/suspend.phtml [...]

Step 6 - Setup routing.

In Trax you can define what are called "routes". A route is a specific url that gets translated into a certain controller and action. The standard format of the url is domain.com/controller/action/id. Controller being the controller to load, action being the method in the controller to run, and id being the passed in id if any. You don't need to do anything here except if you want to define special cases where they type one url and it loads a different controller, An example is if you want Trax to handle the root URL meaning nothing after domain.com. This is done by the adding the following to config/routes.php 

$router->connect( "", array(":controller" => "home") );

The above will route for the URL domain.com (the root of the domain). It will load the controller "home" and the default action "index".

Another example of routing is say I want a specific name to goto a certain product in my catalog, a shirt called cool shirt, but I don't want to have to type domain.com/catalog/show/25 and instead want to just be able to type domain.com/coolshirt. The below example shows how to do this. 

$router->connect( "coolshirt", array(":controller"=>"catalog",":action"=>"show",":id"=>"25") );