FrostMVC PHP Framework

Prerequisites

FrostMVC is a PHP Framework. It would require the following software or applications to be installed first before running the framework.

• PHP version 7.4 and above
• Apache server version 2.2 and above
• MySQL version 5.0 and above, or MariaDB equivalent
• (Optional) Composer version 2.5 and above

You can install the above applications at once by installing WAMPServer or XAMPP

• For WAMPServer, download here https://www.wampserver.com/en/download-wampserver-64bits/
• For XAMPP, download here https://www.apachefriends.org/download.html

If you are using macOS, you can install MAMP from here https://www.mamp.info/en/downloads/

You can add third-party PHP libraries to FrostMVC using Composer. Simply the following to install Composer here https://getcomposer.org/download/

Download

Download FrostMVC to get the basic templated project files that you can use to start right away!

Installation

Once you downloaded the zip file of FrostMVC, you can simply follow these steps:

1. Extract the zip file using your favourite zip file extractor.
2. Copy the folder FrostMVC-master you extracted from Step 1 to the following folder:
   • If you are using WAMPServer, you can copy the FrostMVC-master folder and paste it to C:/wamp/www or C:/wamp64/www
   • If you are using XAMPP, you can paste the folder to C:/xampp/htdocs
   Installation location might be different depending on the installation configuration of your WAMP or XAMPP
3. Run WAMP or XAMPP. Make sure that all the required services are running, such as Apache and MySQL
4. To run your website, go to http://localhost/FrostMVC-master on your browser and you must be able to see the Welcome page.
   You can change FrostMVC-master to any folder name you prefer. It is also advisable to use a Virtual Host instead.

Configuration

There are certain values that FrostMVC would require to be configured first before it can fully run. These configurations can be found in settings.php file located under app directory

Website Properties

You can change the properties of your website using the $instance global variable, which is an instance of Site class.

The following serves as your guide to edit the app/settings.php file:

• setURL(string url) - change the configured website URL.

  Example: $instance->setURL('https://www.mywebsite.com')

  You can get this value using the following:

  • $instance->getURL() method or BASEPATH constant
  • For .twig files, you can use {{ site.getURL() }} or {{ BASEPATH }}
  The constants BASEPATH and RESOURCEPATH relies to the value configured in setURL() method.
  You might see 404 Not Found error if setURL() is not correctly configured.
• setName(string name) - You can set the name of your website using this method.

  Example: $instance->setName('My Website')

  You can get this value using the following:

  • $instance->getName() method
  • For .twig files, you can use {{ site.getName() }}

• setEnvironment(enum Development|Production) - Set the value to 'Development' if you want the error messages to be displayed, otherwise set the value to 'Production' to hide these messages.

  Example: $instance->setEnvironment('Production')

  You can get this value using the following:

  • $instance->getEnvironment() method
  • For .twig files, you can use {{ site.getEnvironment() }}
  In 'Development' environment,

  • you can access /phpinfo in your website's URL to display the current information of PHP.
  • you can use dump() method in twig files to display the values of a variable.

  These features will be disabled when the website is configured to 'Production' environment.

  Always set environment to 'Production' before you deploy your website.

  The $instance global variable can also be accessed through the following:

  • Site::$instance — a static variable from Site class that references $instance global variable.
    Example:

    Site::$instance->getName()

  • getInstance() — a helper function that returns $instance global variable.
    Example:

    getInstance()->getName()

  To learn more about Site class, you can check the following documentation: Site class

Twig Properties

FrostMVC uses Symfony's Twig as template engine for Views.

You can use the $instance->twig variable to set Twig configuration

Adding global variables in Twig

In FrostMVC, you can add variables that can be accessed throughout your .twig files using the addGlobal(string variableName, any value) method.

Example: $instance->twig->addGlobal('myVariable', 'Hello World!')

In .twig files, you can access them as {{ myVariable }} to display its value Hello World!

Custom Helpers and Custom Classes

You can add your own helper files and custom classes to extend the functionality of FrostMVC. Helpers and custom classes must be saved to the following directories:

• For helper files, they have to be saved in libraries/helpers folder.
• For custom classes, they have to be saved in libraries folder.

To make these helper files and custom classes be recognisable to FrostMVC, you have to load them using $instance->require object, which is an instance of Loader class.

• For helper files, you have to load them using helper() method.
  For example: $instance->require->helper('myhelpers')
  In the example above, FrostMVC will look for a file in the following path: libraries/helpers/myhelpers.php
• For custom classes, you have to load them using library() method
  For example: $instance->require->library('MyCustomClass')
  In the example above, FrostMVC will look for a file in the following path: libraries/MyCustomClass.php
To learn more about helpers and custom classes, read the following article article here

CSRF Token Configuration

You can implement a CSRF (Cross-site Request Forgery) token as additional security to your forms.

Syntax

Security::$CSRFTokenConfig = [
    'regenerate' => true,
    'token-name' => 'x-csrf-token',
    'exclude' => []
];

• regenerate (boolean) - indicates whether FrostMVC will generate a new token for each request. It is recommended to turn this to true only at registration and login forms to prevent used tokens to be submitted more than twice.
• token-name (string) - used to assign a name to the token that FrostMVC will generate.
• exclude (string array) - the list of URL paths that will be excluded from CSRF token validity checking. This can be a full URL or a partial value.
To learn more about this feature, read the following article here

Database Configuration

Please note that currently, FrostMVC only supports MySQL or MariaDB databases as of the moment.

Syntax

$dbname = 'testdb';
$servername = 'localhost';
$username = 'root';
$password = 'mypassword';

define('TABLE_PREFIX', '');
define('TABLE_SUFFIX', '_tbl');

DB::$db = new DB($servername, $username, $password, $dbname); 

• $dbname - this refers to the database name
• $servername - this refers to the host of where the database is connected. The default value is 'localhost'.
• $username - the user that PHP will use to connect to the MySQL or MariaDB instance. To learn more about how to manage users in MySQL, please read this article here.
• $password - The password that your database user account is associated to.

For MySQL table names, developers might be using prefixes, for example tbl_profiles and/or suffixes, for example profiles_tbl, where tbl_ or _tbl is the prefix or suffix.

You can specify these by using the constants TABLE_PREFIX and TABLE_SUFFIX. The Model class will append the values of these constants to the class names behind the scenes during the transaction.

define('TABLE_PREFIX', 'tbl_');
define('TABLE_SUFFIX', '');

define('TABLE_PREFIX', '');
define('TABLE_SUFFIX', '_tbl');

define('TABLE_PREFIX', '');
define('TABLE_SUFFIX', '');

Initiator Methods

Initiator methods are methods that is being called to initialise custom classes and libraries. It is recommended to call the initiator methods at the last part of the settings.php file.

Example

If we want to load the twig extension methods from TwigExtension library class, we can load them first using the load() method.

(new TwigExtension)->load();