Basics

1. Introduction

The Adventure PHP Framework (briefly: APF) is designed to assist the developer with the implementation of object oriented and reusable PHP based web applications. It makes use of and implements several important object oriented design patterns and offers a large set of solutions for day-2-day tasks.

The APF is no complete and ready-to-use application that only needs to be configured prior to run but a strong basis to create such application easily and using common software development procedures.

2. Principles and Paradigms

As other PHP frameworks the APF follows dedicated principles and paradigms. The following list contains a list of the most important ones:

  1. Framework instead of class library: The APF understands itself as a framework not a class library. It clearly follows it's paradigms and offers development workflows and patterns that are fully interwoven with the framework. This fact - sometimes misleadingly referred to as restriction - prevents new developers from mistakes and enables you to create applications with proven patterns.
  2. Object orientation: The components of the Adventure PHP Framework are all designed with object orientation in mind. This enables you to create functionality according to their concern that are easily reusable and thus offer a solution for your day-2-day work.
  3. Design pattern: The components of the APF are all designed along with known software design pattern to ease getting started and to use consistent wording.
  4. Bootstrapping: In order to ease configuration and implementation the APF uses a single entry point for all applications - the so-called bootstrap file. This file (e.g. index.php) answers all requests as desired by the developer. Details can be taken from Hello World! or Download, installation and first steps.
  5. Separation of code and configuration: Separation of application logic and configuration allows you to create reusable components and modules. In case you leverage the APF capabilities you can easily create multiple projects based on the same code base or to run a multi-project hosting environment based on one APF installation. Details can be taken from Configuration.
  6. Open to enhancement: The APF follows the open close principle. You are provided dedicated extension points but you cannot completely change the framework. Although the provided extension points let you realize even exotic requirements by enhancing the framework's capabilities according to your project.
  7. Open source: The Adventure PHP Framework is an Open Source product! In case you would like to contribute, we'd love to welcome you within our Team. In other cases, please Contact us or create a thread within our Forum. We are looking forward to get in touch from you!

3. The APF 101

The following chapters contain basic topics on the APF.

3.1. What do I need to get started?

The Adventure PHP Framework is a framework written for PHP to develop web applications. For this reason you need a web server including the PHP module. You may want to use the de-facto standard Apache HTTP Server or nginx respectively.

The APF 2.X requires PHP > 5.3.0 since it is based on PHP namespaces. APF 1.X also works with Version less than 5.3.0. Well-known packages such as XAMPP already contain the required PHP version.

In order to quick-start with the framework it is recommended to download a apf-demopack-* file. These files do not only contain the APF code but a ready-to-use example web site - the Sandbox. The Sandbox contains a large number of examples and wizards to get familiar with the APF. In case you don't have experience with the APF yet, the Sandbox can also be used as a development environment for custom modules or components. Later on, they can be easily integrated into your own web site.

To gain efficiency while programming the APF team strongly recommends to use PHPStorm. It contains code completion, direct feedback on coding issues and a decent integration of xdebug to analyze errors within your application.

Now it's up to you! With the above tools you are now well-equipped to start with development!

3.2. Where do I find important resources?

The pages of the Adventure PHP Frameworks are separated into two main areas: the Downloads area and the Documentation.

Under Downloads you can find the downloads of the current release and a reference on experimental versions (see GIT repository). If you are looking for current snapshots, please refer to GIT repository.

The documentation of the framework is located under Documentation. There are the following areas: the Components documentation with a separate chapter on each component, the Tutorials and the Articles section with further information on the framework and software development in common.

Besides, you are provided the Forum and the Wiki.

3.3. Which components does the APF have?

The Adventure PHP Framework has four main areas: the core that contains basic components, the tools area that ships components that ease development and the modules and extensions section that include ready-to-use modules or extensions.

Each release includes several packages that are all based on the apf-codepack-* files that contains the code base of the APF. Besides, the apf-configpack-* listed under Downloads contains a set of sample content files according to each version.

In case you are searching for implementation samples, you may want to use the Sandbox (package: apf-demopack-*) or the sample packages apf-calc-example-* (simple calculator), apf-modules-example-* (inclusion of dynamic modules), or apf-vbc-example-* - a sample implementation for How to implement view based caching.

4. Folder structure

As noted in chapter 3 the apf-codepack-* files contain the code base of the Adventure PHP Framework. The package contains the following folders:

Code
APF/ core/ extensions/ modules/ tools/

The core and tools folders contain the core parts of the framework. Within core you can find the implementation of the Page controller (/APF/core/pagecontroller/) and the Front controller (/APF/core/frontcontroller/), having a look at tools you may find the Forms implementation (/APF/tools/form/).

modules contains modules that are based on core and tools components. These are i.e. the Comment function and the User management module that can be added to your custom web page easily.

Details on the components can also be taken from the API documentation.

5. A simple application

This chapter shows you how to create a very simple page using the apf-codepack-* release file.

Further content to get started with the APF and how to construct web sites can be found under Hello World!, Download, installation and first steps, or My first website. More tutorials are listed under Tutorials.

5.1. Creating the bootstrap file

As described in chapter 2 the APF uses the boot-strapping concept. This means that the requests of all visitors are handled by one central file (index.php in most cases, bacause this file is configured as DirectoryIndex).

In order to create a simple application please download a apf-codepack-* release file and extract it into a folder located under the DOCUMENT_ROOT of your web server. After that, please create an index.php file in parallel to the APF folder.

Every web page or web application starts with an initial template that takes includes all areas of your application. Please use the following code as a basis for this chapter for the index.php file:

PHP code
include('./APF/core/bootstrap.php'); use APF\core\singleton\Singleton; use APF\core\frontcontroller\Frontcontroller; $fC = Singleton::getInstance(Frontcontroller::class); echo $fC->start('APF\site\templates', 'main');

Within the first line the APF/core/bootstrap.php is included. This file includes all necessary APF components and does the initial configuration.

Line 5 creates an instance of the Front controller and within the last line the request processing is started by applying the initial template. The echo causes the return value - the content of the entire page - to be sent back to the user.

Further instructions on how to configure your application within the index.php file can be found under Configuration, Filter, URL rewriting, and Logger.

5.2. Basic template

Templates play a central role within the Adventure PHP Framework. As mentioned in the last chapter each application starts from a basic template and the Page controller uses templates for it's template-centric implementation of the HMVC pattern.

Within the above sample the Front controller is started with the basic template main from the APF\site\templates namespace. Hence, it expects the main.html file to be stored within folder APF/site/templates. The folder structure is thus as follows:

Code
APF/ core/ extensions/ modules/ site/ templates/ main.html tools/

In case you add

HTML code
My first application with the APF!

to the template file and call the index.php you will be presented the text of the template.

This sample assumes that the standard configuration of the APF has not been changed - especially concerning the ClassLoader configuration. Details on the configuration can be taken from chapter Class loading.

Further examples on templates can be read about in chapters Hello World! and Templates. The My first website tutorial provides an introduction on how to create web pages and applications.

6. Basic configuration

For parameters that are used by various components the framework provides a configuration facility making use of the Registry. In case you intend to adapt those parameters please use the index.php.

The following list shows all relevant parameters from the APF\core namespace:

  • Environment: The Environment property allows you to distinguish configuration properties between different physical environments your software is operated in (e.g. test or production environment). Details can be taken from chapter Configuration.
  • InternalLogTarget: Defines the name of the standard log target for framework error messages. Details on usage and configuration are described in chapter Logger.
  • Charset: Defines the character set that is used for string operations such as htmlspecialchars(). The default value (UTF-8) is initialized within the boostrap.php file.

In case you want to change one or more of the parameters please added the following code to your index.php:

PHP code
include('./APF/core/bootstrap.php'); use APF\core\registry\Registry; Registry::register('APF\core', 'Environment', 'TEST'); Registry::register('APF\core', 'InternalLogTarget', 'framework'); Registry::register('APF\core', 'Charset', 'UTF-16'); ...

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.