Phrame Users Guide

原文来自：http://phrame.sourceforge.net/docs/guide/guide.php

 

Phrame Users Guide

• 1. Introduction
  • 1.1 The Model-View-Controller ('MVC') Design Pattern
  • 1.2 "Phrame"work Overview
  • 1.3 The Model: System State and Business Logic Models
  • 1.4 The View: Pages and Presentation Components
  • 1.5 The Controller: ActionController and ActionMapping
• 2. Building Model Components
  • 2.1 Overview
  • 2.2 ActionForm Objects
  • 2.3 System State Models
  • 2.4 Business Logic Models
  • 2.5 Accessing Relational Databases
• 3. Building View Components
  • 3.1 Overview
  • 3.2 Automatic Form Validation
• 4. Building Controller Components
  • 4.1 Overview
  • 4.2 Action Classes
  • 4.3 The Action Mappings Configuration File
  • 4.4 The Action Controller Options File

 

1. Introduction

1.1 The Model-View-Controller ('MVC') Design Pattern

In the MVC design pattern, application flow is mediated by a central Controller. The Controller delegates requests - in our case, HTTP requests - to an appropriate handler. The handlers are tied to a Model, and each handler acts as an adapter between the request and the Model. The Model represents, or encapsulates, an application's business logic or state. Control is usually then forwarded back through the Controller to the appropriate View. The forwarding can be determined by consulting a set of mappings, usually loaded from a database or configuration file. This provides a loose coupling between the View and Model, which can make an application significantly easier to create and maintain.

1.2 "Phrame"work Overview

True to the Model-View-Controller design pattern, Phrame applications have three major components: a controller, which is provided by Phrame itself, Pages (the "view"), and the application's business logic (or the "model"). Let's step through how this all fits together.

The Phrame controller bundles and routes HTTP requests to other objects in the framework, including pages and Action subclasses provided by the Phrame developer. When initialized, the controller parses a configuration resource file. The configuration resource defines (among other things) the ActionMappings for an application. The controller uses these mappings to turn HTTP requests into application actions.

An ActionMapping will usually specify:

• a request path (or "URI"),
• the object type (Action subclass) to act upon the request,
• and other properties as needed.

The Action object can handle the request and respond to the client (usually a Web browser), or indicate that control should be forwarded elsewhere. For example, if a login succeeds, a login action may wish to forward the request onto the mainMenu.

An Action object can create a shopping cart object, add an item to the cart, place the object in the session collection, and then forward control to another mapping. That mapping may use a page to display the contents of the user's cart. Since each client has their own session, they will each also have their own shopping cart. In a Phrame application, most of the business logic can be represented using models. An Action can call the properties of a model without knowing how it actually works. This encapsulates the business logic, so that the Action can focus on error handling and where to forward control.

Objects can also be used to manage input forms. A key problem in designing Web applications is retaining and validating what a user has entered between requests. With Phrame, you can define your own set of form classes, by subclassing ActionForm, and easily store the data for an input form in these form objects. The object is saved in one of the standard, shared context collections, so that it can be used by other objects, especially an Action object.

The form object can be used by a page to collect data from the user ... by an Action object to validate the user-entered data ... and then by the page again to re-populate the form fields. In the case of validation errors, Phrame has a shared mechanism for raising and displaying error messages.

A Phrame form object is declared in the configuration resource, defined in a PHP file, and linked to an ActionMapping using a common property name. When a request calls for an Action that uses a form object, the controller either retrieves or creates the form object, and passes it to the Action object. The Action object can then check the contents of the form object before its input form is displayed, and also queue messages to be handled by the form. When ready, the Action object can return control with a forwarding to its input form. The controller can then respond to the HTTP request and direct the client to the next page.

For the simplest applications, an Action object may sometimes handle the business logic associated with a request. However, in most cases, an Action object should invoke another object, usually a Model, to perform the actual business logic. This lets the Action focus on error handling and control flow, rather than business logic. To allow reuse on other platforms, business-logic Models should not refer to any Web application objects. The Action object should translate needed details from the HTTP request and pass those along to the business-logic beans as regular PHP variables.

In a database application, for example:

• A business-logic model will connect to and query the database,
• The business-logic model returns the result to the Action,
• The Action stores the result in an object, or form object, in the request,
• The next page displays the result in a HTML form.

Neither the Action nor the page need to know (or care) from where the result comes. They just need to know how to package and display it.

The rest of this Users Guide explains the various Phrame components in greater detail. The Phrame release also includes several Tutorials covering various aspects of the framework, along with sample applications, and, of course, the complete source code!

Phrame is distributed under the GPL license. The code is copyrighted and is free to use in any application. See the GPL license for specifics.

1.3 The Model: System State and Business Logic Models

The Model portion of an MVC-based system can be subdivided into concepts -- the internal state of the system, and the actions that can be taken to change that state. In grammatical terms, we might think about state information as nouns (things) and actions as verbs (changes to the state of those things).

Generally, your application will represent the internal state of the system as a set of one or more objects, with properties that represent the details of the state. Depending on your application's complexity, these objects may be self contained.

Large-scale applications will often represent the set of possible business logic actions as methods that can be called on the objects maintaining the state information. For example, you might have a shopping cart object, stored in session scope for each current user, with properties that represent the current set of items that the user has decided to purchase. This object might also have a checkOut() method that authorizes the user's credit card, and sends the order to the warehouse to be picked and shipped. Other systems will represent the available actions separately, perhaps as Business Logic Models.

In some smaller scale applications, on the other hand, the available actions might be embedded within the Action classes that are part of the Controller role. This is appropriate when the logic is very simple, or where reuse of the business logic in other environments is not contemplated. The "Phrame"work supports any of these approaches, but strongly recommends separating the business logic ("how it's done") from the role that Action classes play ("what to do").

1.4 The View: Pages and Presentation Components

The View portion of a Phrame-based application is generally constructed using PHP or XSLT technology. PHP pages can contain static HTML (or XML) text called "template text", plus the ability to insert dynamic content based on the interpretation (at page request time).

1.5 The Controller: ActionController and ActionMapping

The Controller portion of the application is focused on receiving requests from the client (typically a user running a web browser), deciding what business logic function is to be performed, and then delegating responsibility for producing the next phase of the user interface to an appropriate View component. In Phrame, the primary component of the Controller is an ActionController class. This class is configured by defining a set of ActionMappings. An ActionMapping defines a path that is matched against the request URI of the incoming request, and usually specifies the fully qualified class name of an Action class. All Actions are subclassed from Action. Actions encapsulate the business logic, interpret the outcome, and ultimately dispatch control to the appropriate View component to create the response.

Phrame also supports the ability to use ActionMapping classes that have additional properties beyond the standard ones required to operate the framework. This allows you to store additional information specific to your application, but still utilize the remaining features of the framework. In addition, Struts lets you define logical "names" to which control should be forwarded so that an action method can ask for the "Main Menu" page (for example), without knowing what the actual name of the corresponding page is. These features greatly assist you in separating the control logic (what to do) with the view logic (how it's rendered).

2. Building Model Components

2.1 Overview

Many requirements documents used for building web applications focus on the View. However, you should ensure that the processing required for each submitted request is also clearly defined from the Model's perspective. In general, the developer of the Model components will be focusing on the creation of classes that support all of the functional requirements. The precise nature of the beans required by a particular application will vary widely depending on those requirements, but they can generally be classified into several categories discussed below. However, a brief review of the concept of "scope" as it relates to models and views is useful first.

2.2 ActionForm Objects

Note: While ActionForm objects often have properties that correspond to properties in your Model objects, the form objects themselves should be considered a Controller component. As such, they are able to transfer data between the Model and View layers.

The Phrame framework generally assumes that you have defined an ActionForm object (that is, a PHP class extending the ActionForm class) for the input forms in your application. ActionForm objects are sometimes just called "form objects". These may be finely-grained objects, so that there is one object for each form, or coarsely-grained so that one object serves several forms, or even an entire application.

If you declare such objects in your Phrame configuration file (see "Building the Controller Components"), the Phrame controller will automatically perform the following services for you, before invoking the appropriate Action method:

• Check in the user's session for an instance of a form of the appropriate class, under the appropriate key.
• If there is no such session form available, a new one is automatically created and added to the user's session.
• For every request parameter whose name corresponds to the name of a property in the form, the corresponding setter method will be called.
• The updated ActionForm object will be passed to the perform method of an Action class, so that the values can be made available to your system state and business logic models.

For more about coding Actions and ActionForm objects, see the "Building Controller Components" chapter.

You should note that a "form", in the sense discussed here, does not necessarily correspond to a single page in the user interface. It is common in many applications to have a "form" (from the user's perspective) that extends over multiple pages. Think, for example, of the wizard style user interface that is commonly used when installing new applications. Phrame encourages you to define a single ActionForm bean that contains properties for all of the fields, no matter which page the field is actually displayed on. Likewise, the various pages of the same form should all be submitted to the same Action Class. If you follow these suggestions, the page designers can rearrange the fields among the various pages, often without requiring changes to the processing logic.

Smaller applications may only need a single ActionForm to service all of its input forms. Others applications might use a single ActionForm for each major subsystem of the application. Some teams might prefer to have a separate ActionForm class for each distinct input form or workflow. How many or how few ActionForms to use is entirely up to you. The framework doesn't care.

2.3 System State Models

The actual state of a system is normally represented as a set of one or more object classes, whose properties define the current state. A shopping cart system, for example, will include an object that represents the cart being maintained for each individual shopper, and will (among other things) include the set of items that the shopper has currently selected for purchase. Separately, the system will also include different objects for the user's profile information (including their credit card and ship-to addresses), as well as the catalog of available items and their current inventory levels.

For small scale systems, or for state information that need not be kept for a long period of time, a set of system state objects may contain all the knowledge that the system ever has of these particular details. Or, as is often the case, the system state objects will represent information that is stored permanently in some external database (such as a Customer object that corresponds to a particular row in the CUSTOMERS table), and are created or removed from the server's memory as needed.

2.4 Business Logic Models

You should encapsulate the functional logic of your application as method calls in objects designed for this purpose. These methods may be part of the same classes used for the system state objects, or they may be in separate classes dedicated to performing the logic. In the latter case, you will usually need to pass the system state objects to be manipulated to these methods as arguments.

For maximum code re-use, business logic objects should be designed and implemented so that they do not know they are being executed in a web application environment. If you find yourself having to use sessions in your object, you are tying this business logic to the web application environment. Consider rearranging things so that your Action classes (part of the Controller role, as described below) translate all required information from the HTTP request being processed into property setter calls on your business logic objects, after which a call to an perform() method can be made. Such a business logic class can be reused in environments other than the web application for which they were initially constructed.

Depending on the complexity and scope of your application, business logic objects might be ordinary classes that interact with system state objects passed as arguments, or ordinary objects that access a database. For larger applications, these objects will often be stateful or stateless.

2.5 Accessing Relational Databases

After the database is defined, here is an example of establishing a connection (using ADODB) from within a Action perform method.

<?php
class GetDatabaseConnection extends Action
{
    function perform($actionMapping, $actionForm) {
        //get information required to create connection
        $driver = $actionForm->get('driver');
        $username = $actionForm->get('username');
        $password = $actionForm->get('password');
        $database = $actionForm->get('database');
        //create database connection
        $db = &ADONewConnection($driver);
        $db->PConnect(false, $username, $password, $database);
        //use connection and then forward to next state
        return $actionMapping->get('mainMenu');
    }
}

?>
 

Note that the Phrame should utilize connection pools for better performance, especially with high-volume production systems.

 

3. Building View Components

3.1 Overview

This chapter focuses on the task of building the View components of the application, which will primarily be created using available presentation technologies. In particular, Phrame provides support for building applications, as well as for interacting with input forms.

3.2 Automatic Form Validation

Phrame offers an additional facility to validate the input fields it has received. To utilize this feature, override the following method in your ActionForm class:

<?php
class ValidatingForm extends ActionForm
{
    function validate()
    {
        if (!$this->get('value')) {
            trigger_error('Enter some value');
        }
    }
}
?>


 

The validate() method is called by the controller after the form properties have been populated, but before the corresponding action class's perform() method is invoked. The validate() method has the following options:

• Perform the appropriate validations and find no problems -- proceed to call the perform() method of the appropriate Action class.
• Perform the appropriate validations and find problems -- trigger errors. The controller will store these and forward control back to the input form (identified by the input property for this ActionMapping).

As mentioned earlier, this feature is entirely optional. The default implementation of the validate() method does nothing, and the controller will assume that any required validation is done by the action class.

One common approach is to perform simple, prima facia validations using the ActionForm validate() method (or client-side javascript), and then handle the "business logic" validation from the Action.

4. Building Controller Components

4.1 Overview

Now that we understand how to construct the Model and View components of your application, it is time to focus on the Controller components. Phrame includes a controller that implements the primary function of mapping a request URI to an Action class. Therefore, your primary responsibilities related to the Controller are:

• Write an Action class for each logical request that may be received (extend Action).
• Configure a ActionMapping for each logical request that may be submitted. The configuration file is usually named mapping.php.

4.2 Action Classes

The goal of an Action class is to process a request, via its perform() method, and return an ActionForward object that identifies where control should be forwarded (e.g. a page) to provide the appropriate response. In the MVC/Model2 design pattern, a typical Action class will often implement logic like the following in its perform() method:

• Validate the current state of the user's session (for example, checking that the user has successfully logged on). If the Action class finds that no logon exists, the request can be forwarded to the page that displays the username and password prompts for logging on. This could occur because a user tried to enter an application "in the middle" (say, from a bookmark), or because the session has timed out, and the web server created a new one.
• If validation is not complete, validate the form properties as needed. If a problem is found, trigger the appropriate error message, and forward control back to the input form so that the errors can be corrected.
• Perform the processing required to deal with this request (such as saving a row into a database). This can be done by logic code embedded within the Action class itself, but should generally be performed by calling an appropriate method of a business logic object.
• Update the server-side objects that will be used to create the next page of the user interface.
• Return an appropriate ActionForward object that identifies the page to be used to generate this response, based on the newly updated objects. Typically, you will acquire a reference to such an object by calling get() on either the ActionMapping object you received (if you are using a logical name local to this mapping).

Design issues to remember when coding Action classes include the following:

• The controller creates only one instance of your Action class, and uses it for all requests.
• The objects that represent the Model of your system may trigger errors due to problems accessing databases or other resources. You should trap all such errors in the logic of your error handler, and log them (along with the corresponding context) by calling: error_log('Error message text');

In addition, you will want to guard against Action classes that are too large. The easiest way for this to happen is to embed your functional logic in the Action class itself, rather than coding it in separate business logic beans. Besides making the Action class itself hard to understand and maintain, this approach also makes it harder to re-use the business logic code, because it is embedded inside a component (the Action class) that is tied to being executed in a web application environment.

An Action can be factored into several local methods, so long as all properties needed are passed in the method.

4.3 The Action Mappings Configuration File

How does the controller learn about the mappings you want? It would be possible (but tedious) to write a small PHP class that simply instantiated new ActionMapping instances, and called all of the appropriate setter methods. To make this process easier, Phrame is capable of reading an PHP-based associative array describing the desired mappings, creating the appropriate objects along the way. The format is an associative array (instead of XML, for example) so the overhead of parsing is kept to a minimum. The associative array can be used directly by Phrame and is easier to manipulate at runtime.

The developer's responsibility is to create a PHP file (named mapping.php for example) and place it in the directory of your application (the include directory for example).

The elements required in the mappings file are PHP constants (see the Constants file).

There are two important elements that are used to describe your actions:

_ACTION_FORMS

This section contains your form object definitions. Each form object has a unique identifier, which will be used to reference it in corresponding action mappings, and has the following important attributes:

• _TYPE: The fully-qualified PHP classname of your form object.

_ACTION_MAPPINGS

This section contains your action definitions. Each action element has a unique identifier and requires the following attributes to be defined:

• _TYPE: The fully qualified PHP classname of your Action class.
• _NAME: The name of your _ACTION_FORMS element to use with this action.
• _INPUT: Context-relative path of the input form to which control should be returned if a validation error is encountered.
• _VALIDATE: Set to true if the validate() method of the form object (if any) associated with this mapping should be called.

_ACTION_FORWARDS

This section contains your forward object definitions. Each action element contains forward objects that have a unique identifier and require the following attributes to be defined:

• _PATH: Context-relative URI to which control should be forwarded, or an absolute or relative URI to which control should be redirected.
• _REDIRECT: Set to true if the controller should redirect instead of forward on the associated path.

The mappings file from the example application "hello" includes the following mapping entry for the "say hello" function, which we will use to illustrate the requirements.

<?php
//build mapping information to pass into controller
$mappings = array(
    _ACTION_FORMS => array(
        'form' => array(
            _TYPE => 'HelloForm'
        )
    ),
    _ACTION_MAPPINGS => array(
        'sayHello' => array(
            _TYPE => 'HelloAction',
            _NAME => 'form',
            _INPUT => 'index.php?view=views/index.xsl',
            _VALIDATE => 1,
            _ACTION_FORWARDS => array(
                'hello' => array(
                    _PATH => 'index.php?view=views/hello.xsl',
                    _REDIRECT => 0
                ),
                'index' => array(
                    _PATH => 'index.php?view=views/index.xsl',
                    _REDIRECT => 0
                )
            )
        )
    )
);
?>


 

First the form object is defined. A basic object of class "HelloForm" is mapped to the logical name "form". Each mapping entry contains local objects of class "ActionForward" which contain the possible states the application can forward to. The Action classes in the example application are almost totally independent of the actual names of the pages that are used by the page designers. The pages can be renamed (for example) during a redesign, with negligible impact on the Action classes themselves. If the names of the "next" pages were hard coded into the Action classes, all of these classes would also need to be modified. Of course, you can define whatever local forward properties makes sense for your own application.

4.4 The Action Controller Options File

The controller requires the appropriate initialization parameters:

• _CACHE: Set to true to enable internal "lazy" object caching
• _ERROR_REPORTING: This is a PHP directive that is a bitmask, or named constant. Using named constants is strongly encouraged to ensure compatibility for future versions. As error levels are added, the range of integers increases, so older integer-based error levels will not always behave as expected (see the PHP Manual ).
• _ERROR_HANDLER: This is used for defining your own way of handling errors during runtime, for example in applications in which you need to do cleanup of data/files when a critical error happens, or when you need to trigger an error under certain conditions using trigger_error() (see the PHP Manual ).

<?php
//set options for the controller
$options = array(
    //set to true for data caching
    _CACHE => 1,
    //set to E_ALL to get controller errors (debug use only)
    _ERROR_REPORTING => E_USER_ERROR | E_USER_WARNING | E_USER_NOTICE,
    //sets to the function that you specify for handling errors
    _ERROR_HANDLER => "handleError",
);
?>