Run HTTP

App handles the internet Hypertext Transfer Protocol in a very easy-to-use way.

Let's see an example creating a little application:

We will need to autoload classes, so we will set default configs for the Autoloader Service.

This app will respond to two origins. One is the web front end. Another is the REST API.

The default Router Service will load one file for each origin.

This is the public/index.php file:

use Framework\MVC\App;

(new App([
    'autoloader' => [
        'default' => [
            'namespaces' => [
                'Api' => __DIR__ . '/../api',
            ],
        ],
    ],
    'router' => [
        'default' => [
            'files' => [
                __DIR__ . '/../routes/front.php',
                __DIR__ . '/../routes/api.php',
            ],
        ],
    ],
]))->runHttp(); // void

And now, let's create the router files:

The routes/front.php file is for the front end. The origin will be https://domain.tld. Change if you want:

use Framework\MVC\App;
use Framework\Routing\RouteCollection;

App::router()->serve('https://domain.tld', function (RouteCollection $routes) {
    $routes->get('/', fn () => '<h1>Homepage</h1>');
}); // static

The routes/api.php is for the REST API. The origin will be https://api.domain.tld. Change if you need:

use Framework\MVC\App;
use Framework\Routing\RouteCollection;

App::router()->serve('https://api.domain.tld', function (RouteCollection $routes) {
    $routes->get('/', fn () => App::router()->getMatchedCollection());
    $routes->post('/users', 'Api\UsersController::create');
    $routes->get('/users/{int}', 'Api\UsersController::show/0', 'users.show');
}, 'api'); // static

This is the api/UsersController.php example:

namespace Api;

use Framework\HTTP\Response;
use Framework\HTTP\ResponseHeader;
use Framework\HTTP\Status;
use Framework\MVC\App;
use Framework\MVC\Controller;

class UsersController extends Controller
{
    public function create() : Response
    {
        $data = $this->request->getPost();
        $errors = $this->validate($data, [
            'name' => 'minLength:5|maxLength:64',
            'email' => 'email',
        ]);
        if ($errors) {
            return $this->response
                ->setStatus(Status::BAD_REQUEST)
                ->setJson([
                    'errors' => $errors,
                ]);
        }
        // TODO: Create the UsersModel to insert the new user
        // ...
        $user = [
            'id' => rand(1, 1000000),
            'name' => $data['name'],
            'email' => $data['email'],
        ];
        return $this->response
            ->setStatus(Status::CREATED)
            ->setHeader(
                ResponseHeader::LOCATION,
                App::router()->getNamedRoute('api.users.show')
                    ->getUrl(pathArgs: [$user['id']])
            )->setJson($user);
    }
}

After that, the application will have the following files:

• public/index.php
• routes/front.php
• routes/api.php
• api/UsersController.php

Put you server to run and access the URLs https://domain.tld and https://api.domain.tld.

You can make a POST request with curl to https://api.domain.tld/users:

curl -i -X POST https://api.domain.tld/users \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name=John&[email protected]"

That's it. The basic HTTP application structure is created and working.

You can improve it with Models, Views and Controllers.

Run CLI

App handles Command-Line Interface with the Console Service.

Let's create the console.php file:

use Framework\MVC\App;

$app = new App();
$app::config()->set('console', [
    'directories' => [
        __DIR__ . '/commands',
    ]
]);
$app->runCli(); // void

Now, let's add a command in the commands/Meet.php file:

use Framework\CLI\CLI;
use Framework\CLI\Command;

class Meet extends Command
{
    public function run() : void
    {
        $name = CLI::prompt('What is your name?', 'Tadandan');
        CLI::write("Nice to meet you, $name. I'm Aplus.");
    }
}

Go to the terminal and run:

php console.php

The console will output meet as an available command.

To execute it, run:

php console.php meet

That's it.

Anti-CSRF Service

Gets an instance of Framework\HTTP\AntiCSRF.

App::antiCsrf()

[
    'antiCsrf' => [
        'default' => [
            'enabled' => true,
            'token_name' => 'csrf_token',
            'session_instance' => 'default',
            'request_instance' => 'default',
        ],
    ],
]

Autoloader Service

Gets an instance of Framework\Autoload\Autoloader.

App::autoloader()

[
    'autoloader' => [
        'default' => [
            'register' => true,
            'extensions' => '.php',
            'namespaces' => null,
            'classes' => null,
        ],
    ],
]

Cache Service

Gets an instance of Framework\Cache\Cache.

App::cache()

[
    'cache' => [
        'default' => [
            'class' => ???, // Must be set
            'configs' => [],
            'prefix' => null,
            'serializer' => Framework\Cache\Serializer::PHP,
            'logger_instance' => 'default',
        ],
    ],
]

Console Service

Gets an instance of Framework\CLI\Console.

App::console()

[
    'console' => [
        'default' => [
            'directories' => null,
            'find_in_namespaces' => false,
            'language_instance' => 'default',
            'locator_instance' => 'default',
        ],
    ],
]

Database Service

Gets an instance of Framework\Database\Database.

App::database()

[
    'database' => [
        'default' => [
            'config' => ???, // Must be set
            'logger_instance' => 'default',
        ],
    ],
]

Debugger Service

Gets an instance of Framework\Debug\Debugger.

App::debugger()

[
    'debugger' => [
        'default' => [
            'debugbar_view' => null,
            'options' => null,
        ],
    ],
]

Exception Handler Service

Gets an instance of Framework\Debug\ExceptionHandler.

App::exceptionHandler()

[
    'exceptionHandler' => [
        'default' => [
            'environment' => Framework\Debug\ExceptionHandler::PRODUCTION,
            'logger_instance' => 'default',
            'language_instance' => 'default',
            'development_view' => null,
            'production_view' => null,
            'initialize' => true,
            'handle_errors' => true,
        ],
    ],
]

Language Service

Gets an instance of Framework\Language\Language.

App::language()

[
    'language' => [
        'default' => [
            'default' => 'en',
            'supported' => null,
            'negotiate' => false,
            'request_instance' => 'default',
            'fallback_level' => Framework\Language\FallbackLevel::none,
            'directories' => [],
            'find_in_namespaces' => false,
            'autoloader_instance' => 'default',
        ],
    ],
]

Locator Service

Gets an instance of Framework\Autoload\Locator.

App::locator()

[
    'locator' => [
        'default' => [
            'autoloader_instance' => 'default',
        ],
    ],
]

Logger Service

Gets an instance of Framework\Log\Logger.

App::logger()

[
    'logger' => [
        'default' => [
            'class' => Framework\Log\Logger\MultiFileLogger::class,
            'destination' => ???, // Must be set
            'level' => Framework\Log\LogLevel::DEBUG,
            'config' => [],
        ],
    ],
]

Mailer Service

Gets an instance of Framework\Email\Mailer.

App::mailer()

[
    'mailer' => [
        'default' => [
            'class' => Framework\Email\Mailers\SMTPMailer::class,
            'config' => ???, // Must be set
        ],
    ],
]

Migrator Service

Gets an instance of Framework\Database\Extra\Migrator.

App::migrator()

[
    'migrator' => [
        'default' => [
            'database_instance' => 'default',
            'directories' => ???, // Must be set
            'table' => 'Migrations',
        ],
    ],
]

Request Service

Gets an instance of Framework\HTTP\Request.

App::request()

[
    'request' => [
        'default' => [
            'server_vars' => [],
            'allowed_hosts' => [],
            'force_https' => false,
        ],
    ],
]

Response Service

Gets an instance of Framework\HTTP\Response.

App::response()

[
    'response' => [
        'default' => [
            'headers' => [],
            'auto_etag' => false,
            'auto_language' => false,
            'language_instance' => 'default',
            'cache' => null,
            'request_instance' => 'default',
        ],
    ],
]

Router Service

Gets an instance of Framework\Routing\Router.

App::router()

[
    'router' => [
        'default' => [
            'files' => [],
            'placeholders' => [],
            'auto_options' => null,
            'auto_methods' => null,
            'response_instance' => 'default',
            'language_instance' => 'default',
        ],
    ],
]

Session Service

Gets an instance of Framework\Session\Session.

App::session()

[
    'session' => [
        'default' => [
            'save_handler' => [
                'class' => null,
                'config' => [],
            ],
            'options' => [],
            'auto_start' => null,
            'logger_instance' => 'default',
        ],
    ],
]

Validation Service

Gets an instance of Framework\Validation\Validation.

App::validation()

[
    'validation' => [
        'default' => [
            'validators' => [
                Framework\MVC\Validator::class,
                Framework\Validation\FilesValidator::class,
            ],
            'language_instance' => 'default',
        ],
    ],
]

View Service

Gets an instance of Framework\MVC\View.

App::view()

[
    'view' => [
        'default' => [
            'base_dir' => ???, // Must be set
            'extension' => '.php',
            'layout_prefix' => null,
            'include_prefix' => null,
            'show_debug_comments' => true,
        ],
    ],
]

Extending

Built-in services are designed to be extended.

Let's look at an example extending the HTTP Request class and adding two custom methods, isGet and isPost:

namespace Lupalupa\HTTP;

class Request extends \Framework\HTTP\Request
{
    public function isGet() : bool
    {
        return $this->hasMethod('get');
    }

    public function isPost() : bool
    {
        return $this->hasMethod('post');
    }
}

Now, let's extend the App class:

The App::request method return type can be replaced by a child class thanks to Covariance.

The example below adds a new method, App::other, which also uses Late Static Bindings.

use Lupalupa\HTTP\Request;
use Lupalupa\Other;

class App extends \Framework\MVC\App
{
    public static function request(string $instance = 'default') : Request
    {
        $service = static::getService('request', $instance);
        if ($service) {
            return $service;
        }
        $config = static::config()->get('request', $instance);
        return static::setService(
            'request',
            new Request($config['allowed_hosts'] ?? null),
            $instance
        );
    }

    public static function other(string $instance = 'default') : Other
    {
        $service = static::getService('other', $instance);
        if ($service) {
            return $service;
        }
        $config = static::config()->get('other', $instance);
        $service = new Other(
            static::request($config['request_instance'] ?? 'default')
        );
        if (isset($config['foo'])) {
            $service->setFoo($config['foo']);
        }
        return static::setService('other', $service, $instance);
    }
}

Finally, you will be able to use the custom instance of Request and Other anywhere in your application:

App::request()->isGet();
App::request()->isPost();

App::other()->doSomething();
App::other('other_instance')->doSomething();

Tip: Use a smart IDE. Aplus loves it. Be happy.

Table Name

The table name can be set in the $table property.

protected string $table;

If the name is not set the first time the getTable method is called, the table name will automatically be set to the class name. For example, if the class is called App\Models\PostsModel, the table name will be Posts.

Database Connections

Each model allows two database connections, one for reading and one for writing.

The connections are obtained through the Framework\MVC\App::database method and the name of the instances must be defined in the model.

To set the name of the read connection instance, use the $connectionRead property.

protected string $connectionRead = 'default';

The name of the connection can be obtained through the getConnectionRead method and the instance of Framework\Database\Database can be obtained through the getDatabaseToRead method.

The name of the write connection, by default, is also default. But it can be modified through the $connectionWrite property.

protected string $connectionWrite = 'default';

The name of the write connection can be taken by the getConnectionWrite method and the instance by getDatabaseToWrite.

Primary Key

To work with a model, it is necessary that its database table has an auto-incrementing Primary Key, because it is through it that data is found by the find method, and rows are also updated and deleted.

By default, the name of the primary key is id, as in the example below:

protected string $primaryKey = 'id';

It can be obtained with the getPrimaryKey method.

The primary key field is protected by default, preventing it from being changed in write methods such as create, update and replace:

protected bool $protectPrimaryKey = true;

You can check if the primary key is being protected by the isProtectPrimaryKey method.

If it is protected, but allowed in Allowed Fields, an exception will be thrown saying that the primary key field is protected and cannot be changed by writing methods.

Allowed Fields

To manipulate a table making changes it is required that the fields allowed for writing are set, otherwise a LogicException will be thrown.

Using the $allowedFields property, you can set an array with the names of the allowed fields:

protected array $allowedFields = [
    'name',
    'email',
];

This list can be obtained with the getAllowedFields method.

Note that the data is filtered on write operations, removing all disallowed fields.

Return Type

When reading data, by default the rows are converted into stdClass objects, making it easier to work with object orientation.

But, the $returnType property can also be set as array (making the returned rows an associative array) or as a class-string of a child class of Framework\MVC\Entity.

protected string $returnType = stdClass::class;

The return type can be obtained with the getReturnType method.

Results are automatically converted to the return type in the find, findAll and paginate methods.

Automatic Timestamps

With models it is possible to save the creation and update dates of rows automatically.

To do this, just set the $autoTimestamps property to true:

protected bool $autoTimestamps = false;

To find out if automatic timestamps are enabled, you can use the isAutoTimestamps method.

By default, the name of the field with the row creation timestamp is createdAt and the field with the update timestamp is called updatedAt.

Both fields can be changed via the $fieldCreated and $fieldUpdated properties:

protected string $fieldCreated = 'createdAt';
protected string $fieldUpdated = 'updatedAt';

To get the name of the automatic timestamp fields you can use the getFieldCreated and getFieldUpdated methods.

The timestamp format can also be customized. The default is like the example below:

protected string $timestampFormat = 'Y-m-d H:i:s';

And, the format can be obtained through the getTimestampFormat method.

The timestamps are generated using the timezone of the write connection and, if it is not set, it uses UTC.

A timestamp formatted in $timestampFormat can be obtained with the getTimestamp method.

When the fields of $fieldCreated or $fieldUpdated are set to $allowedFields they will not be removed by filtering, and you can set custom values.

Validation

When one of the create, update or replace methods is called for the first time, the $validation property will receive an instance of Framework\Validation\Validation for exclusive use in the model, which can be obtained by the getValidation method.

To make changes it is required that the validation rules are set, otherwise a RuntimeException will be thrown saying that the rules were not set.

You can set the rules in the $validationRules property:

protected array $validationRules = [
    'name' => 'minLength:5|maxLength:32',
    'email' => 'email',
];

Or returning in the getValidationRules method.

Validators can also be customized. By default, the ones used are Framework\MVC\Validator and Framework\Validation\FilesValidator:

protected array $validationValidators = [
    Validator::class,
    FilesValidator::class,
];

The list of validators can be obtained using the getValidationValidators method.

The labels with the name of the fields in the error messages can also be customized, being set in the $validationLabels property:

protected array $validationLabels;

Or through the getValidationLabels method, as in the example below, setting the labels in the current language:

protected function getValidationLabels() : array
{
    return $this->validationLabels ??= [
        'name' => $this->getLanguage()->render('users', 'name'),
        'email' => $this->getLanguage()->render('users', 'email'),
    ];
}

The same goes for setting custom error messages. They can be set in the $validationMessages property:

protected array $validationMessages;

And obtained by the getValidationMessages method.

When create, update or replace return false, errors can be retrieved via the getErrors method.

Pagination

Using the paginate method, you can perform a basic pagination with all the data in a table.

Below, we take the first 30 items from the table:

$page = 1;
$perPage = 30;
$data = $model->paginate($page, $perPage); // array

After calling the paginate method, the $pager property will have an instance of the Framework\Pagination\Pager class, which can be obtained by the getPager method.

So you can render the pagination wherever you need it, like in the HTTP Link header or as HTML in views:

echo $model->getPager()->render('bootstrap');

In the $pagerView property you can define the default Pager view:

protected string $pagerView = 'bootstrap';

So this view will always render by default:

echo $model->getPager()->render();

Also, it is possible to set the Pager URL in the $pagerUrl property, which is unnecessary in HTTP requests, but required in the command line.

Cache

The model has a cache system that works with individual results. For example, once the $cacheActive property is set to true, when obtaining a row via the find method, the result will be stored in the cache and will be available directly from it for the duration of the Time To Live, defined in the $cacheTtl property.

When an item is updated via the update method, the cached item will also be updated.

When an item is deleted from the database, it is also deleted from the cache.

With the active caching system it reduces the load on the database server, as the rows are obtained from files or directly from memory.

Below is the example with the cache inactive. To activate it, just set the value to true.

protected bool $cacheActive = false;

Whenever you want to know if the cache is active, you can use the isCacheActive method.

And the name of the service instance obtained through the method Framework\MVC\App::cache can be set as in the property below:

protected string $cacheInstance = 'default';

Whenever it is necessary to get the name of the cache instance, you can use the getCacheInstance method and to get the object instance of the Framework\Cache\Cache class, you can use the getCache method.

The default Time To Live value for each item is 60 seconds, as shown below:

protected int $cacheTtl = 60;

This value can be obtained through the getCacheTtl method.

Language

Some features, such as validation, on labels and error messages, or pagination need an instance of Framework\Language\Language to locate the displayed texts.

The name of the instance defined in the $languageInstance property is obtained through the service available in the Framework\MVC\App::language method, and can be obtained through the getLanguage method.

The default instance is default, as shown below:

protected string $languageInstance = 'default';

CRUD

The model has methods to work with basic CRUD operations, which are:

• Create
• Read
• Update
• Delete

$data = [
    'name' => 'John Doe',
    'email' => '[email protected]',
];
$id = $model->create($data); // Insert ID or false

if ($id === false) {
    $errors = $model->getErrors();
}

$id = 1;
$row = $model->find($id);

$limit = 10;
$offset = 20;
$rows = $model->findAll($limit, $offset); // array

$id = 1;
$data = [
    'name' => 'Johnny Doe',
];
$affectedRows = $model->update($id, $data); // int, string or false

$id = 1;
$affectedRows = $model->delete($id); // int, string or false

$count = $model->count(); // int

$id = 1;
$data = [
    'name' => 'John Morgan',
    'email' => '[email protected]',
];
$affectedRows = $model->replace($id, $data); // int, string or false

$data = [
    'id' => 1,
    'email' => '[email protected]',
];
$result = $model->save($data); // int, string or false

Entities

Entities represent rows in a database table. They can be used as a Return Type in models.

Let's see the entity User below:

use Framework\Date\Date;
use Framework\HTTP\URL;
use Framework\MVC\Entity;

class User extends Entity
{
    protected int $id;
    protected string $name;
    protected string $email;
    protected string $passwordHash;
    protected URL $url;
    protected Date $createdAt;
    protected Date $updatedAt;
}

And, it can be instantiated as follows:

$user = new User([
    'id' => 1,
    'name' => 'John Doe',
]);

protected URL $url;
protected string $name;

protected function init() : void
{
    $this->name = $this->firstname . ' ' . $this->lastname;
    $this->url = new URL('https://domain.tld/users/' . $this->id);        
}

$isSet = isset($user->id); // bool

unset($user->id);

$id = $user->id; // 1
$id = $user->getId(); // 1

$user->id = 3;
$user->setId(3);

To Model

Through the toModel method, the object is transformed into an associative array ready to be written to the database.

Conversion to array can be done directly, as below:

$data = $user->toModel(); // Associative array

Or passed directly to one of a model's methods.

Let's see how to create a row using the variable $user, which is an entity:

$id = $model->create($user); // Insert ID or false

JSON Encoding

When working with APIs, it may be necessary to convert an Entity to a JSON object.

To set which properties will be JSON-encoded just list them in the property $_jsonVars:

class User extends Entity
{
    protected array $_jsonVars = [
        'id',
        'name',
        'url',
        'createdAt',
    ];
}

Once this is done, the entity can be encoded. Let's see in the following example:

echo json_encode($user, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

And then the JSON object:

{
    "id": 1,
    "name": "John Doe",
    "url": "https://domain.tld/users/1",
    "createdAt": "2022-06-10T18:36:52-03:00"
}

Note that the url and createdAt property objects have been serialized.

exist

Requires that a value exists in the database.

exist:$tableColumn
exist:$tableColumn,$connection

The rule has two parameters: $tableColumn and $connection.

$tableColumn is the table name and, optionally, the column name separated by a dot. If the column is not defined, the field name will be used as the column name.

$connection is the name of the database connection. The default is default.

unique

Requires that a value is not registered in the database.

unique:$tableColumn
unique:$tableColumn,$ignoreColumn,$ignoreValue
unique:$tableColumn,$ignoreColumn,$ignoreValue,$connection

The rule has four parameters: $tableColumn, $ignoreColumn, $ignoreValue and $connection.

$tableColumn is the table name and, optionally, the column name separated by a dot. If the column is not defined, the field name will be used as the column name.

$ignoreColumn is the name of the column to ignore if the value is already registered. Usually when updating data.

$ignoreValue is the value to be ignored in the $ignoreColumn.

$connection is the name of the database connection. The default is default.

Extending Layouts

The View has a basic layout system that other view files can extend.

Let's see the layout file views/_layouts/default.php below:

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title><?= $title ?></title>
</head>
<body>
<?= $view->renderBlock('contents') // string or null ?>
</body>
</html>

Then, in the view that will be rendered by the render method, the file _layouts/default sets the content inside the contents block:

views/home/index.php

<?php
$view->extends('_layouts/default'); // static
$view->block('contents'); // static
?>
<h1><?= $title ?></h1>
<p><?= $description ?></p>
<?php
$view->endBlock(); // static

If you want to extend views always from the same directory, you can set the layout prefix:

$view->setLayoutPrefix('_layouts'); // static

This will make it unnecessary to type the entire path. See the example below:

- $view->extends('_layout/default');
+ $view->extends('default');

When working with only one file that extends a layout, it is possible to set the default block name in the second argument of extends.

Let's see how to extend the default layout and capture the content in the file views/home/index.php:

<?php
$view->extends('default', 'contents'); // static
?>
<h1><?= $title ?></h1>
<p><?= $description ?></p>

So the rendered HTML file will look like this:

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Welcome!</title>
</head>
<body>
<h1>Welcome!</h1>
<p>Welcome to Aplus MVC.</p>
</body>
</html>

View Includes

It is often common to have parts of the layout that are repeated. Like for example, a header, a footer, a sidebar.

These files are called includes.

Let's see an example of include with a navigation bar in the file views/_includes/navbar.php:

<div class="navbar">
<ul>
    <li<?= $active === 'home' ? ' class="active"' : ''?>>
        <a href="/">Home</a>
    </li>
    <li<?= $active === 'contact' ? ' class="active"' : ''?>>
        <a href="/contact">Contact</a>
    </li>
</ul>
</div>

This navbar will appear in several layouts, including the default one.

Let's see below how to make it appear in views that extend the layout views/_layouts/default.php:

<body>
<?= $view->include('_includes/navbar') // string ?>
<h1><?= $title ?></h1>

As with layouts, you can set the includes path prefix:

$view->setIncludePrefix('_includes');

Once the includes path is set, it is no longer necessary to include it in the include method call:

- $view->include('_includes/navbar');
+ $view->include('navbar');

The call in the default layout will be like this:

<body>
<?= $view->include('navbar') // string ?>
<h1><?= $title ?></h1>

When necessary, you can pass an array of data to the include.

Let's see how to pass the variable active with the value home:

<body>
<?= $view->include('navbar', ['active' => 'home']) // string ?>
<h1><?= $title ?></h1>

When rendered, the include will show the active class on the Home line in the navbar:

<div class="navbar">
<ul>
    <li class="active">
        <a href="/">Home</a>
    </li>
    <li>
        <a href="/contact">Contact</a>
    </li>
</ul>
</div>

View Blocks

Below we will see how to create a block called contents and another called scripts in the views/home/index.php file:

<?php
$view->extends('default'); // static

$view->block('contents'); // static
?>
<h1><?= $title ?></h1>
<p><?= $description ?></p>
<?php
$view->endBlock(); // static

$view->block('scripts'); // static
?>
<script>
    console.log('Hello!');
</script>
<?php
$view->endBlock(); // static

In the views/_layouts/default.php file we can render the two blocks:

<body>
<?= $view->renderBlock('contents') // string or null ?>
<?= $view->renderBlock('scripts') // string or null ?>
</body>

And the output will be like this:

<body>
<h1>Welcome!</h1>
<p>Welcome to Aplus MVC.</p>
<script>
    console.log('Hello!');
</script>
</body>

Render Views

Instead of building all the page content inside the index method, you can use the render method, with the name of the file that will be rendered, building the HTML page as a view.

In this case, we render the home/index view:

use Framework\MVC\Controller;

class Home extends Controller
{
    public function index() : string
    {
        return $this->render('home/index');
    }
}

Validate Data

When necessary, you can validate data using the validate method.

In it, it is possible to put the data that will be validated, the rules, and, optionally, the labels, the messages and the name of the validation service instance, which by default is default.

In the example below we highlight the create method, which can be called by the HTTP POST method to create a contact message.

Note that the rules are set and then the POST data is validated, returning an array with the errors and showing them on the screen in a list or an empty array, showing that no validation errors occurred and the message that was created successfully:

use Framework\MVC\Controller;

class Contact extends Controller
{
    public function index() : string
    {
        return $this->render('contact/index');
    }

    public function create() : void
    {
        $rules = [
            'name' => 'required|minLength:5|maxLength:32',
            'email' => 'required|email',
            'message' => 'required|minLength:10|maxLength:1000',
        ];
        $errors =  $this->validate($this->request->getPost(), $rules);
        if ($errors) {
            echo '<h2>Validation Errors</h2>';
            echo '<ul>';
            foreach($errors as $error) {
                echo '<li>' . $error . '</li>';
            }
            echo '</ul>';
            return;
        }
        echo '<h2>Contact Successful Created</h2>';
    }
}

HTTP Request and Response

The Controller has instances of the two HTTP messages, the Request and the Response, accessible through properties that can be called directly.

Let's see below how to use Request to get the current URL as a string and put it in the Response body:

use Framework\HTTP\Response;
use Framework\MVC\Controller;

class Home extends Controller
{
    public function index() : Response
    {
        $url = (string) $this->request->getUrl();
        return $this->response->setBody(
            'Current URL is: ' . $url
        );
    }
}

The example above is simple, but $request and $response are powerful, having numerous useful methods for working on HTTP interactions.

Model Instance

Often, a controller works with a specific model and through the $modelClass property it is possible to set the Fully Qualified Class Name of a ModelInterface child class so that an instance of it is automatically loaded, in all requests, in the construction of the controller.

Let's see below that $modelClass receives the name of the App\Models\UsersModel class and in the show method the direct call to the $model property is used, which has the instance of App\Models\UsersModel:

use App\Models\UsersModel;
use Framework\MVC\Controller;

class Users extends Controller
{
    protected string $modelClass = UsersModel::class;

    public function show(int $id) : string
    {
        $user = $this->model->find($id);
        return $this->render('users/show', [
            'user' => $user,
        ]);
    }
}

JSON Responses

As with the Framework\Routing\RouteActions class, the controller action methods can return an array, stdClass, or JsonSerializable instance so that the Response is automatically set with the JSON Content-Type and the message body as well.

In the example below, we see how to get the users of a page, with an array returned from the model's paginate method, and then returned to be JSON-encoded and added to the Response body:

use App\Models\UsersModel;
use Framework\MVC\Controller;

class Users extends Controller
{
    protected string $modelClass = UsersModel::class;

    public function index() : array
    {
        $page = $this->request->getGet('page')
        $users = $this->model->paginate($page);
        return $users;
    }
}

Before and After Actions

Every controller has two methods inherited from Framework\Routing\RouteActions that can be used to prepare configurations, filter input data, and also to finalize configurations and filter output data.

They are beforeAction and afterAction.

Let's look at a simple example to validate a user's access to a dashboard's pages.

We create the AdminController class and put a check in it to see if the user_id is set in the session. If not, the page will be redirected to the location /login. Otherwise, access to the action method is released and the user can access the admin area:

use Framework\MVC\App;
use Framework\MVC\Controller;

abstract class AdminController extends Controller
{
    protected function beforeAction(string $method, array $arguments) : mixed
    {
        if ( ! App::session()->has('user_id')) {
            return $this->response->redirect('/login');
        }
        return null;
    }
}

Below, the Dashboard methods will only be executed if beforeAction returns null in the parent class, AdminController:

final class Dashboard extends AdminController
{
    public function index() : string
    {
        return 'You are in Admin Area!';
    }
}