Skip to content

Application architecture

Jump to bottom Edit New page
g105b edited this page Mar 27, 2013 · 38 revisions

As you can see in the Hello, World! tutorial, there really isn't that much required to get an application running in PHP.Gt.

A blank project

The only file required to make an application run is the Go.php file that sits in the empty web root of your directory. This file simply serves the purpose of loading the Bootstrap.php file within the PHP.Gt Framework directory. The reason we use Go.php instead of just pointing the webserver at the Boostrap.php file is so there is a clear public webroot that is nested deeper in the directory structure than your code or any PHP.Gt internals - this means that naughty people trying to get access to your code simply will not be able to, because the highest public directory they can see via HTTP is the public webroot with Go.php.

As a convention, we will use the www sub-directory of your application's directory as the public webroot (where your webserver points to), although there is nothing to say you have to use the name www (or the name Go, for that matter).

A blank project within PHP.Gt looks like this:

Application    # This is your application's directory.
 - www
   - Go.php

Recommended directory structure

In development environments, it is recommended to use a single directory as your webroot, with all application directories as sub-directories within it. A logical place for this root directory would be within the Home directory (on Unix-based systems).

For example: the directory /home/username/Webroot (or ~/Webroot) can be used as the 'base' directory for your PHP.Gt projects, and within that directory all your applications' directories and the PHP.Gt directory should be located. This allows the same copy of PHP.Gt to serve all your applications, and means that when you upgrade PHP.Gt, all applications benefit from the features and bug fixes.

~                # The home directory for current Unix user.
 - Webroot
   - Bookface
   - Cms
   - HelloWorld
   - PHP.Gt      # The PHP.Gt source goes here.

Initial files

Although the single Go.php file is all that is needed for PHP.Gt to perform a whole successful HTTP request-response lifecycle, the only thing that will happen is your application will serve a 404 error, as there are no pages to view.

To create the first page within your application, you will need to create an HTML file and place it inside the PageView directory within your application's directory structure.

PageView files are simply HTML files that strictly contain no PHP code. Their contents are used to build DOM objects that are passed to your code for manipulation. This enforces a strict separation of concerns and helps agile development.

URL structure

When requesting URLs to your application, PHP.Gt enforces files are served, not directories. Requesting a directory name in the URL uses the following convention to serve a file:

  • Attempts to serve the Index.html PageView within the requested directory.
  • Attempts to serve the file of that name within the current directory.
  • Ensures the case in the URL matches the case of the files/directories requested.

Having one - and only one - point of entry for each PageView is a strict design decision in PHP.Gt. Therefore, requesting http://example.com/ is 301 redirected to http://example.com/Index.html, and http://example.com/Directory is 301 redirected to either http://example.com/Directory/Index.html or http://example.com/Directory.html (whichever one exists).

The strict rules on URL structure is difficult for visitors of your application to remember, and we don't expect people to remember that the "i" of "Index.html" is upper-case, so PHP.Gt will do its best in fixing URLs while respecting the original URL by 301 redirecting.

So when you've made the next best app online, don't worry about having to tell people the exact URL. Here's a couple of examples of common URLs that would be useful to type lower-case and without file extensions:

  • http://example.com/contact -> http://example.com/Contact.html
  • http://example.com/shop/specialoffers -> http://example.com/Shop/SpecialOffers/Index.html

PageView

PageView files are simply HTML files that strictly contain no PHP code. Their contents are used to build DOM objects that are passed to your code for manipulation. This enforces a strict separation of concerns and helps agile development.

For example, let's use the following valid HTML file as our Index.html, to see how it can be interacted with in PHP (remember, the Index.html file is put inside the /PageView directory within your application's directory structure):

<!doctype html>
<h1>A simple example</h1>
<p>This is a quick example to show the <span id="word">basic</span> functionality of PHP.Gt

The above page can be accessed by navigating to the root URL of your application, or by explicitly requesting Index.html.

PageCode

PageCode files are an object-oriented entry point for your code in reference to the current requested page. Typically, each PageCode file is only invoked when the visitor requests the matching URL (there are special PageCode cases that can be used to perform common functionality across multiple pages, however).

To manipulate the page in the above example, we will create an Index.php file and place it in the /PageCode directory within the application's directory structure.

The footprint of an empty PageCode file looks like this:

<?php class Index_PageCode extends PageCode {

public function go($api, $dom, $template, $tool) {
}

}?>

By convention, the class name is placed on the first line, directly after the opening <?php tag, and the closing brace for the class is placed before the closing ?> tag. This is not a requirement - simply a preference by the PHP.Gt team to save as much horizontal space as possible, and make the important go function stand out.

PageCode files must declare a class named according to the page they represent, followed by "_PageCode", and the class must extend the built-in PageCode abstract class.

The PageCode abstract class declares the go function as the only required implementation within the class. The function is passed four highly important variables, which will be discussed briefly here but in more depth through the rest of the documentation.

The four objects passed into the Go function are all array-like objects, usually interacted by referencing things within square bracket notation.

All we will look at in this brief example is the $dom object, and how we can quickly manipulate the DOM using W3C standards.

We will change the value of the <span> element within Index.html.

<?php class Index_PageCode extends PageCode {

public function go($api, $dom, $template, $tool) {
    $dom["span#word"]->textContent = "awesome";
    // And that's it!
}

}?>

Refreshing the page will now read "This is a quick example to show the awesome functionality of PHP.Gt".

Directories within your application's directory structure.

PageView and PageCode files are the most fundamental features of PHP.Gt, as with them (technically) anything is possible to achieve. However, there are many other areas of the toolkit that will help you create fantastic applications with ease. There areas are explained further on in the documentation.

Below is a representation of the directory structure applications can have. Note that the only required directory is www (apart from PageView, if you require anything more than a 404 page).

ApplicationRoot
- Api          # PHP code that wraps data IO.
- Cache        # Created automatically when cached content is saved.
- Class        # Application-defined class sourcecode.
- Database     # SQL files, including database methods and deployment scripts.
- PageCode     # PHP code that runs in context of each URL request.
- PageTool     # PHP code that is shared over your application(s).
- PageView     # HTML files representing each URL request.
- Script       # JS files for clientside scripting.
- Style        # CSS or SCSS files for clientside styling.
- Test         # PHPUnit tests.
- www          # The public webroot of your directory.

Now you know how to create HTML pages within your application, we can move on to learning about the DOM, and how to manipulate the original HTML from within PHP.

Next page - Manipulating the DOM

Back to documentation

Website | Packagist | CircleCI | Scrutinizer

Introduction

Tutorials

User guide

Further reading

Setup guides

Clone this wiki locally