README

VELOX

The fastest way to build simple websites using PHP!

Table of Contents

Installation
About VELOX
Architecture
Config
Classes
Functions
Commands
Themes
Extending VELOX
MVC
Templating
Authentication
Changelog
Documentation

^{If you like this project and would like to support its development, giving it a ⭐ would be appreciated!}

Check out the Demo or play with the REPL.

Do you feel like reading? Check out the full API on the documentation website on marwanalsoltany.github.io/velox.

Key Features

Zero dependencies
Minimal, intuitive and easy to get along with
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. You may also want to add --no-dev flag to not install development dependencies.

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.

Advice: If you want to test out VELOX quickly and you don't have any web server available, use whatever installing method and run php bin/app-serve from inside VELOX directory. This command will spin up a development web server on localhost:8000 (Note that you need to have at least PHP installed on your system).

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 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, interact with the database, render views, handle exceptions, autoload code, and resolve assets. It provides the View and the Controller parts of an MVC design pattern. Staring from v1.3.0, VELOX also provides the Model part, making it a fully featured MVC framework and starting from v1.4.0 it also comes shipped with a simple authentication system. 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, minimal, and straight to the point.

It's not recommended to use VELOX if you have an intermediary project, you would be better off using a well-established framework. 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.

<?php

require 'bootstrap/autoload.php';


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

Router::start();

Additionally, you can add middlewares using Router::middleware() and/or set up handlers for 404 and 405 responses using {global.errorPages.CODE} config value.

Alternatively, you can extract the "routes registration part" in its own file and let VELOX know about it using bootstrap/additional.php. Starting from v1.2.0 VELOX does that by default, the file includes/routes/web.php is where you should register your routes. The router will also start automatically if not started explicitly.

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 your 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

VELOX classes are divided in four namespaces:

The following table lists all available classes with their description:

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

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

Functions

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.

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

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

Commands

VELOX comes with some handy commands that you can use to do some repetitive tasks. You can execute these commands using the php bin/{command-name}.

The following table lists all available commands with their description.

You can customize these commands using the config/cli.php file. Here you can enable/disable them or provide different arguments for them.

If you would like to make all these commands accessible via a single interface. Check out my other package Blend, which will do that for you and even more.

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 be placed.
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 get 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, pages, or other partials. 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 (caching for example) 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:

Extending VELOX

To add your 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 your classes. See app/Controller/DefaultController.php, to get an idea.

Here is a list of some important files that you should consider when working with VELOX:

Preloading files/directories autoload/additional.php.
Providing additional data config/data.php.
Registering web routes includes/routes/web.php (starting from v1.2.0).
Registering event handlers includes/events/system.php (starting from v1.2.0).

MVC

Creating a Model:

<?php

namespace App\Model;

use MAKS\Velox\Backend\Model;

class Person extends Model
{
    protected static ?string $table = 'persons';
    protected static ?array $columns = ['id', 'first_name', 'last_name', 'age', ...];
    protected static ?string $primaryKey = 'id';

    public static function schema(): string
    {
        // return SQL to create the table
    }
}

Working with the Model:

<?php

use App\Model\Person;

// creating/manipulating models
$person = new Person(); // set attributes later via setters or public assignment.
$person = new Person(['first_name' => $value, ...]); // set attributes in constructor
$person->get('first_name'); // get an attribute
$person->set('last_name', $value); // set an attribute
$person->getFirstName(); // case will be changed to 'snake_case' automatically.
$person->setLastName($value); // case will be changed to 'snake_case' automatically.
$person->firstName; // case will be changed to 'snake_case' automatically.
$person->lastName = $value; // case will be changed to 'snake_case' automatically.
$attributes = $person->getAttributes(); // returns all attributes.
$person->save(); // persists the model in the database.
$person->update(['first_name' => $value]); // updates the model and save changes in the database.
$person->delete(); // deletes the model from the database.
Person::create($attributes); // creates a new model instance, call save() on the instance to save it in the database.
Person::destroy($id); // destroys a model and deletes it from the database.

// fetching models
$count   = Person::count(); // returns the number of models in the database.
$person  = Person::first();
$person  = Person::last();
$person  = Person::one(['first_name' => 'John']);
$persons = Person::all(['last_name' => 'Doe'], $order, $offset, $limit);
$person  = Person::find($id); // $id is the primary key of the model.
$persons = Person::find('first_name', 'John', 'last_name', 'Doe' ...); // or
$persons = Person::find(['first_name' => 'John', 'last_name' => 'Doe']);
$persons = Person::findByFirstName('John'); // fetches using an attribute, case will be changed to 'snake_case' automatically.
$persons = Person::where('first_name', '=', $value); // fetches using a where clause condition.
$persons = Person::where('last_name', 'LIKE', '%Doe', [['AND', 'age', '>', 27], ...], 'age DESC', $limit, $offset);
$persons = Person::fetch('SELECT * FROM @table WHERE `first_name` = ?', [$value]); // fetch using raw SQL query.

Using the Model in the Controller:

<?php

namespace App\Controller;

use MAKS\Velox\Backend\Controller;
use App\Model\Person;

class PersonsController extends Controller
{
    public function indexAction()
    {
        $persons = Person::all();

        return $this->view->render('persons/index', [
            'title' => 'Persons',
            'persons' => $persons
        ]);
    }

    // other CRUD actions ...

    /**
     * Persons search action.
     *
     * @route("/persons/search", {GET})
     */
    public function searchAction()
    {
        // ...
    }

    /**
     * Persons middleware.
     *
     * @route("/persons/*", {GET, POST})
     */
    public function personsMiddleware()
    {
        // ...
    }
}

Fact: CRUD operations (namely: index, create, store, show, edit, update, destroy) are registered and configured by default. To register your own routes automatically, use the @route("<path>", {<http-verb>, ...}) annotation. See Controller::registerRoutes() DocBlock to learn more.

Fact: To make the model available as property for the controller ($this->model), use Controller::associateModel(). See Controller::associateModel() DocBlock to learn more.

Advice: If in production mode, as a shortcut, throwing an exception with a code matching {global.errorPages.CODE} config value will render the corresponding error page. For example, when throwing new Exception('Not found', 404) form the controller, the configured 404 error page will be rendered and will be passed the exception message. If the page is not configured, the 500 error page will be rendered as a fallback instead.

VELOX does not have any way to validate data. Check out my other package Mighty, which will do that for you and even more.

Using the Model in a View:

{# theme/pages/persons/index.phtml #}

{! @extends 'theme/pages/persons/base' !}

{! @block content !}
    {! @super !}

    <h1>{{ $title }}</h1>

    {! @if (isset($persons) && count($persons)) !}
        <ul>
            {! @foreach ($persons as $person) !}
                <li>{{ $person->firsName }} {{ $person->lastName }}</li>
            {! @endforeach !}
        </ul>
    {! @endif !}
{! @endblock !}

Advice: Check out the Person model and the PersonsController to see a realistic example.

Templating

VELOX comes with its own templating engine. This templating engine is very intuitive and easy to get along with, if you have experience with any other templating engine, learning it would be a matter of minutes. Note that the use of this templating engine is optional. You can simply use raw PHP in your views.

The following table lists all available tags and what they do:

Advice: Take a look at persons views of PersonsController in VELOX theme for a realistic example.

Authentication

Starting from v1.4.0 VELOX comes shipped with a simple built-in authentication system. This system is very simple and easy to use.

<?php

use MAKS\Velox\Backend\Auth;

// instantiate the Auth class
$auth = new Auth(); // or Auth::instance();

// register a new user
$status = $auth->register('username', 'password');

// unregister a user
$status = $auth->unregister('username');

// log in a user
$status = $auth->login('username', 'password');

// log out a user
$auth->logout();

// authenticate a user model
Auth::authenticate($user);

// check if there is a logged in user
$status = Auth::check();

// retrieve the current authenticated user
$user = Auth::user();

// add HTTP basic auth
Auth::basic(['username' => 'password']);

Advice: Check out the UsersController to see a realistic example.

marwanalsoltany / velox

Maintainers

Details