Download, installation und first steps

1. Introduction

This is a step-by-step tutorial, which shows you how to set up and use the Adventure PHP Framework (short: APF).

First, you need a PHP capable server. As local test server under windows you might have a look at XAMPP page. It contains an installation of all important server components like Apache, PHP, MySQL, etc. Depending on your setup, you need to adjust the paths used in this tutorial. On LINUX/UNIX boxes you might install the PHP libraries using your favorite package manager.

3. Download

Under Downloads you can always find the latest version. Writing this tutorial, version 1.10 was the latest.

There, the following packages are available:

Example project: (apf-demopack-*):
Contains all necessary APF files and some examples. It's designed for beginners.
Framework code release: (apf-codepack-*):
This contains all necessary APF files. It is designed for daily use.
Sample configuration package: (apf-configpack-*):
This contains some sample configurations, which are useful while creating the own configurations.

For this tutorial we will use the "framework code release", which you can download now.

4. Installation

You need to understand the structure of the folders first. This tutorial expects the document root (the folder which is being opened when you visit http://localhost/ in your browser) under /xampp/htdocs.

The APF is designed delivering a website using only one file. This file (e.g. index.php)is called "bootstrap" file. We create the folder /xampp/htdocs/APF/sites/helloworld/ for it. Here you can further place public accessible files (e.g. pictures).

For security reasons the APF files should not be public accessible, otherwise the public might read your configuration files. The best way would be, placing the package above the document root. If that's not possible (e.g. on a simple webspace without control of the document root) follow step 4.2, where a special security rule is being created, otherwise follow step 4.1.

4.1. Installation above the document root

Because the document root is placed at /xampp/htdocs/, we will create /xampp/APF/. Now we extract the before downloaded package in here.

Now there should be the following directory structure:

Code

/xampp/APF/apps/
    core/
    modules/
    tools/

If everything is fine, you can skip section 4.2.

4.2. Installation under document root

We need to take care that we secure the APF files from public requests. We already created /xampp/htdocs/APF/, so we just extract the before downloaded package in here. Now there should be the following directory structure:

Code

/xampp/htdocs/APF/apps/
    core/
    modules/
    tools/

For securing the APF files, we create a .htaccess file within /xampp/htdocs/APF/apps/ using the following content:

Shell

# Deny all requests
Order allow,deny
deny from all

When uploading the .htaccess file via FTP you need to make sure that ASCII-mode is enabled, otherwise there could be problems.

5. First steps

We dont provide always the full path from now on. We will now call /apps/ the folder with the APF files, and /APF/ the public accessible folder.

Let's explain the folders first:

/apps/core/: Contains all important APF base libs.
/apps/modules: Contains some optional modules which are provided together with the APF. If you want to use them, you need to configure them first. How this works can be read in the tutorials on the overview page of built-in modules.
/apps/tools: Contains some little but useful tools.

We will create the file /APF/sites/helloworld/index.php now. We will write a simple "hello world!" application, in order to explain the base functions.

Hereafter the term namespace will be used instead of folder. The reason for this is the following: The namespace is a relative addressing from the /apps folder. In the namespace all "/" must be replaced with "::".

We now need to create the namespace for the template. For that reason we will create the folder /apps/sites/helloworld, and in this we create the folders /pres/templates. Because the APF supports 3 layer applications (presentation, business and data) the pres means the presentation layer, in which the .html templates are stored in /templates. We only need one template for this example:

Code

helloworld.html

We just write

Code

Hello World!

in it.
Now we edit the before created index.php. It will contain the following: (Description follows below):

PHP-Code

// include page controller (for the under 4.1 configured folder)
include_once('../../../APF/apps/core/pagecontroller/pagecontroller.php');

// include page controller (for the under 4.2 configured folder)
//include_once('../../apps/core/pagecontroller/pagecontroller.php');

// include and configure the front controller
import('core::frontcontroller', 'Frontcontroller');
$fC = &Singleton::getInstance('Frontcontroller');

// start request processing and send result to the client
echo $fC->start('sites::helloworld::pres::templates', 'helloworld');

At first we include the front controller. Here you need to choose the right variation for the step you followed before. Then we create the front controller instance. Thereafter, the the template we have created is passed as root template and the front controller is started. The first parameter is the namespace, the second one is the path to the template with the name of the template file. File names are always provides without extensions in the APF, because the framework convention tells how they have to be called (*.html for templates, *.ini for configuration files, *.php for PHP-files). At last the transform page is displayed by an echo.

The exact function of the front controller can be read about on the Front controller page.

To see the result we visit

Code

http://localhost/APF/sites/helloworld/index.php

There should be displayed Hello World! now.

6. Summary

Now the base functionality of the APF should be clear. In order to get to know the many other functions, you should read some more tutorials. I suggest the My first website tutorial as a next step.

Ralf Schubert thinks the APF is brilliant!

This article was exclusively written for adventure-php-framework.org.

About the author:

Ralf Schubert, an enthusiastic APF developer likes the framework giving the chance to easily develop reusable gui elements (aka. widgets). This is one of the reasons, why he had chosen the APF to be his application development framework of choice.

To support beginners, he wrote this article to give a brief introduction into the framework and to ease the first steps using the APF.

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.

Christian 23.11.2009, 23:11:50

Hello rofrol,

thanks for your hint, the text has been corrected. Besides: was this tutorial a useful introduction to you?

rofrol 13.11.2009, 01:06:54

otherwise follow steop 4.1 ->
otherwise follow step 4.1