Adventure PHP Framework

	Search:
	Downloads \| SVN! \| Roadmap \| Forum! \| Bugtracking \| Guestbook \| Backlinks! \| References! \| Sitemap \| Impress

Deutsch | English Adventure PHP Framework

Quicknavi

1. Introduction
2. Structure and meaning of folders
3. Easy application
3.1. Bootstrap file
3.2. Templates
3.3. Basic configuration

Basics

Rank article:
This article has not yet been ranked. Vote this article first of all!

1. Introduction

The present framework gets on as an aid for the implementation of object orientated, generic and reisable PHP applications. Various OO design pattern and a set of coding conventions offer solutions for known problems:

Model-View-Controller-Pattern:
The Model-View-Controller-Pattern is a pattern of the presentation layer. It is aimed at generating an adaptable program design. In particular it dictates a strict separation of the areas model, view and controller. With it the application becomes for later changes simply maintainable and extendable. Besides, the complexity of the single components is reduced and single software parts become reusable.
Besides, the model contains the data to be shown or information about the behaviour of the software. The view describes the kind of the representation and is represented as by template files. The controller knows the model as well as the view and thus can build up the view with the desired data.

See also http://en.wikipedia.org/wiki/Model-view-controller.
Composite-Pattern:
The objects of the presentation layer inherit from the central class coreObject, or from the class Document. On grounds of this fact any objects can be hung up in an object tree of a site. Thus the presentation layer can be extended by any elements in an easy way.

See also http://en.wikipedia.org/wiki/Composite_pattern.
3 layer architectur:
As already appealed, the framework supports the implementatn of applications in the 3-layer architecture. This pattern intends that applications are divided into the layers of presentation, business logic and data layer and everything taken for itselve encapsulates a certain functionality. The presentation layer - or briefly called "pres" - is responsible for the representation of the application in a (HTML-)GUI. It knows all HTML elements and also the business layer (biz) which delivers data and information about the kind and contents of the representation to the presentation layer. Within the biz layer the business processes of the application is encased and executed. The data layer deals solely with the gathering and persistence of data. Moreover it knows the data source and has tools with those the data source can be read.
Domain object pattern:
The domain object pattern describes that the data which are processed in an application are held in data objects. The pattern is used as a rule in connection with the data mapper pattern. Domain objects are used, in addition, as a communicative device between the layers described above. Furthermore, in real life applications a "domain object" can also be a list of domain objects or a tree of different domain objects. The stamping is depending on the application.
Data mapper pattern:
A Data-Mapper is a "translator" by default. It translates the data model of the database into the data model of the application. These must not agree necessarily and also do not do it in many application cases. Example: In an application persons and their addresses are administered. The data model has an own table for the object "person" and the object "address". To be able to illustrate the affiliation between both objects the third table - the relation table - exists. If the application likes to load the object "person" with his address, the data mapper first has to load the object "person" from the corresponding table and it's adress with the help of the relation table afterwards. During saving, the mapper acts vice versa and stores the data of the object "person" and "adress" in the corresponding tables.

The adventure PHP framework supports the programmer in all design models mentioned. The framework consciously gets on as a programmer's help and not as a ready application which merely must be configured. The design of the software can only be created by the developer itself, hence the framework can only support the implementation!

2. Structure and meaning of the folders

As a common practice in the object orientated world, the components of the framework are stored in folders concerning their dependencies and importance. Here the folder defines the name of the package and the file name the name of the class. The components nedded within a program part can be included by the import() function

Each release version possesses the following folder structure:

apps/ (Directory for all source code files)
     [config/ (Directory for all configuration files)]

     core/ (Directory that contains the core components)
          benchmark/
          configuration/
          database/
          errorhandler/
          filesystem/
          filter/
          frontcontroller/
          logging/
          pagecontroller/
          service/
          session/
          singleton/

     modules/ (Directory that contains the modules shipped with each release)
             comments/
             guestbook/
             kontakt4/
             pager/
             socialbookmark/

     [sites/ (Directory for the source code files of this project)]

     tools/ (Directory including the tools)
           cache/
           datetime/
           form/
                taglib/
           html/
                taglib/
           image/
           link/
           mail/
           string/
           validator/
           variablen/

The folders core and tools contain core components of the framework and are delivered with every release. In it are among other things the implementing of the page controller (/apps/core/pagecontroller/), the configurationManager (/apps/core/configuration/) or tools like the mailSender (/apps/tools/mail/) and the linkHandler (/apps/tools/link/).

The modules folder contains modules based on the core and tools components that are delivered with each release (e.g. guestbook, contact form) or that are implemented by any developer of your team to enrich your web page or application.

Below config the configuration files which are used in core components or parts of your software are held. This can be language mapping files, configuration files for your applications or MySQL statement files.

Because it is a significant point of the codexes of the framework to always create reusable code parts, it is distinguished between the folders modules and sites. The folder modules contains every software part, that can be included in real web projects hosted under the folder sites. A web page project can be not only an easy web page, but also a complicated project as for example a CMS.

The precise contents of the folders can be seen in the API documentation.

3. Construction of an easy application:

The framework is written to operate in a so-called "postback" mode. This means, that a web site project consists of exactly one central file (often called "bootstrap file"). This file must be configured as an DirectioryIndex within the webserver's configuration. Nevertheless, it is possible - and often also helpfully - to define other central files according to their task. But it had proved satisfactory to deal with only one bootstrap file, because of the lower maintenance costs.

3.1. Schema of an index.php file

A simple application merely consists of a bootstrap file and a master template. The index.php loads the template, therefrom creates a page, that is transformed and displayed afterwards. The master template defines the structure of the application and indicates, which further taglibs or modules are included.

A typical index.php has the following code parts:


   // include page controller
   include_once('./apps/core/pagecontroller/pagecontroller.php');

   // create the page object
   $Page = new Page('{1}');

   // load the master template
   $Page->loadDesign('{2}','{3}');

   // transform and output the page
   echo $Page->transform();

The place holders marked with {x} signify the following:

{1}: The parameter {1} defines the name of the webseite. This parameter is optional and only gives a name to the object Page.
{2}: Namespace to the basic template or the context of the application. To be able to load a design the information "namespace" or "path" and "design name" is necessary. The first part ("namespace" or "path") is used at the same time as a context for configuration interests, if the context is not set before loading a template via loadDesign(). (see configuration for more details).
{3}: Name if the basic template. Here either the name of the basic template can be given without his ending or a sub path incl. name of the basis template.

3.2. Construction of the templates

Templates ara playing a big role within the adventure php framework. Abstractly spoken, each node of a web page or application forms a "small MVC section" that consists of a model (commonly the model of the application or website), the view (an XML / HTML template) and a controller (named document controller) if applicable. The kernel of the framework contains the page controller component that generates a DOM tree out of the templates specified in either the index.php or by any includes in templates. The page controller executes specified controller during transformation of the DOM tree.

The semantics of the templates thereby defines the complexity of the desired page and thus directly influences the structure of the DOM tree generated by the page controller. By calling the loadDesign() method in the index.php the initial template of an application or web page is loaded. This file defines the basic structure of the page. Each template included forms a child node of the initial DOM node - the Document. The depth of the tree is not limitied to any number. The initial demo page template mentioned before can be seen in the following code box:

<html>
<head>
  <title>Demo</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
</head>
<body>
...
</body>
</html>

Further examples on templates can be read about in the chapters hello world! and templates. The my first website tutorial gives you a closer look at create webpages and applications.

3.3. Basic configuration

In contrast to earlier versions of the framework (< 1.7), you do not need any further basic configuration. The core components' configuration parameter are stored in the apf::core namespace of the Registry. In order to manipulate them to fit your special needs, the desired parameters must be changed in the central bootstrap file as described below. The registry is not only an information pool for the framework's core, but can also be used to store information about concrete applications.


   // include pagecontroller
   include_once('./apps/core/pagecontroller/pagecontroller.php');

   // get an instance of the registry
   $Reg = &Singleton::getInstance('Registry');

   // change the environment parameter used by the configurationManager
   $Reg->register('apf::core','Environment','MY_ENV');

   // change the base path to your application
   $Reg->register('apf::core','URLBasePath','http://mybaseurl.de');

   // change the url rewriting mode (true: URL params are separated by a "/", false: "normal" URLs)
   $Reg->register('apf::core','URLRewriting',true);

   // change log directory
   $Reg->register('apf::core','LogDir','/path/to/my/log/dir');

   // create page
   $Page = new Page('{1}');

   // load initial template file
   $Page->loadDesign('{2}','{3}');

   // transform and display page
   echo $Page->transform();

The registry parameters have the following meaning:

Environment: (used by: configurationManager, MySQLxHandler, MySQLHandler, SQLiteHandler, ...)

Every configuration file exists of four different components:
- Namespace: The folder below which all configuration files of this application lie
- Context: Current context of the application
- Umgebung: e.g. for development, test and live
- Dateinamen: Name of the configuration file
This abstraction was introduced, so that an application or a module can be integrated into different other applications or modules and is executable on different systems at the same time without change of the source code. Nevertheless, for the loading of configurations there are standardised methods, so that the programmer must not look after it any more. Continuing material can be found under configuration.

Default value: "DEFAULT"
URLBasePath: (used by: bbCodeParser, socialBookmarkManager, Suche, ...)

Many modules link on itself or different areas of a module or a web page. That's why it must be confessed how the base URL of the site is. The registry value URLBasePath defines this.

Default value: "HTTP_HOST value of the $_SERVER array"
URLRewriting: (used by: PageController, FrontController, linkHandler, frontcontrollerLinkHandler, ...)

The present page controller supports URL-Rewriting. Rewrited URLs look like http://www.domain.tld/param1/value1/param2/value2 instead of http://www.domain.tld?param1=value1&param2=value2. If this value is set to "true" the linkHandler and frontcontrollerLinkHandler component generate links in rewrite style.

Default value: "false"
LogDir: (used by: Logger, ...)

To allow a central Logging mechanism, the path in which the log files should be written must be defined centrally. The path is used by the class Logger.

Default value: "./logs"
LibPath: (used by: bbCodeParser, ...)

The LibPath directive stores the basic path to the framework's code files. The directory path is set dynamically and the value is read only.

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.

There are no comments belonging to this article.