Enplated MVC Documentation

1.1 MVC Basics

MVC is an architectural pattern that separates an application into three main logical components: Model, View, and Controller. Each of them handles specific development aspects of an application. In Enplated MVC, they work as follows:

• Controller is tied to a specific path and is triggered when a request matches that path and its method (GET, POST, etc.). It gets all the data from the Model(s) and passes it to the View, which is then displayed.
• Model is a collection of pure functions (here, a pure function does not affect anything outside of itself, apart from changing the state of the DB, etc.). The Controller typically calls one or more functions from the Model(s), and they return data to the Controller.
• View receives data from the Controller, processes it and displays it to the user. It is generally HTML, supplemented with special tags for outputting data (see below) and occasionally small sections of PHP code. However, the View does not decide whether the user is allowed to see the page (that is the Controller's job), nor does it get data from the DB (that is the Model's job).

The following diagram illustrates this:

1.2 Demo Blog App

A demo blog app built with Enplated MVC is available in the latest release on GitHub. Just download the demo-vX-X.zip file.

1.3 Handling a User Request

.htaccess handles the redirection of all requests as follows:

• If the request targets the /public folder, the file from this folder is served. If the file does not exist in that folder, the request is passed to index.php.
• Otherwise, the request is passed to index.php.

index.php performs the following operations:

• The Error Handler is registered. If an error occurs anywhere in the script, it runs and displays the 500 page if necessary.
• All variables from the .env file are stored in the superglobal variable $_ENV['APP']['key'] - for example, APP_NAME = "My Cool App" in the .env file is stored in $_ENV['APP']['APP_NAME'].
• Helper functions are loaded.
• All databases listed in the engine/database/setup.php file are connected.
• The helper function for Models is loaded.
• The rendering engine for Views is loaded.
• The request itself is processed. The URI and METHOD are stored in the superglobal variable $_ENV['REQUEST'] as follows:

  $_ENV['REQUEST'] = [
      'URI' => "...", // for example: users/veronica/details
      'METHOD' => "...", // for example: GET / POST...
  ];

• All registered Routes Files are scanned for a matching route, which then starts the Controller.
• If no matching route is found, the 404 page from the /engine/errors/404.php file is displayed.

3.1 Registering a Routes File

Create a new PHP file in the /routes folder. The file must not be named default. You can also create a file in a folder nested in /routes. This creates our Routes File. Now we need to register it. Go to /routes/default.php and add this command at the beginning of the file:

registerRoutesFile(__DIR__ . '/nameOfRouteFile.php');

For example, if we created a Routes File named users.php, we would do this:

registerRoutesFile(__DIR__ . '/users.php');

If users.php is in the management folder (/routes/management/users.php), then we modify the command as follows:

registerRoutesFile(__DIR__ . '/management/users.php');

3.2 Simple Route

Go to the Routes File created in the previous section. Call a function with 3 parameters:
checkRoute(METHOD, PATH, function() {...});

• METHOD (String) - The method of the request (GET, POST, PUT, DELETE, etc.).
• PATH - The path of the request (for example, /contact).
The path is relative to the root of the application. If the application is running at the http://localhost/projects/myapp/test URL, the path /contact will be http://localhost/projects/myapp/test/contact.
If you want to match the root of the application, use /.
DO NOT include a trailing slash at the end of the path (except for the root path). If you set the path incorrectly, the application will display a 404 page.
• function - The anonymous function that will be called if the path and method match.
GET /contact and POST /contact are two different routes. If you want to use the same path for different methods, you need to create a separate route for each.

For example, if we want to create a simple route for the /contact path, we would write this:

checkRoute('GET', '/contact', function() {
   ... // Controller
});

In the Controller, we can use any PHP code. We should get data from the Model, process it and pass it to the View. More information can be found in the Models and Views sections.

3.3 Routes with Parameters

Routes can also contain parameters. Parameters are variables that are passed in the path. For example, if we have a path /users/veronica/details, we can extract veronica from the path.

To create a route with parameters, we need to use the {param} syntax. For example, if we want to create a route for the /users/{username}/details path, we would write this:

checkRoute('GET', '/users/{username}/details', function() {
    ... // Controller
});

We can then get the username parameter value from the path in the Controller with the getRequestParam('name') function. For example:
$username = getRequestParam('username');

checkRoute('GET', '/users/{username}/details', function() {
    /*
    This Router is called when the path is /users/_anything_/details.
    If the path is /users/veronica/details, the $username variable will contain 'veronica'.
    If the path is /users/thomas/details, the $username variable will contain 'thomas'.
    */
    $username = getRequestParam('username');
});

More complex paths can be created by combining static parts of the path with parameters. For example, if we want to create a route for the /users/{username}/details/{id} path, we would write this:

checkRoute('GET', '/users/{username}/details/{id}', function() {
    /*
    This Router is called when the path is /users/_anything_/details/_anything_.
    */
    $username = getRequestParam('username');
    $id = getRequestParam('id');
});

3.4 Adjustments in index.php

If you want some code to run on every request, you can put it in the /index.php file. For example, if you want to start a session on every request, you can call the session_start() function at the beginning of the /index.php file.

3.5 /public Folder

The /public folder is the only folder that is accessible from the outside. This is where all the static files (images, CSS, JS, etc.) are stored. Do not place any PHP files in this folder and do not place any images, CSS or JS files in any other folder. How to access these files is described in the Views section.

3.6 Folders Excluded from Routing

If you want to exclude a folder from routing, you can do so by adding the folder name to the .htaccess file. For example, if you want to exclude the /cache folder from routing, you would change the .htaccess file as follows:

RewriteEngine on

# serve existing files in the /public folder directly
RewriteCond %{REQUEST_FILENAME} -f
RewriteRule ^public/(.*)$ public/$1 [L]

# added line
RewriteCond %{REQUEST_FILENAME} -f
RewriteRule ^cache/(.*)$ cache/$1 [L]

# otherwise, route the request to index.php
RewriteRule ^ index.php

4.1 Connect to MySQL / MariaDB

Navigate to the .env file and add the following variables:

DB_HOST = 'host' ; address of the database, for example localhost
DB_USER = 'user' ; username for the database 
DB_PASS = 'pass' ; password for the database
DB_NAME = 'db_name' ; name of the database
DB_PORT = 3306 ; port of the database, for example 3306

Then navigate to the /engine/database/setup.php file and add the following code at the top of the file:

connectToMysqli("db", "DB_HOST", "DB_USER", "DB_PASS", "DB_NAME", "DB_PORT");

db is the name of the database connection. You can have multiple connections to different databases. The connection name must be unique. After a successful connection, you can get it with the getDatabaseEnvConn('db') function. More information can be found in the Get Database Connector section.

The other values are names of variables from the .env file. The names can be changed - for example, you can use HOST_DB_1 instead of DB_HOST.

4.2 Connect to SQLite

Navigate to the /engine/database/setup.php file and add the following code at the top of the file:

connectToSqlite("db",  __DIR__ . "/db.sqlite");

4.3 Get Database Connector

In a Controller, you can get the Database Connector with the getDatabaseEnvConn('name') function. For example, if we have a connection named db, we would write this:

$db = getDatabaseEnvConn('db');

With a MySQL / MariaDB connection, we get a mysqli object. With an SQLite connection, we get a PDO object.

We can then use the $db object to execute queries. More information can be found in the Models section.

4.4 Other Database Types

Enplated MVC supports only MySQL, MariaDB and SQLite databases. If you want to use another database type, you need to create a new function in the /engine/database/setup.php file. You can use the connectToMysqli / connectToSqlite functions as examples.

5.1 Creating a Model

Models are created in the /models folder. The file name must be the same as the name of the Model. For example, if we want to create a Model for the users table, we would create a file named users.php.

You do not need to register Models anywhere (as you do with Routes Files). The Model is registered automatically when the Controller calls it.

5.2 Model Functions

Model Functions are pure functions. They do not affect anything outside of themselves, apart from changing the state of the DB, etc. The Controller typically calls one or more functions from the Model(s), and they return data to the Controller.

For example, let's create two functions for the users model: one returns the user ID by username, the other returns the user's details. We would write this in the models/users.php file:

<?php
    function getUserId($db, $username) {
        $sql = "SELECT id FROM users WHERE username = ?";
        $stmt = $db->prepare($sql);
        $stmt->bind_param("s", $username);
        $stmt->execute();
        $result = $stmt->get_result();
        $stmt->close();
        if ($result->num_rows == 0) {
            return null;
        }

        return $result->fetch_assoc()["id"];
    }

    function getUserDetails($db, $id) {
        $sql = "SELECT * FROM users WHERE id = ?";
        $stmt = $db->prepare($sql);
        $stmt->bind_param("i", $id);
        $stmt->execute();
        $result = $stmt->get_result();
        $stmt->close();
        if ($result->num_rows == 0) {
            return null;
        }

        return $result->fetch_assoc();
    }
?>

5.3 Calling a Model Function

Now go to the Routes File and call the Model Functions from a Controller. We can call a Model Function with the modelCall("model_name", "function_name", [params..]) function.

For example, if we want to create a Controller and call the users model for the /users/{username}/details path, we would write this:

checkRoute('GET', '/users/{username}/details', function() {
    $username = getRequestParam('username');
    $db = getDatabaseEnvConn('db');
//                         ┌ model name         ┌ first parameter                 ┌ second parameter
//                         │	                │	                              │	
    $userId = modelCall("users", "getUserId", ["db" => getDatabaseEnvConn("db"), "username" => $username]);
//                                │
//                                └ function name in model
    ...
});

Now you should be able to create a route, call the Model function and get the data from the Model function. How to display the data is described in the Views section.

6.1 Creating a New View

All View files must be located in the /views root folder (or subfolders). They must end with the .enp extension. After the file is created, you can write any HTML code or special syntax similar to PHP (you can learn more about it in the Syntax section).

6.2 VS Code Extension

If you are using Visual Studio Code, you can install the Enplated MVC Extension. This extension provides syntax highlighting for the .enp files.

1. Open Visual Studio Code.
2. Go to the Extensions tab.
3. Search for Enplated MVC.
4. Click Install.

If you still do not see the syntax highlighting, open any .enp file and click on the bottom right corner where it says Plain Text. Select Enplated MVC Blade from the list.

You can also click Configure File Association for .enp and select Enplated MVC Blade.

6.3 Enplated Blade Files Syntax

Enplated MVC View (Blade) files use a syntax similar to Laravel Blade. It is very simple and easy to learn. The following special tags are available:

@include('path')

Includes another .enp file. The path is relative to the /views folder. For example, if we want to include the /views/partials/header.enp file, we would write this:

@include('partials/header')

{{ $variable }}

Outputs the value of the variable. For example, if we want to output the $username variable, we would write this:

<p>User {{ $username }} is registered from {{ $date }}.</p>

How to pass the variable to the View is described in the Calling a View Renderer section.

{{ env('value') }}

Outputs the value of a variable from the .env file. For example, if we want to output the BASE_URL variable, we would write this:

<a href="{{ env('BASE_URL') }}/contact/veronica">Contact Veronica</a>

{{-- comment --}}

Comments out the code. This section will not be rendered in the final HTML.

{{-- This code is horrible and should be rewritten, but do not show it to the user. --}}

@php, @endphp

Starts a block of PHP code. You can write any PHP code between the @php and @endphp tags. For example, if we want to get the current date, we would write this:

@php
    $date = date("Y-m-d");
@endphp

@if, @elseif, @else, @endif

Starts a conditional statement. You can write any code between the @if and @endif tags. For example, if we want to print a badge based on the user's status, we would write this:

@if ($privilegeLevel == 'admin')
    <span class="badge badge-danger">Admin</span>
@elseif ($privilegeLevel == 'user')
    <span class="badge badge-primary">User</span>
@else
    <span class="badge badge-secondary">Guest</span>
@endif

@foreach, @endforeach

Starts a loop. You can write any code between the @foreach and @endforeach tags. For example, if we want to print all users, we would write this:

@foreach ($users as $user)
    <li>{{ $user['name'] }}</li>
@endforeach

@for, @endfor

Starts a loop. You can write any code between the @for and @endfor tags. For example, if we want to print numbers from 1 to 10, we would write this:

@for ($i = 1; $i <= 10; $i++)
    Number: {{ $i }}
@endfor

To understand the syntax better, this table shows the syntax comparison between Enplated Blade and PHP:

6.4 Calling a View Renderer

We can call the View Renderer with the processTemplate('path', [params..]) function from the Controller. This function will return rendered HTML. For example, if we want to render the /views/users/details.enp file, we would write this:

checkRoute('GET', '/users/{username}/details', function() {
    $username = getRequestParam('username');
    $db = getDatabaseEnvConn('db');
    $userId = modelCall("users", "getUserId", ["db" => getDatabaseEnvConn("db"), "username" => $username]);

//                                ┌ view name (located in /views/users/details.enp)
//                                │
    $template = processTemplate("users/details", ["userId" => $userId, "pageName" => "User Details"]);
//                                                 │           
//                                                 └ variable passed to the view (available for printing, for example with {{ $userId }})

});

6.5 Returning a View to the User

We can return the rendered HTML to the user with the finishRender($html) function. This function will also end the script execution.

For example, if we want to render the /views/users/details.enp file, we would write this:

checkRoute('GET', '/users/{username}/details', function() {
    $username = getRequestParam('username');
    $db = getDatabaseEnvConn('db');
    $userId = modelCall("users", "getUserId", ["db" => getDatabaseEnvConn("db"), "username" => $username]);

    $template = processTemplate("users/details", ["userId" => $userId, "pageName" => "User Details"]);
//     │
//     └────────────┐
//                  ├ rendered HTML
//                  │
    finishRender($template);

//    ┌ this code will never be executed
//    │
    echo "Never gonna give you up\n Never gonna let you down";
});

7.1 Returning Data

We can return data to the user with the resourceView($associative_array, "type") function. This function will return the data in the format specified in the type parameter (json, xml, csv).

For example, if we want to return the user data in JSON format, we would write this:

checkRoute('GET', '/api/users/{username}/details', function() {
    $username = getRequestParam('username');
    $db = getDatabaseEnvConn('db');
    $userId = modelCall("users", "getUserId", ["db" => getDatabaseEnvConn("db"), "username" => $username]);
    $userData = modelCall("users", "getUserDetails", ["db" => getDatabaseEnvConn("db"), "id" => $userId]);

    resourceView($userData, "json");
});

Another example for XML format:

checkRoute('GET', '/api/version', function() {
    resourceView([
        "version" => "1.0",
        "timestamp" => date("Y-m-d H:i:s")
    ], "xml");
});

7.2 Response Types

The user can change the format of the returned data by passing the dataType POST parameter. This works only for POST requests.

This table shows which type is returned for each dataType value:

function resourceView($data, $defaultType) {
    //check if POST includes dataType
    //$dataType = '';
    //if (!isset($_POST['dataType'])) {
        $dataType = $defaultType;
    //} else {
    //    if ($_POST['dataType'] === 'json') {
    //        $dataType = 'json';
    //    } else if ($_POST['dataType'] === 'xml') {
    //        $dataType = 'xml';
    //    } else if ($_POST['dataType'] === 'csv') {
    //        $dataType = 'csv';
    //    } else {
    //        $dataType = 'json';
    //    }
    //}

    ...
}

7.3 robots.txt Example

We can also simply use echo in the Controller. For example, if we want to create a robots.txt file, we would write this Route:

 checkRoute('GET', '/robots.txt', function() {
        header('Content-Type: text/plain; charset=UTF-8');
        echo "User-agent: *\n";
        echo "Disallow: \n";
        echo "Sitemap: https://example.com/sitemap.xml";
        die();
    });

8.1 403 Error Page

The 403 page is not shown automatically; you have to call it in the Controller. For example, if you want to show the 403 error page when the user is not logged in, you would write this:

checkRoute('GET', '/admin', function() {
    ...
    if (!$isLoggedIn) {
        require_once "engine/errors/403.php";
        die();
    }
    ...
});

8.2 404 Error Page

The 404 page is shown automatically when the route is not found. You can edit the /engine/errors/404.php file to customize the 404 error page.

You can also call the 404 error page in the Controller similarly to the 403 error page, but first unset the $_ENV["REQUEST"]["FOUND"] variable:

...
    unset($_ENV["REQUEST"]["FOUND"]);
    require_once "engine/errors/404.php";
    die();
...
                    

8.3 500 Error Page

The 500 page is shown automatically when any error or warning occurs while the script is running. You can edit the /engine/errors/500.php file to customize the 500 error page.

8.4 Database Error Page

The database error page is shown automatically when the database connection fails. You can edit the die_conn() function in the /engine/database/setup.php file to customize the database error page.

8.5 Custom Error Page

You can create your own error pages. Create a new file in the /engine/errors folder and call it in the Controller. Then follow the same procedure as in the 403 Error Page section.

9.1 Built-in Debugger

The Built-in Debugger is shown when the script is running in the development environment and an error occurs. It shows the error message, file, and line where the error occurred. It also shows all variables with their values and a code snippet around the error.

9.2 JS Debugger

The JS Debugger logs the process of finding the correct Route. It is useful for debugging the routing system or when you rewrite some core functions.

To enable the JS Debugger, go to the .env file and change the CONSOLE_LOG variable to true.

9.3 PHP Eval Dump

PHP Eval Dump saves all compiled HTML and PHP code before it is processed by the PHP engine. It is useful for debugging the View files.

To enable the PHP Eval Dump, go to the .env file and change the DEBUG_BUFFER variable to true. The output files will be generated in the /debug folder.