Basics

1. Introduction

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

Hence, the framework is a programmer's help and not a ready-to-install application which merely must be configured. The design of the software can only be created by the developer itself and 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 needed within a program part can be included by the import() function.

Each release version possesses the following folder structure:

Code
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/ (E.g. directory for the source code files of a 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 ImageManager (/apps/tools/image/) and the LinkGenerator (/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). You can use them 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 paradigms 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 post-back 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 DirectoryIndex within the web server'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.

As a start the Download, installation and first steps tutorial is recommended.

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:

PHP code
// include the page controller (APF core library) include_once('./apps/core/pagecontroller/pagecontroller.php'); // include the front controller import('core::frontcontroller', 'Frontcontroller'); // create and configure front controller $fC = &Singleton::getInstance('Frontcontroller'); $fC->setContext('{1}'); // optional: $fC->setLanguage('{2}'); // start request processing and send result to the client echo $fC->start('{3}', '{4}');
The place holders marked with {x} signify the following:
  • {1}: Context of the application. The context is used for application-dependent configuration files (see Configuration).
  • {2}: Language of the application. The language is used for language-dependent elements (see Standard taglibs).
  • {3}: Namespace of the base template. In order to load an initial template you need to provide a namespace or path respectively.
  • {4}: Name of the base templates. The parameter takes the name of the template file without it's extension.

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 limited to any number. The initial demo page template mentioned before can be seen in the following code box:

HTML code
<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 gives you a closer look at create web pages 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.

PHP code
// include the page controller (APF core library) include_once('./apps/core/pagecontroller/pagecontroller.php'); // include the front controller import('core::frontcontroller', 'Frontcontroller'); // change the environment parameter used by the ConfigurationManager Registry::register('apf::core','Environment','MY_ENV'); // change the base path to your application Registry::register('apf::core','URLBasePath','http://mybaseurl.de'); // change the url rewriting mode (true: URL params are separated by a "/", false: "normal" URLs) Registry::register('apf::core','URLRewriting',true); // change log directory Registry::register('apf::core','LogDir','/path/to/my/log/dir'); // create and configure front controller $fC = &Singleton::getInstance('Frontcontroller'); $fC->setContext('{1}'); // optional: $fC->setLanguage('{2}'); // start request processing and send result to the client echo $fC->start('{3}', '{4}');

The registry parameters have the following meaning:

3.3.1. 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
  • Environment: e.g. for development, test and live
  • File name: 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"

3.3.2. URLBasePath

Used by: AdvancedBBCodeParser, SocialBookmarkManager, ...

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"

3.3.3. URLRewriting

Used by: ChainedGenericInputFilter, ChainedGenericOutputFilter, LinkGenerator, ...

The Filters and the LinkGenerator shipped with the APF support url rewriting. This means that you can use urls 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 LinkGenerator outputs rewritten links.

Details can be taken from the URL rewriting or Filter or Links chapter.

Default value: "false"

3.3.4. 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"

3.3.5. LibPath

Used by: various extensions, ...

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.