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 these components is built to handle specific development aspects of an application. Their functionality in Enplated MVC are as follows:

• Controller corresponds to the found path and therefore a specific controller is triggered when the path is found correctly with the right type of request (GET, POST..). It gets all the data from the Model(s) and then passes it to the View, which is displayed.
• Model is an enumeration of pure functions (a pure function does not affect anything outside its function, except for changing the state of the DB, etc.). The Controller will typically call one or more functions contained in the model(s), the function will then return data to the Controller.
• View - The Controller passes its data to the View, which is then processed and displayed to the user. This is generally HTML, supplemented with special tags for outputting data (see below) or perhaps smaller sections of PHP code. But in any case, the View no longer solves whether the user has the right to view the page (this is solved by the Controller) or does not get data from the DB (this is solved by the Model).

A diagram is available here for illustration:

1.2 Demo Blog App

You can get a demo blog app created with Enplated MVC in the the latest release in GitHub and by downloading file demo-vX-X.zip.

1.3 Handling User Request

.htaccess handles the redirection of all requests as follows:

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

index.php does the following operations:

• The Error Handler is registered. In case of an error anywhere in the script, it will run and display page 500 if necessary.
• All variables from the .env file are set to the superglobal variable $_ENV['APP']['key'] - for example value set as APP_NAME = "My Cool App" in the .env file is set to the superglobal variable $_ENV['APP']['APP_NAME']
• Auxiliary (helpers) functions are loaded.
• All DBs will be connected if they are listed in the engine/database/setup.php file.
• The help 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 routing files are scanned to find the correct routing path, which then starts the Controller.
• If a matching route is not found, a 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 is how we created our Routing File. Now we need to register it. Go to /routes/default.php and write this command at the beginning of the file:

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

For example, if we created a Routing 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 created Routing file from the previous section. We call a function that has 3 parameters:
checkRoute(METHOD, PATH, function() {...});

• METHOD (String) - The method of the request (GET, POST, PUT, DELETE..).
• PATH - The path of the request (for example, /contact).
The path is relative to the root of the application. If the application is running in 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 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 paths. If you want to use the same path for different methods, you need to create two separate functions.

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 Route with Params

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 get the 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 function getRequestParam('name'). 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 to make some code execute every single time, you can put it in the /index.php file. For example, if you want to start a session every time the application is run, you can put the session_start() function in the beginning /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

# redirect all of the /public requests to /public folder
RewriteCond %{REQUEST_FILENAME} -f
RewriteRule ^public/(.*)$ public/$1 [L]

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

# otherwise, redirect 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 succesfull connection, you can get the connection with the getDatabaseEnvConn('db') function, more information can be found in the Get Database Connector section.

Others variables are from the .env file. The variable 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 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');

When we have MySQL / MariaDB connection, we will get the mysqli object. When we have SQLite connection, we will get the 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 Routing 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 their function, except for changing the state of the DB, etc. The Controller will typically call one or more functions contained in the model(s), the function will then return data to the Controller.

For example, we want to create two functions for model users - one will return used id by username, other will show details for user. We would write this in the file models/users.php:

<?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 and Controller and we will call the Model functions. We can call Model function with the modelCall("model_name", "function_name", [params..]) function.

For example, if we want to create a Controller and call the user 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 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 the PHP code (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 will provide 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 Views (Blade) Files use a syntax similar to Laravel Blade files. The syntax 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 the .env file variable. 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 not rendered in the final HTML.

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

@php, @endphp

Starts the 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 the conditional statement. You can write any conditional statement between the @if and @endif tags. For example, if we want to print the badge by user status, we would write this:

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

@foreach, @endforeach

Starts the loop. You can write any loop 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 the loop. You can write any loop 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:

Enplated Blade Syntax	PHP
@include('filename')	≈ include 'filename';
❴❴ $variable ❵❵	echo htmlentities($variable);
❴❴ env('value') ❵❵	echo getAppEnvVar('value');
@php	<?php
@endphp	?>
@if (condition)	if (condition) {...}
@elseif (condition)	elseif (condition) {...}
@else	else {...}
@endif	(endif; exists, but not used frequently)
@foreach ($array as $item)	foreach ($array as $item) {...}
@endforeach	(endforeach; exists, but not used frequently)
@for (expr1; expr2; expr3)	for (expr1; expr2; expr3) {...}
@endfor	(endfor; exists, but not used frequently)

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 (will be available to print for exaple by ❴❴ $userId ❵❵

});

6.5 Return View to 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";
});