Controller

The controller is responsible for handling user input, processing requests and returning response via the view.

Quick summary

Let's start with a very quick summary of the controller.

<?php
namespace Http\Controllers;

use MaplePHP\Http\Interfaces\ResponseInterface;
use MaplePHP\Http\Interfaces\RequestInterface;
use MaplePHP\Foundation\Http\Provider;
use Http\Controllers\BaseController;

class Pages extends BaseController
{
    private $provider;
    
    public function __construct(Provider $provider)
    {
        $this->provider = $provider;
    }
    
    public function start(ResponseInterface $response, RequestInterface $request): ResponseInterface
    {
        // Your code here -->
        return $response;
    }
}

Controller name

In the example, the controller is named Pages. However, it can be anything you prefer, as long as it conveys its purpose. While "Pages" may be too broad for many apps, it works well for our examples. You'll input the controller name in the router (explained in the next section). The router parses the requested URL and method, matches them to predefined routes, and directs the request to the corresponding controller or handler.

BaseController

You have the option (not required) to extend the BaseController from Http\Controllers. It's more about your preference and coding style. This creates shortcuts to provide efficiency, making it quicker to write code.

So instead of doing this:

class Pages
{
    private $provider;
    
    public function __construct(Provider $provider)
    {
        $this->provider = $provider;
        $firstName = $this->provider->string("john")->toUpper();
    }
...

You can just do this:

class Pages extends BaseController
{
    public function __construct(Provider $provider)
    {
        $firstName = $this->string("john")->toUpper();
    }
...

Both approaches achieve the same outcome, so it's more about personal preference. However, I'll use the first example so that it's clear the functions I'm using come from the Provider.

Response and Request

As mentioned in the previous section, Controllers will have the Dependency Injector loaded by default. However, that's not the only characteristic of a Controller. Another characteristic is that methods will have two expected arguments: PSR-7 Response and Request.

With that let's do some real life examples.

Example 1 - Show content

Here come a real life example on how to display some template views using MaplePHP template engine.

class Pages extends BaseController
{

    public function about(ResponseInterface $response, RequestInterface $request): ResponseInterface
    {
        
        // Add Ingress template section
        $this->provider->view()->setPartial("main.ingress.about", [
            "tagline" => "Ingress view partial",
            "name" => "Welcome to MaplePHP",
            "content" => "Get ready to build you first application."
        ]);
        
        // Add a Text template section
        $this->provider->view()->setPartial("main.text.textA", [
            "tagline" => "Text view partial A",
            "name" => "Lorem ipsum dolor",
            "content" => "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam id sapien dui. Nullam gravida bibendum finibus. Pellentesque a elementum augue. Aliquam malesuada et neque ac varius. Nam id eros eros. Ut ut mattis ex. Aliquam molestie tortor quis ultrices euismod. Quisque blandit pellentesque purus, in posuere ex mollis ac."
        ]);
        
        // Add another Text template section
        $this->provider->view()->setPartial("main.text.textB", [
            "tagline" => "Text view partial B",
            "name" => "Lorem ipsum dolor",
            "content" => "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam id sapien dui. Nullam gravida bibendum finibus. Pellentesque a elementum augue. Aliquam malesuada et neque ac varius. Nam id eros eros. Ut ut mattis ex. Aliquam molestie tortor quis ultrices euismod. Quisque blandit pellentesque purus, in posuere ex mollis ac."
        ]);
        
        return $response;
    }
}

The example above will show 1 ingress (resources/partials/text.php) view and 2 text (resources/partials/ingress.php) partial views. You can read more about how the template engine works under that section.

Example 2 - Display 404

Triggering a 404 page is straightforward. Upon activation, it will replace the current document view with the "resources/views/httpStatus.php" view meaning the ingress partial in the example will not be showed.

class Pages extends BaseController
{

    public function about(ResponseInterface $response, RequestInterface $request): ResponseInterface
    {
        // Add 404 page
        $response = $response->withStatus(404);
        
        // Add Ingress template section
        $this->provider->view()->setPartial("main.ingress", [
            "tagline" => "Ingress view partial",
            "name" => "Wont be visible",
            "content" => "This template will not be shown becouse of 404 page will take over."
        ]);
        
        return $response;
    }
}

With that you can now start building apps and and sites, it is really not harder than that.

Take over the document

You can also take over the document with the help of the PSR Messaging by writing to the PSR Stream. Bellow I will do just that, and create a json response.

Bellow is a quick example on how to generate a 404 page, Without a template engine

public function aboutAPI(ResponseInterface $response, RequestInterface $request): ResponseInterface
{
    $response = $response->withHeader("Content-type", "application/json; charset=UTF-8");
    $response->getBody()->write(json_encode([
        "headline" => "Hello world!",
        "message" => "Lorem ipsum dolor sit amet."
    ]));
    return $response;
}

Let's move on to the Middlewares.