view release on metacpan or  search on metacpan

lib/App/devguide.pod  view on Meta::CPAN

#!perl -w
# run this document through perl to check its syntax
use Pod::Checker;
podchecker(\*DATA);
__END__

=head1 NAME

App::devguide - App Developer's Guide

=head1 INTRODUCTION

This is the Developer's Guide to the
App (Perl 5 Enterprise Environment).
You can find out more background to the project on the web.

  http://www.officevision.com/pub/p5ee
  http://p5ee.perl.org

=head1 App DESIGN PHILOSOPHY

When the App project was begun, there were already

 * many outstanding Perl packages on CPAN
 * an excellent systems architecture for Perl webapps (mod_perl)
 * several excellent web application development frameworks

So why was App needed?

For a variety of reasons, there was never sufficient unity of
purpose or direction within the Perl community to provide
a coherent blueprint of what Enterprise Programming in Perl is
or how to do it.

 * What are the pieces?
 * What pieces are default? standard? mandatory? optional?
 * How do they fit together?
 * How can I override or customize them?
 * What techniques do I need to use to assemble them effectively?

After "Enterprise Systems" were defined (see website), the field
of existing frameworks, solutions, and components was surveyed.
The goal was to examine everything that people were already doing,
divide it into pieces that seemed interchangeable, and come up
with a unified blueprint.  Pieces that people often like to do
differently (template systems, persistence frameworks, configuration
files) were allowed to vary, while their essential contribution
to the working system was standardized in the framework.

It should be noted that most of the work on what people might
term "Enterprise Systems" in Perl was actually focused on
"Web Systems" in Perl with a relational database.

The goal of the App design is to unify the Perl community
on a framework for cooperation, while providing flexibility in
the areas that might otherwise divide the community.

Essentially, everything in App is overridable and customizable,
but good defaults are provided for everything as well.

On the practical side, App was also designed to allow for gradual
adoption and incorporation into existing projects.

=head1 App Execution Flow: CGI

The first step to understanding the flow of execution through
the App framework is to understand the flow in the CGI
Context.

This is one of the most challenging contexts
to develop for because of the stateless nature of HTTP,
the need to initialize all resources before accessing them,
and the need to properly shut down all resources after using
them or in case of user abort.

=head2 cgi-bin/app and the Initialization Config File

All usage of App from the web can be driven through the CGI program,
"cgi-bin/app".  (Actually, depending on the settings in the Initialization
Config File, the "app" program might not be a CGI program at all.)
The app program should be installed at a location which is executable
as a CGI program such as the following.

  http://www.officevision.com/cgi-bin/pub/p5ee/app

The "app" progam runs with the "-wT" switches turned on for maximum
safety, security, and enforcement of programming rigor.

Then a BEGIN block is executed to read the Initialization Config File
to get low level config settings and perhaps modify the @INC variable.
Modification of the @INC variable in the BEGIN block through configuration
is critical so that you can have multiple versions of modules installed
(at various stages of development through testing, production, and support).
and access the correct ones.

The Initialization Config File (.conf) is located in the following way.
First, the PATH_INFO is checked and a corresponding .conf file is opened.
Thus, the following URL

  http://www.officevision.com/cgi-bin/pub/p5ee/app/ecommerce/shop

would open "ecommerce_shop.conf" in the directory of the "app" program. 

If it is not found, "$0.conf" is opened.  That would be "app.conf"
in this case.  However, you can see that this allows for the "app"
program to be renamed, and (according to its configuration) it will
behave like a completely different application.

If it is still not found, "app.conf" is opened.
If this is not found, no Initialization Config information will be
used and all defaults will be used.

Whichever .conf file was first opened, it is read for simple configuration
variables of the form "variable = value".  Anything following a "#" is considered
a comment.  Leading and trailing spaces are removed, and blank lines are
ignored.  Spaces may precede or follow the "=" sign without affecting the
"variable" or the "value".  The "variable" must be a sequence of alphabetic characters
and ".", "_", or "-" (i.e. matches /[a-zA-Z_.-]+/).  The value may be
any string of characters (including none), but leading and trailing spaces
are stripped.  The variable/value pairs are saved in a global hash in %main::conf.

If the "perlinc" variable is set, it is understood to be a comma-separated
list of directories to search for Perl modules.  This list is placed
at the beginning of the special Perl @INC variable.

Some sample lines in the .conf file are: