VELOX

Key Features

1. Zero dependencies
2. Intuitive and easy to get along with
3. Unlimited flexibility when it comes to customizing it to your exact needs

Installation

Using Composer:

composer create-project marwanalsoltany/velox my-velox-app

Note: You may need to add the --stability=dev depending on the version/branch.

Using Git:

git clone https://github.com/MarwanAlsoltany/velox.git my-velox-app

Fact: If you don't want to use any other third party packages. Installing VELOX using Git is sufficient.

Using source:

Download VELOX as a .zip or .tar.gz and extract it in your server web root directory.

About VELOX

VELOX is a lightweight micro-framework that makes creating a simple website using PHP joyful. It helps you create future-proof websites faster and more efficiently. It provides components that facilitate the process of creating a website using vanilla PHP. VELOX does not have any dependencies, the VELOX package and everything that it needs is included in the project itself. All that VELOX provides is a way to work with config, pass data, register routes, render views, handle exceptions, autoload code, and resolve assets. It provides the View and the Controller parts of an MVC design pattern, leaving the Model part for you to implement as you wish, or use any 3rd-Party Package; in case you needed it. VELOX can also be used as a Static Site Generator if all you need is HTML files in the end.

Why does VELOX exist?

VELOX was created to solve a specific problem, it's a way to build a website that is between dynamic and static, a way to create a simple website with few pages without being forced to use a framework or a CMS that comes with a ton of stuff which will never get used, it's lightweight and straight to the point.

It's not recommended to use VELOX if you have an intermediary project, you would be better off using some well-established frameworks. VELOX is not an initiative to reinvent the wheel, you can look at VELOX as a starter-kit for small projects.

VELOX has a very special use-case, simple websites, and here is meant really simple websites. The advantage is, you don't have stuff that you don't need. Comparing VELOX to Laravel or Symfony is irrelevant, as these frameworks play in a totally different area, it also worth mentioning that VELOX is much simpler than Lumen or Slim.

Architecture

Directory structure

Advice: Most files listed in these directories are documented. Take a look through them to learn more about VELOX.

App Entry

The entry point for a VELOX app is the index.php, here you need to require the bootstrap/autoload.php, register some routes with their handlers using the Router::class, and start the router. This is all that you need to have a working VELOX app.

require 'bootstrap/autoload.php';

Router::handle('/', function () {
    return View::render('home', ['title' => 'Home']);
});

Router::start();

Additionally, you can also set up handlers for 404 and 405 responses using Router::handleRouteNotFound() Router::handleMethodNotAllowed() respectively.

Alternatively, you can extract the "routes registration part" in its own file and let VELOX know about it using bootstrap/additional.php.

Note: In order for VELOX to work correctly and safely, you need to redirect all requests to application entry point (index.php) and block all requests to other PHP files on the server (take a look at .htaccess.dist to get started with Apache).

Config

The following table lists all config files that come shipped with VELOX.

Fact: You can freely add your own config files too, all you need to do is to create a new file under /config and add you own configuration to it. VELOX will know about this file and load it in the application. You can access your config via Config::get('filename.whatEverKeyYouWrote').

Classes

The following table lists all available classes with their description.

VELOX classes are divided in four namespaces:

• MAKS\Velox
• MAKS\Velox\Backend
• MAKS\Velox\Frontend
• MAKS\Velox\Helper

Note: This all what the VELOX package provides out of the box.

Fact: The App, Config, Router, Globals, Data, View, HTML, Path classes are aliased on the root namespace for ease-of-use.

Extending VELOX

To add you own classes use the app/ directory, this is where you should put you own business logic. Note that you have to follow PSR-4 in order for VELOX to load you classes. See app/Controller/DefaultController, to get an idea.

Functions

The following table lists all available functions and to which class/group they belong.

VELOX functions are divided into these files:

• helpers.php: This is where helper functions for VELOX classes live, these are mainly functions that return an instance of class or alias some method on it.
• html.php: This is where HTML helper functions live, these are nothing other than aliases for the most used PHP functions with HTML.

Fact: You can freely add your functions too, all you need to do is to create a new file under functions/ and add you own functions to it. VELOX will know about this file and load it in the application.

Themes

VELOX is built around the idea of themes, a theme is divided into four directories:

• The assets/ directory is where all your static assets associated with this theme will find their place.
• The layouts/ directory is where you define your layouts. A layout in VELOX terminology is the outer framing of a webpage.
• The pages/ directory is where you put the content specific to every page, the page will then be wrapped with some layout of your choice and finally rendered. A page in VELOX terminology is the actual content of a webpage.
• The partials/ directory is where you put all your reusable pieces of the theme, which then will be used in your layouts or pages. A good example for partials could be: Components, Includes, and Content-Elements.

You can customize the behavior of themes using the config/theme.php file. Here you can set the active theme with the active key. Themes can inherit from each other by setting parent(s) with the parent key. You can also change the theme directory structure if you wish to using the paths key. Other configurations that worth taking a look at which have to do with themes can be found in the config/view.php file.

Advice: You can take a look at the provided velox theme to see how all stuff work together in practice.

Examples:

1. Layout: themes/velox/layouts/main.phtml
2. Page: themes/velox/pages/home.phtml
3. Partial: themes/velox/partials/text-image.phtml

License

VELOX is an open-source project licensed under the MIT license.
Copyright (c) 2021 Marwan Al-Soltany. All rights reserved.