PRADO is a component-based and event-driven Web programming framework for PHP 5. A PRADO component represents a combination of a PHP class, an HTML template and a specification file (in XML). PRADO components are combined to form larger components or form complete PRADO pages.
Developing PRADO Web applications involves instantiating pre-built and application-specific component types, configuring them by setting their properties, responding to their events by writing handler functions, and composing them into application tasks.
PRADO provides the following benefits to Web application developers:
This article walks through the initial files and directories you will encounter when first using PRADO in your Web development.

Download and Install PRADO

You can download PRADO from the official website. You will also find very useful documentation in the documentation section.
Installing PRADO is very easy; all you need to do is unpack the PRADO release file to the prado subdirectory under the DocumentRoot of the Web server. With that, your installation of PRADO is done and you can start to play with the demo applications included in the PRADO release via the URL http://web-server-address/prado/demos/.
When you access the http://hostname/blog/index.php URL, you should see a web page showing "Welcome to PRADO".

Intial Files for PRADO Development

The sections to follow discuss the intial files for PRADO Web application development.
The Entry Script
Every PRADO application has an entry script, often named index.php. In most applications index.php is the only PHP script that can be directly accessed by Web users. The main scope of the entry script is to initialize the PRADO application and have it handle user requests. A basic entry script can contain the following PHP statements:
<?php
// include prado.php which contains basic PRADO classes
require_once('path/to/prado.php');

// create a PRADO application instance
$application = new TApplication;

// run the application and handle user requests
$application->run();

?>
Homepage
The homepage (Home.page) is the only page created by the PRADO command-line tool. The content of this file appears in the browser when you access the http://hostname/blog/index.php URL. The content of Home.page uses the PRADO template format, which is like HTML enhanced with a few PRADO-specific tags.
The following are two examples of Home.page files, one containing pure HTML content and the other containing some basic PRADO components:
  1. Example 1:
    Home.page
    <html>
<head>
  <title>Welcome to PRADO</title>
</head>
<body>
<h1>Welcome to PRADO!</h1>
</body>
</html>
  2. Example 2:
    Home.page
    <com:TForm>

<fieldset><legend>Login</legend>
<label>Username:  </label>
<com:TTextBox ID="username"/>
<br />

<label>Password:  </label> 
<com:TTextBox ID="password" TextMode="Password" />
<br />

<com:TButton Text="Login" OnClick="buttonClicked" />

</com:TForm>
Application Configuration
You can set PRADO application configuration in the optional XML file application.xml. This file's purpose is allow you to customize in a configurable fashion the application instance created in the entry script. For example, you may enable the logging feature for your blog system with the help of application configuration.
Here is an example of an application.xml file:
<?xml version="1.0" encoding="utf-8"?>
<application id="personal" mode="Normal">
  <paths>
    <using namespace="Application.Common.*" />
  </paths>
  <!-- modules configured and loaded for all services -->
  <modules>
    <!-- Remove this comment mark to enable logging
    <module id="log" class="System.Util.TLogRouter">
      <route class="TBrowserLogRoute" Categories="System" />
      <route class="TFileLogRoute" Categories="System" 
       Levels="Notice,Warning,Error,Alert,Fatal" />
    </module>
    -->
  </modules>
  <services>
    <!-- page service -->
    <service id="page" class="TPageService" BasePath="Application.Pages">
      <!-- modules configured and loaded when page service is requested -->
      <modules>
        <!-- user manager module -->
        <module id="users" class="System.Security.TUserManager" 
                    PasswordMode="Clear">
          <user name="demo" password="demo" />
        </module>
        <!-- auth manager module -->
        <module id="auth" class="System.Security.TAuthManager" 
         UserManager="users" LoginPage="UserLogin" />
      </modules>
    </service>
  </services>
</application>

Initial Directories for PRADO Application Setup

The sections to follow discuss the intial directories for setting up a PRADO application.
The Protected Directory
The protected directory, also known as the application base path, is the root directory for holding pages, templates, configurations, data, etc. As its name indicates, the protected 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 a file named .htaccess with the content deny from all under the directory.
The Protected/Runtime and Assets Directories
The protected/runtime and assets directories are the two directories that must be set to "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).
The Pages Directory
The pages directory is the root page directory holding all pages in a PRADO application. It is similar to the htdocs directory for the Apache httpd Web server. To access an arbitrary page located under pages, you can use the http://hostname/application/index.php?page=path.to.PageName URL. According to this URL, PRADO will look for a page named "PageName" under the directory pages/path/to. The URL you previously used to access the homepage is equivalent to http://hostname/application/index.php?page=Home.

Customization of Initial Files and Directories

You can customize the name and location of the files and directories described in the previous two sections. For example, to improve security, you could 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, you can specify it in the application configuration file application.xml as follows:
<?xml version="1.0" encoding="utf-8"?>

<application id="blog" mode="Debug">
  <services>

    <service id="page" 
           class="TPageService" 
           BasePath="path.to.pages"

           DefaultPage="NewHome"
           />
  </services>
</application>
As you learn more about PRADO, you will see that PRADO is such a flexible framework that you can customize nearly every aspect. For example, Figure 1 presents a class tree with some of the major classes provided by PRADO.


The Class Tree Scheme and the Main Classes Provided by PRADO
Click here for larger image
Figure 1. The Class Tree Scheme and the Main Classes Provided by PRADO

Conclusion

This article introduced the PRADO framework and presented the basics for beginning to build applications using it. The next article will build on this knowledge and demonstrate how to implement custom components into your PHP applications using PRADO.
About the Author
Octavia Andreea Anghel is a senior PHP developer currently working as a primary trainer for programming teams that participate at national and international software-development contests. She consults on developing educational projects at a national level. She is a coauthor of the book "XML Technologies -- XML in Java" (Albastra, ISBN 978-973-650-210-1), for which she wrote the XML portions. In addition to PHP and XML, she's interested in software architecture, web services, UML, and high-performance unit tests. to e-mail her.