Entry Point

When accessing Hiraeth over HTTP (any standard web server), you will be hitting the application through the public/index.php file. This file is provided by hiraeth/bootstrap, though more specifically through hiraeth/http which is a downstream requirement (usually included via an HTTP implementation like hiraeth/diactoros).

If you’ve not installed any these packages or are integrating your own libraries, you can create your own custom entry point. We’ll deconstruct the entry point for hiraeth/http to get a better idea of the steps involved.

Finding the Application Root

In order to boot Hiraeth\Application we’ll need to know what our application root is. The way this is achieved in default Hiraeth entry points is by simply tracking back through parent directories until we find our composer.json.

for (
	$root_path  = __DIR__;
	$root_path != '/' && !is_file($root_path . DIRECTORY_SEPARATOR . 'composer.json');
	$root_path  = realpath($root_path . DIRECTORY_SEPARATOR . '..')
);

The above allows the entry point to be moved into any sub-directory of the application root and still function as expected without having to change a static or relative root path.

Get Autoloader and Application

Once we know our application root, we can load composer’s autoloader and get our application instance:

$loader  = require $root_path . '/vendor/autoload.php';
$hiraeth = new Hiraeth\Application($root_path);

In addition to the $root_path you can also specify an environment file path and a release file path as the second and third argument respectively, but these are niche use cases.

Handling Static Files

If you intend to use Hiraeth’s provided bin/server command which just wraps the PHP built-in server, you’ll also want to handle some static file look-ups. The following code just checks to see if a file exists in the current public folder corresponding to the request path and returns false if we’re running the PHP built-in development server. Returning false tells the built-in server that the request is not handled by PHP:

$req_path = parse_url($_SERVER['REQUEST_URI'])['path'] ?? '/';

if (PHP_SAPI == 'cli-server' && is_file(__DIR__ . $req_path)) {
	return FALSE;
}

Executing Hiraeth

Finally, once we have our application instance, we can execute Hiraeth:

$hiraeth->exec(function() {
	//
	// Do application stuff
	//
});

The $hiraeth->exec() method will return whatever value is returned from the callback passed, so for console based entry points you may want to wrap it in an exit() in order to exit with the return code. Within the context of the callback, $this refers to the application instance itself. Additionally dependencies can be dependency injected by typehinting them as arguments to the callback.

The default Hiraeth functionality provided by hiraeth/http is to have injected implementations for:

And, finally Laminas\HttpHandlerRunner\Emitter\SapiEmitter, which is provided by laminas/laminas-httphandlerrunner to emit PSR-7 response objects.

The hiraeth/http package does not require or provide implementations for the first two mentioned interfaces, rather it is up to an implementation package to alias these interfaces to whatever concrete implementation it uses. The hiraeth/diactoros package provides such implementation via laminas/laminas-diactoros.

The default executed code where $emmitter, $handler, and $request are our injected instances, therefore, is simply:

return $emitter->emit($handler->handle($request)) ? 0 : 1;