Index: manual.xml =================================================================== --- manual.xml (revision 1865) +++ manual.xml (working copy) @@ -447,8 +447,20 @@
System Architecture - - + Describing an architecture of a free software project essentially means answering the toughest question: what do you get? With Agavi, you get two things: + + A clear and sound way to describe and code up your application logic and to work with your source code, tests and documentation, a set of libraries to solve your common problems and an engine which runs your application + A meta-application based on the aforementioned engine suited for the Web, which has placeholders for your logic. + + + Agavi is a PHP application framework. The essence of an Agavi application corresponds to that of the HTTP protocol: whenever a web request arrives, Agavi application and framework code gets executed by the web server, and the resulting output is returned to the user's browser. In other words, an Agavi application receives an asyncronous request and syncronously returns a response. However, Agavi is perfectly suitable for other types of applications and might be an answer for any kind of large PHP project. + Before we explain the architecture of Agavi, we need to make it clear what Agavi is, exactly. First of all, Agavi is an user-space PHP 5 application framework. This author strongly advises the reader to look at the layout of the Agavi source tree. Every subdirectory of src/ stores classes that correspond to a a particular PHP application pattern. At its core, Agavi is a family of classes that implement various necessary functionality of your application as if you were to write it in raw PHP from scratch. All this code is unified by the developers' single and conservative perspective, resulting in big, orderly and cooperative library. There are again two distinct families of these classes: those that solve common problems for any general PHP application (I/O, logging, caching, and other support infrastructure), and those that solve problems specifically related to Web applications (such as routing and templating). These classes are glued together by configuration into a runtime environment for your application logic to execute in. This is possible and comfortable because of Agavi's powerful configuration mechanism, allowing you to extend and replace components of your application. For instance, you can replace Agavi's default Security Filter to implement an exotic authentication scheme. Agavi is designed to be extended, and you will find that as you work more with Agavi you reuse the Agavi extensions you wrote for previous projects. + Being a developer, you define your application logic. The framework provides you with a skeleton Web application and a build engine that you can use to create initial source files for your application logic. Your application skeleton consists of some default code and the recommended starter configuration which consists of several XML files that define the shape of entire Agavi environment. + All execution of Agavi application code is given in a certain Context. A Context defines the general conditions in which the application is executed. The Context object is the end product of gluing Agavi components together via configuration; it is literally constructed from components as configuration prescribes for any particular execution conditions. Configuration is an inseparable part of an Agavi application. For example, you may define in the configuration that logging is enabled for a particular Context, performed with alternative logging classes (or databases, or format) in another, and totally disabled in yet another. During execution, the Context is an object that encapsulates access to different parts of Agavi's runtime API. For instance, your web application's requests may execute in a "web" Context when an user is using a browser. However, your XMLRPC web service requests may execute in a Context called "xmlrpc". Interaction with your application via command line console would occur in the "console" Context. Configuration brings life into Context, and it is very important to comprehend that configuration is also a way to achieve your goals. + Pieces of your Agavi application logic are organized as Actions. An Action is a PHP class that Agavi loads and uses when a relevant request arrives (whether it's an external request or a result of another Action). You create an action by running Agavi's build tool, which writes the necessary code skeleton for you. An Action is executed by an Execution Container object, which isolates it from outside world and provides it with the environment it needs, thus making it unaware of outside world. An Action has no idea whether it was called by a console command, a XMLRPC request or an user submitting an HTML form. When you construct your application logic in such fashion, it becomes reusable, and clear borders between actions prevent nasty logic leaks and other long term problems. You can, for instance, write an Action that adds an order once, and then have it instantly available over XMLRPC. You then can write another Action that uses the previous one for batch order processing! When you need to process an Excel file you receive from your affiliate describing your orders, you write a simple script that executes the batch ordering Action in Agavi environment (which means all the nuisance of loading vendor libraries, starting database engines, ensuring integrity of data and notifying all observers etc would be already taken from you by Agavi), passing it orders as parameters from your custom Excel parsing script. Actions may respond with error conditions and pass data to the outside world, but they do not really know what they are communicating with. + Many things happen before an Action gets executed. Agavi initializes the environment, reads configuration, loads necessary classes, and starts the Controller which then works its way towards executing the action. The high-level flow of an Agavi application is implemented using filter chains. A filter chain is a way to chain pieces of logic to one another and pipe some input data through them, resulting in something happening and some output data being returned. All major waypoints of execution are wrapped in filter chains, which are constructed out of configuration. + In the "web" Context, an Action's input is gathered from the HTTP request, and the output must be translated into an appropriate HTTP response. Agavi helps on both counts: first, it preprocesses and organizes the request data into an object that your Action is expecting; then, after your Action is finished, its result is supplied to Views. Depending on the result of your action (most commonly "success" or "error"), a View is selected that can translate its particular response into a Web response. A View does not implement any application logic; it merely selects a template, loads data into it and uses an object called a Renderer to produce output. + However, Agavi's involvement with your application does not end here. Agavi provides you with facilities that parse your web requests, enable your logic to access databases, allow you to handle common types of data you work with, maintain stateful user sessions amd authorization, enforce security constraints, format output, log internal software messages, validate data, retain rich and extensible configuration and much more.
@@ -553,14 +565,17 @@
How a Request is Processed - If you call an URL that is handled by pub/index.php, Agavi will + If you call an URL that is handled by pub/index.php, Agavi will bootstrap the specified (or default) Environment and then create an instance of the specified (or default) Context (this instantiation sets up all of the core components of the framework). Finally, the request is - dispatched from the Context's Controller instance. + dispatched from the Context's Controller instance. For example, the sample Agavi + application would bootstrap the development environment, + load the web context and call it's controller's + dispatch() method. - The dispatch method first executes the routing (if enabled) to - determine the Module/Action that are to be executed. The routing returns + The dispatch method first executes the routing + (if enabled) to determine the Module/Action that are to be executed. The routing returns an Execution Container for the first action. Then, a filter chain containing all Global Filters is created, and the DispatchFilter is added to that chain as the last element. Each filter will be called in