Initial Setup

We start by setting up the directories and the files that are required by most PRADO applications. We use the PRADO command line tool to achieve this goal.

Assume blog is the name of the directory to hold the whole blog system, and the URL to access this folder is http://hostname/blog/ (replace hostname with the actual host name).

Under the blog directory, we run the PRADO command line tool with the following command (replace path/to with the actual path to the PRADO framework installation):

php path/to/prado-cli.php -c .

Running the above command creates the following directories and files:

We now have a skeleton PRADO application accessible via the URL http://hostname/blog/index.php which brings up a Web page showing "Welcome to PRADO".

It is beneficial to learn more details about the directories and files we just created.

Initial Files

The Entry Script

Every PRADO application has an entry script, often named as index.php. In most cases, it is the only PHP script that is directly accessible by Web users. This reduces the risk of allowing Web users to execute unwanted scripts on the server.

The main purpose of the entry script is to initialize the PRADO application and have it handle user requests. The entry script usually contains the following PHP statements,

run(); ?> The name of the entry script does not need to be index.php. It can be any name as long as the Web server can tell that the script is a PHP 5 script. For example, on some shared hosting environments, one may need to name the script as index.php5 so that it can be properly handled by the Web server.

Application Configuration

The optional XML file application.xml contains the application configuration. Its main purpose is to customize in a configurable fashion the application instance created in the entry script. For example, we may enable the logging feature for our blog system with the help of application configuration.

The file application.xml we have now is nearly empty. In fact, we may safely remove it because the application at the moment uses only default settings of PRADO. As we move forward, we will refer back constantly and show how to configure our application in application.xml.

Homepage

The homepage (also called default page) Home.page is the only page created by the PRADO command line tool. It is the content in this file that shows up in the browser when visiting the URL http://hostname/blog/index.php.

Content in the file Home.page uses the PRADO template format, which is mostly like HTML enhanced with a few PRADO-specific tags. For example, in Home.page we see the following pure HTML content:

Welcome to PRADO

Welcome to PRADO!

Initial Directories

The protected Directory

The protected directory, also known as the application base path, is the root directory holding pages, templates, configurations, data, etc. The name protected indicates this directory should be hidden from Web users, because files under this directory often contain sensitive data.

Different Web servers have different ways of "protecting" a directory. For Apache httpd server, the easiest way is to place under the directory a file named .htaccess with the content deny from all.

The protected/runtime and assets Directories

The protected/runtime and assets directories are the two directories that must be set writable by the Web server process. The runtime directory stores sensitive data (e.g. parsed application configuration) generated when running a PRADO application, while the assets directory stores published resources (e.g. image files, javascript files).

It is safe to remove files and directories under protected/runtime and assets. In fact, developers are recommended to do this cleanup work when they upgrade their PRADO installation.

The pages Directory

The pages directory is the root page directory holding all pages in a PRADO application. It bears an analogy to the htdocs directory for the Apache httpd Web server.

We already see how to access the homepage. To access an arbitrary page located under pages, use the URL http://hostname/blog/index.php?page=path.to.PageName. According to this URL, PRADO will look for a page named PageName under the directory pages/path/to. The URL we used to access the homepage previously is equivalent to http://hostname/blog/index.php?page=Home.

Customization

It is possible to customize the name and location of the files and directories described above.

For example, to improve security, one may want to move the whole protected directory to somewhere else that is not a Web folder. To do so, use the following PHP statement to create the application instance in the entry script:

$application = new TApplication( 'path/to/protected' );

To change the location of the root page directory and change the name of homepage, one can specify it in the application configuration application.xml as follows:

As you learn more about PRADO, you will see that PRADO is such a flexible framework that it allows you to customize nearly every aspect. We will describe more customization techniques as we continue with our tutorial.