PHPainfree2 Docs

ApplicationController: includes/App.php

The provided App.php makes an excellent starting point for your project. This script, and the singleton you're expected to create, will serve as the overall application state of your program for each and every HTTP request that is passed to the server and handled by PHPainfree2.

class App Overview

The provided ApplicationController is a stripped down version of several production ApplicationControllers that have been developed for several large companies serving hundreds of thousands of requests for complicated highly-interactive data-driven web applications. This file is an excellent starting point for projects of all sizes, ranging from quick Hackathon projects to high-availability production web applications.

Environment Setup - includes/App.php

At the top of the ApplicationController, the code creates a global Singleton instance of class App defined in this file.

Other Classes

Directly below the instantiation, you can see a few lines commented out with a recommendation for how to build these types of ApplicationControllers.

A common PHPainfree2 design pattern is to attach several other required object Singletons to the primary ApplicationController Singleton. In the example code that is commented out, a class User singleton is imported and instantiated as a public member of the $App instance.

Because this example ApplicationController uses the $App instance as the "application state" and execution director, it would be typical to have several such instances defined and attached to the $App instance at run-time. There are several such pre-defined example classes available in this repository, and you can learn more about them at /docs/painfree-examples.

$App->route()

Finally, on line 10, a tiny bit of magic happens with the call to $App->route(). This code, defined inside the class is an example of an ApplicationController consuming the structured route of $Painfree->route to dynamically handle requests and pass them to the correct controller.

Using this function, or one like it, allows PHPainfree2 projects to orchestrate complex behaviors at URLs defined entirely by the name of the first value in the URL path.

$App->route() ➡️ $this->__setRoutes()

Inside $App->route(), the first thing we do is call the __setRoutes() private method. This function takes the route that PHPainfree2 has defined and splits it up into various individual components. This ApplicationController has defined a routing format as: /$VIEW/$ID/$ACTION, so __setRoutes() examines $Painfree->route and assigns each piece to public member variables in $App

		private function __setRoutes() : void {
			$routes = explode('/', $this->route);

			// default route is set in PainfreeConfig.php
			if ( count($routes) ) {
				$this->view = array_shift($routes);
			} else {
				$this->view = $this->route;
			}

			if ( count($routes) ) {
				$this->id = array_shift($routes);
			}

			if ( count($routes) ) {
				$this->action = array_shift($routes);
			}
		}
				

"Magic" Routing

Now that the route variables have been prepared, the route() method does the next four pieces of magic in a few short lines of code.

1. Check if there is a controller script defined for $App->view.
   • If Controller Exists, load and execute the controller script.
   • If No Controller, send a HTTP 404 status code.
2. htmx Support [partials] - Check the Request Headers to see if HX-Request is set and set a boolean for our templates to use.
3. htmx Support [boosted links] - Check the Request Headers to see if HX-Boosted is set and set a boolean for our templates to use.
4. Fast API Support - Check the request headers to see if Content-Type is set to "application/json" or a query parameter of ?json was sent with the URL, and if so, set the response Content-Type and immediately die and send back the contents of $this->data encoded as JSON.

Rendering a Template BaseView

After completing the route() method, execution returns to $Painfree and $Painfree->view(); is called. This function loads the script defined in your PainfreeConfig.php BaseView option, which is the script located in templates/. In the PainfreeConfig provided with this project, the initial BaseView template is defined as templates/app.php.

Your initial BaseView template is often going to be the most complicated template in your project, performing double-duty as an HTML skeleton for the rest of your views as well as dynamically loading view templates based on the URL. In PHPainfree2, this template also has code to handle htmx partial templates.

Dynamic View Template Loading

Inside of templates/app.php in the meat of our web template, we'll load a template file in the template/views/ directory if one exists with the same name as the value stored in $App->view.

In PainfreeConfig, we have our DefaultRoute parameter defined as "main", so our application will serve templates/views/main.php for any request to either http://hostname.com/ (no path) as well as explictly called like http://hostname.com/main. The value of that view, "main" automatically loads:

• includes/Controllers/main.php
• templates/views/main.php

This is one of the designs that makes developing projects with PHPainfree2 so quick. Adding new pages is as simple as dropping a file in the includes/Controllers/ folder and templates/views/ folder. And as you develop more complicated applications, allowing all of your Controller code to serve as the business logic for your REST JSON API, you're able to do a lot more with a lot less duplication.