Download, installation and 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 3.0 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 for it. Here you can further place public accessible files (e.g. CSS, JS, pictures).

For security reasons the APF files should not be accessible for the public, 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 web space without control of the document root) please proceed with chapter 4.2 where a special security rule is being created. Otherwise follow the description in chapter 4.1.

4.1. Installation above the document root

Because the document root is placed at /xampp/htdocs, we will create /xampp/APF/ where the files downloaded before should be extracted.

You should now have the following directory structure:

Code

/xampp/APF/
           core/
           modules/
           tools/
           ...
       htdocs/

You can now proceed with chapter 5.

4.2. Installation under document root

If you intend to install the APF within an area that is accessible from the public you need to ensure that the files are protected adequately.

Please create /xampp/htdocs/APF/ and extract the downloaded package in here.

You should now have the following directory structure:

Code

/xampp/htdocs/APF/
                  core/
                  modules/
                  tools/
                  ...

In order to secure the APF files please create a .htaccess file within /xampp/htdocs/APF with the following content:

Shell

# Apache <=2.2
Order allow,deny
deny from all

# Apache >=2.4
Require all denied

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

Since we used different installation folders in chapter 4.1 and 4.2 folder /APF both refers to /xampp/APF with an installation outside of the document root as well as to /xampp/htdocs/APF which means installing the APF within the document root.

Let's explain the folders first:

/APF/core/: Contains all important APF base libs.
/APF/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.
/APF/tools: Contains some little but useful tools.
/APF/extensions: This folder contains extensions to the APF.

Please now create the /xampp/htdocs/index.php file. We will now write a simple "hello world!" application in order to explain the base functions of the APF.

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

We now need to create the folder /APF/helloworld that contains the template - helloworld.html. The template should be added the following content:

Code

Hello World!

In order to generate the output please adapt the previously created index.php as follows

PHP code

// Include bootstrap file for the folder configured in chapter 4.1
include('../APF/core/bootstrap.php');

   // Include bootstrap file for the folder configured in chapter 4.2
include('./APF/core/bootstrap.php');

use APF\core\singleton\Singleton;
use APF\core\frontcontroller\FrontController;

// create the front controller
$fC = Singleton::getInstance(FrontController::class);

// start request processing and send result to the client
echo $fC->start('APF\helloworld', 'helloworld');

First of all, the bootstrap.php is included that executes the basis configuration of the framework. After that, the front controller is created and started with the initial template. The first parameter of the start() method is the namespace (=path to the template) and the second names the template file. Template files are always passed without their file extension within the APF since the *.html extension is appended by convention automatically. Last but not least, the content is sent to the client via echo.

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

In order to see the result please call

Code

http://localhost/index.php

within your browser. There you should see 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. We 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