This document is an introduction on how to develop Web applications that use the code generated by Metastorage. It is meant to guide the Web developers through the necessary steps to build Web applications, using Metastorage as a means to reduce the project development cycle times.

A methodology named use case mapping is also presented in this document. It is a methodology for developing consistent PHP Web applications, whether they use Metastorage generated code or not.

Metastorage is a tool that generates several types of software components that can be incorporated Web applications. However, in the current version, Metastorage does not generate complete Web applications that can be executed right away.

It is still necessary to develop more components that act as glue to implement complete Web applications. Such glue components can be Web page scripts, application logic components, and other types of components which provide functionality that is outside of the scope of Metastorage.

A complete Web application can be built using many different methodologies. This document presents one methodology named "Use case mapping".

It does not mean that this is necessarily the best Web development methodology, nor that you could not use another methodology that you may prefer.

It is a methodology that I have been using for developing PHP Web applications with very satisfactory productivity results. I have been using it since 1999, when Object Oriented Programming support was added to PHP 3. Over time, it has been refined to address better the real world needs of sites of growing complexity.

This methodology has been used extensively to develop busy sites like the PHPClasses repository. Therefore, it has proven to be suitable to develop enterprise grade Web applications. It does not impose excessively complex development procedures. So, it is also suitable for developing small Web applications.

Use cases are basically the different types of situations that an application must handle to interact with the application actors.

Use cases are often referred to as "screens" or "pages", like for instance: the login page, the search page, the articles pages, etc...

Actors are usually the application users or external systems with which the application must interact.

Use cases are not only about situations that generate output that an user can view when it occurs. An use case may need to handle a situation that only requires to interact with non-human external systems. For instance, sending an automated newsletter to subscribers listed in a database, or fetching weather forecast information from a remote system.

Usually, a well structured software process requires some planning. Even when you are developing a small project for your own use, it is always good to give some thought before start implementing it.

Many developers do not like planning, either because it is boring, or because they do not know enough about good methodologies to make proper software planning.

The Rational Unified Process is a well-known software development process that recommends a plan-driven development of projects that are divided in iterations.

Agile is another well-known software development process that also recommends iterative development, but in shorter cycles. The idea is to be able to develop software than can be released earlier and often. That would allow making eventual adjustments to the project requirements and subsequent planning, based on information realized later during the implementation process.

Developers that do not like planning much, often prefer Agile software development process because it lets them start writing code sooner and see the results more often.

Regardless of the software development process you prefer, by the time you start implementing your project, you must have already a good idea of which use cases you are going to implement in each project iteration. You also need to have a good idea of what each use case must do.

It is always good to document your project use cases. This is is specially true when you are developing a project for a client. Even when the client does not understand enough about software development, if you show him a use case diagram and use case descriptions, he will most likely understand and trust that you are doing what he expects.

When the client trusts you have the competence to do what he wants, he is more open to pay you more for your work, and will prefer ordering more work from you instead of your competitors. Therefore, the additional work that it takes to create proper project documentation may compensate financially.

An use case diagram is an artifact of the UML language that can help you modeling use cases. UML is a visual language that can be used to create visual representations of different perspectives of a software system.

An UML use case diagram can help representing the use cases that you want to implement. Use case diagrams are presented in an way that is easy to understand, even by people that is not familiar with software development processes, like clients and sponsors. However, use case diagrams are not sufficient to describe the relevant details of each use case.

It is not absolutely necessary to describe use cases in detail before start writing the code that implements them. A small application written by a single developer may not need to be formally documented because the developer is capable to keep all the relevant details in mind.

Regardless if a project is formally documented or not, there are several details about an use case that are very important. Understanding these details very well, helps you to write the necessary code to implement the use cases correctly. These are the most important use case details:

Name

Example: Submit article

Description of the situation

Summary of what the use case is about.

Example: The user submits new article for publication.

Pre-conditions

Any conditions that must be true when the use case is initiated.

Example: The user must be authenticated to publish an article.

Activation events

Events that trigger the start of an use case.

Example: The user accesses the submit article page.

Normal flow of events

Expected sequence of events that should happen when the use case is executed in most common situation. This is also known as the primary scenario.

Example:
1. The article submission form is presented with fields for the title, lead text and body text.
2. The user submits the form.
3. A message is displayed to let the user know the article was submitted successfully.

Alternative flows of events

Other sequences of events that may happen but are not the most expected. These are also known as secondary scenarios or exceptions situations.

Example:
Secondary scenario: Submission canceled
2a. The user submits the article form using the cancel button.
3a. A message is displayed to let the user know that the article submission was canceled and nothing happened.

Exception: empty fields
2b. The user submits the form with empty fields.
3b. A message is displayed telling that the form fields must not be empty.
4b. Go to 1.

Exception: non-unique article title
2c. The user submits the form with a title of an article that was previously submitted.
3c. A message is displayed telling that there is already an article with the same title.
4c. Go to 1.

The three public functions initialize(), process() and output() constitute the use case class interface.

Each of these three public functions of the use case class interface implement an important part of the use case logic:

initialize()

It is called before the actual use case action happens.

Implements the first part of the Controller functionality of the compact MVC design pattern.

Initializes auxiliary variables and external objects.

May access model class objects if necessary.

Verifies whether the use case pre-conditions are met.

It is a function of type boolean. It returns false when an unexpected runtime error happens.

process()

It is called right after the initialize() function, only if it has returned true.

Implements the second part of the Controller functionality of the compact MVC design pattern.

Implements the actions associated with the normal and alternative flows of events.

Does not do anything if the use case pre-conditions are not met.

Handles expected exceptional situations.

Assures that the use case post-conditions are met.

May access model class objects if necessary.

Prepares any results to be presented, but it does not output any information, except when that is part of the use case processing, like for instance serving files for download or other kind of streamed output.

It should use the class private variables to pass information to present by the output() function.

It is a function of type boolean. It returns false when an unexpected runtime error happens.

output()

It is called right after the process() function, only if it has returned true.

Implements the View functionality of the compact MVC design pattern.

Generates the Web script output as result of the actions executed by the process() function.

It may use result information passed by the process() function using the class private variables.

It never fails. It is a void type function. Anything expected or unexpected that could have failed, must happen either in the initialize() or process() functions.

$this->page->Header();
if(!$this->user->authenticated)
{
/*
* Let the user know that the article submission can only be made
* by an authenticated system administrator
*/
?>
<h2 class="importantmessage">Only the system administrator
is allowed to submit new articles.</h2>
<?php
$this->user->output();
?>
<p class="importantmessage"><a href="index.php">List articles</a></p>
<?php
}

Use result information passed by the process() function using the class private variables

This special use case class is like an exception class, except that it can work with PHP 4 on which exception handling support is not available.

It provides consistent error handling behavior. It works the same way regardless of the type of error that may have occurred.

It may receive error context information via public variables, like for instance an error message, or debug log messages returned by the main use case class.

The error handling class may perform several types actions. Such actions may be useful to help the system administrators or the developers to realize what happened and why, so they can act promptly and fix any problems as soon as possible.

Common error handling actions may include recording the error message in a log file, notify the system administrators by e-mail, pager, instant messaging, etc..

The output of the use case must be an user-friendly message that should not cause user panic. That message also must not include sensitive details that could be used by malicious users to compromise the system security.

An application may be made of many files for many different purposes. Usually each file should be stored in a directory according to its purpose.

Using a consistent application directory structure helps developers understanding better their applications. This way they can find faster the files they need to create and maintain.

The following directory structure is a proposal that addresses the needs of most types of Web applications. It is not necessarily the only directory structure that may be right for Web applications. It is a recommendation that may be followed by anybody. Eventually, you may rename, add, remove or rearrange directories according to your needs.

Under restricted hosting environments it may not be possible to put the base directory for Web pages accessible to the public as a sub-directory of the installation directory named web, as it is proposed.

In that case it is acceptable to make the base Web page scripts directory the same as the installation directory, as long as sensitive information files do not become accessible via Web, like for instance the configuration files that contain database access user names and passwords.

Metanews is the name of simple application written with the help of code generated by Metastorage. It is a simples news publication system that lets a news editor submit articles. The published articles are listed in their own Web pages.

By all means, it is not anything near a complete article publication system. It is just meant to illustrate how common aspects of Web applications can be implemented by glueing custom handwritten code with Metastorage generated code.

Despite Metanews is a simple project for educational purposes, it required some planing. The planing consisted in looking at the project requirements and see which use cases would need to be implemented.

An use case diagram was elaborated with the help of a UML modeling program named Umbrello. This is a free Linux program that is now part of the software development kit package of the KDE system. There are plenty of other free and commercial UML tools that you can use to design UML diagrams.

These tools can save UML projects in the XMI. This is a XML based format meant for exchange project metadata between different tools.

The Metanews use case diagram is available as part of UML project saved in XMI format. The Metanews XMI project file comes with the project source code distribution. It looks like this:

Description

Install the schema of the database that will serve as support to store the information of the application objects.

Pre-conditions

1. The database schema is not yet installed or it is not upto date with the latest revision.
2. The application options are configured.

Activation events

The user accesses the page of the application start page.

Normal flow of events

1. The database schema is installed.
2. A message is displayed to tell the user that the database schema was installed successfully.

Alternative flows of events

Secondary scenario: The database schema is already installed
1a. If the database schema is not upto date, upgrade it to the latest version.
2a. If the database schema was upgraded, tell the user that the database was updated successfully.

Exception: Application is not configured
1b. Tell the user which application options must be configured.
2b. Stop

Post-conditions

Description

Pre-conditions

The user must be authenticated as an administrator to be allowed to publish an article.

Activation events

The user accesses the submit article page.

Normal flow of events

1. The article submission form is presented with fields for the title, lead text and body text.
2. The user submits the form.
3. A message is displayed to let the user know the article was submitted successfully.

Alternative flows of events

Secondary scenario: Submission canceled
2a. The user submits the article form using the cancel button.
3a. A message is displayed to let the user know that the article submission was canceled and nothing happened.

Exception: empty fields
2b. The user submits the form with empty fields.
3b. A message is displayed telling that the form fields must not be empty.
4b. Go to 1.

Exception: non-unique article title
2c. The user submits the form with a title of an article that was previously submitted.
3c. A message is displayed telling that there is already an article with the same title.
4c. Go to 1.

Post-conditions

Below follows the structure of files and directories of the Metanews application.

Some directories have a sub-directory named metanews that contains files that belong specifically to the Metanews project. Using sub-directories this way is recommended in case you plan to install several applications or modules that coexist in the same Web site.

The source directory is listed for learning purposes. In a real Web site production environment that directory is not need and should not be installed.

Each use case uses its own set of scripts and class files. Some were generated by Metastorage, others were handwritten.

There are several groups of files located in different directories that are shared by practically all use cases:

Configuration

The application configuration files are located in the directory configuration. There is one options class file that defines all the application configuration default values. To override the default values, you need to create a PHP script named local_options.php. If it exists, this script is included by the options class. So, it must be made of statements that redefine the class variables like this:

$this->debug = 0;

Presentation details

The application uses special classes to generate common presentation output for page headers and footers and also window frames. These classes are located in the directory templates.

The classes use HTML embedded in the actual class code. The template HTML is HTML 4.01 strict DTD compliant.

The template classes could have used a template engine that would allow putting the template HTML in separate data files. That was not done only to simplify this example project and not add a dependency on an external template engine package.

The presentation styles of several page items are defined in a CSS file located in the web/css directory. This file can be customized to adjust the presentation styles to your preferences.

The installation use case is implemented using files for the schema definition and the database installation class that are located in the directory setup/metanews.

The database installation class is capable of installing the database schema generated automatically by Metastorage. The schema includes all the tables that are necessary to store the objects of the persistent classes specified in the project component definition.

Metastorage generates a database installation class that can either install the schema for the first time, or upgrade to a newer revision, also generated by Metastorage, after eventual changes made to the project component definition.

When the database schema is installed, the file metanews.schema is copied to metanews.schema.installed. The installation use case class uses this information to determine whether the database schema is being installed for the first time, or is being upgraded to a newer revision, or if nothing happened when the installed schema revision is already the most upto date.

The submit article use case is implemented using a form handling class located in the directory components/metanews. This class is also generated by Metastorage.

The article submission form class takes care of most of the use case processing logic, including form validation, article object initialization, validation and storage. It also takes care of the situation when the user cancels the form submission.

Since the use case has as pre-condition that the user must be authenticated, this verification is the first thing that is done in the initialize function of the submit article use case class.

The authentication is done using a special use case class located in the components/users directory. This class performs basic HTTP user authentication. It verifies whether the user and password match those defined by the application options administrator and administrator_password.

The show latest articles use case is implemented using a report data extraction class handling class located in the directory components/metanews. This class is also generated by Metastorage.

The report class retrieves all the necessary data to present upto 10 of the latest articles into a class private array variable. The class iterates over this array to format the article information.

The class also generates a link to a page that generate the same articles listing as an RSS 1.0 feed. This link points to same page but it takes an additional request parameters that tells the class to generate the RSS feed instead of the normal articles listing page.

The show article use case is implemented using the same report data extraction class handling class generated by Metastorage that is located in the directory components/metanews.

The report class retrieves all the data to present an article with an identifier passed by a page request parameter. The article data is also stored in a class private array variable that is accessed by the class output function to present the article in detail.

Metastorage is a powerful code generation tool, but obviously it does not generate all the parts of a Web application. That is not its main goal either. However, the Metanews application demonstrated how Metastorage can be used already to generate a significant amount of code of a complete Web application, that otherwise would take a lot more time to write, test and debug by hand.

The use of a mature and consistent development methodology, as the use case mapping, also helps the developer to become more productive once he gets used to work systematically using the same development procedures.

Therefore, the adoption of productive tools and methodologies like Metastorage and use case mapping can obviously contribute in a significative way to the moral and financial satisfaction of the Web developer.