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

Directory	Description
`bootstrap`	This is where VELOX bootstraps the application. You normally don't have to change anything in this directory, unless you want to extend VELOX functionality beyond basic stuff.
`bin`	This is where PHP executables are placed. You can freely add yours, or delete the entire directory.
`app`	This is where your own backend logic will be placed. You will be mostly working here for the backend part of your app.
`classes`	This is where VELOX source files live. You shouldn't be touching anything here unless you want to make your own version of VELOX.
`functions`	This is where all functions that are loaded in the application live. You can freely add yours, or delete the entire directory.
`includes`	This is where all files that should be preloaded will be placed. You can freely add yours, or delete the entire directory.
`themes`	This is where all your frontend themes will be placed. You will be mostly working here for the frontend part of your app.
`config`	This is where all config files will live. All files here will be accessible using the `Config` class at runtime.
`storage`	This is where VELOX will write caches and logs. You can also use this directory to store installation-wide assets.
`public`	This is where you should put your `index.php` with a symlink for static assets (active theme `assets/` directory for example) for maximum security. You can freely delete this directory if you want to.
`vendor`	This is where your Composer dependencies will be placed. You can freely delete this directory if you don't want to use Composer.

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.

Config File	Description
`global.php`	This config file contains some global variables that are used by almost all classes (app-wide config).
`router.php`	This config file can be used to override `Router::class` default parameters.
`session.php`	This config file contains session configuration, it is used by the `Session::class`.
`database.php`	This config file contains database credentials, it is used by the `Database::class`.
`auth.php`	This config file contains authentication configuration, it is used by the `Auth::class`.
`theme.php`	This config file can be used to edit/extend theme configuration.
`view.php`	This config file can be used to customize everything about the views. It is used by the `View::class`.
`data.php`	This config file can be used to provide any arbitrary data, which then will get injected in the `Data::class`.
`cli.php`	This config file can be used to enable/disable the commands or change their arguments.

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:

Class	Description
`Velox\App`	A class that serves as a basic service-container for VELOX.

`Backend\Event`	A class that offers simple events handling functionality (dispatching and listening).
`Backend\Config`	A class that loads everything from the `/config` directory and make it as an array that is accessible via dot-notation.
`Backend\Router`	A class that serves as a router and an entry point for the application.
`Backend\Globals`	A class that serves as an abstraction/wrapper to work with superglobals.
`Backend\Session`	A class that offers a simple interface to work with sessions.
`Backend\Controller`	An abstract class that serves as a base Controller that can be extended to make handlers for the router.
`Backend\Database`	A class that represents the database and handles database operations.
`Backend\Model`	An abstract class that serves as a base model that can be extended to create custom models.
`Backend\Auth`	A class that serves as an authentication system for users.

`Frontend\Data`	A class that serves as an abstracted data bag/store that is accessible via dot-notation.
`Frontend\View`	A class that renders view files (Layouts, Pages, and Partials) with the ability to include additional files, divide page content into sections and cache rendered views.
`Frontend\HTML`	A class that serves as a fluent interface to write HTML in PHP. It also helps with creating HTML elements on the fly.
`Frontend\Path`	A class that serves as a path resolver for different paths/URLs of the app.

`Helper\Dumper`	A class that dumps variables and exception in a nice formatting.
`Helper\Misc`	A class that serves as a holder for various miscellaneous utility function.

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:

Class/Group	Function(s)
`App::class`	`app()`, `abort()`, `terminate()`
`Event::class`	`event()`
`Config::class`	`config()`
`Router::class`	`router()`, `handle()`, `redirect()`, `forward()`
`Database::class`	`database()`
`Globals::class`	`globals()`
`Session::class`	`session()`, `flash()`, `csrf()`
`Auth::class`	`auth()`
`View::class`	`view()`, `render()`, `render_layout()`, `render_page()`, `render_partial()`, `section_push()`, `section_reset()`, `section_start()`, `section_end()`, `section_yield()`, `include_file()`
`Data::class`	`data()`, `data_has()`, `data_get()`, `data_set()`
`HTML::class`	`html()`
`Path::class`	`path()`, `app_path_current()`, `app_url_current()`, `app_path()`, `app_url()`, `theme_path()`, `theme_url()`, `assets_path()`, `assets_url()`
`Dumper::class`	`dd()`, `dump()`, `dump_exception()`
HTML Helpers	`he()`, `hd()`, `hse()`, `hsd()`, `st()`, `nb()`

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.

Command	Description
`app-serve`	This command starts a development server.
`app-mirror`	This command mirrors the application in the `/public` directory.
`config-cache`	This command caches the current configuration.
`config-dump`	This command dumps the current configuration with syntax highlighting.
`cache-clear`	This command clears caches.

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:

Tag	Description
`{! @extends 'path/to/template' !}`	Extend a template, blocks of this template will be inherited.
`{! @include 'path/to/file' !}`	Include a file, this will get rendered before inclusion (can't access context variables).
`{! @embed 'path/to/file' !}`	Embed a file, this will be included as is (can access context variables).
`{! @block name !}` `{! @endblock !}`	Create a block to wrap some code.
`{! @super !}`	Use it inside a block in an extended template to inherit parent block content.
`{! @block(name) !}`	Print a block. Needs to be called at least once in order to render a block.
`{! @foreach ($vars as $var) !}` `{! @endforeach !}`	Control structures (loops, if statements, ...). All PHP control structures are available (`if`, `else`, `elseif`, `do`, `while`, `for`, `foreach`, `continue`, `switch`, `break`, `return`, `require`, `include`) with the same syntax but simply prefixed with an `@` symbol if a control structure is the first word in the tag.
`{! $var = '' !}`	Variable assignments. Content can be a variable or any valid PHP expression.
`{{ $var }}`	Print a variable. Content can be a variable or any PHP expression that can be casted to a string.
`{{{ $var }}}`	Print a variable without escaping. Content can be a variable or any PHP expression that can be casted to a string.
`{# This is a comment #}`	Comment something. This will be a PHP comment (will not be available in final HTML).

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

VELOX

Key Features

Installation

Using Composer:

Using Git:

Using Source:

About VELOX

Why does VELOX exist?

Architecture

Directory structure

App Entry

Config

Classes

Functions

Commands

Themes

Examples:

Extending VELOX

MVC

Creating a Model:

Working with the Model:

Using the Model in the Controller:

Using the Model in a View:

Templating

Authentication

License

About

Releases 31

Sponsor this project

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 571 Commits
.github		.github
app		app
bin		bin
bootstrap		bootstrap
classes		classes
config		config
functions		functions
includes		includes
public		public
storage		storage
tests		tests
themes		themes
vendor		vendor
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.htaccess.dist		.htaccess.dist
.scrutinizer.yml		.scrutinizer.yml
.styleci.yml		.styleci.yml
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
index.php		index.php
phpdoc.xml.dist		phpdoc.xml.dist
phpunit.xml.dist		phpunit.xml.dist

License

MarwanAlsoltany/velox

Folders and files

Latest commit

History

Repository files navigation

VELOX

Key Features

Installation

Using Composer:

Using Git:

Using Source:

About VELOX

Why does VELOX exist?

Architecture

Directory structure

App Entry

Config

Classes

Functions

Commands

Themes

Examples:

Extending VELOX

MVC

Creating a Model:

Working with the Model:

Using the Model in the Controller:

Using the Model in a View:

Templating

Authentication

License

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 31

Sponsor this project

Languages