Alight

Alight is a light-weight PHP framework. Easily and quickly build high performance RESTful web applications. Out-of-the-box built-in routing, database, caching, error handling, logging and job scheduling libraries. Focus on creating solutions for the core process of web applications. Keep simple and extensible.

Alight Family

| Project | Description | | ----------------------------------------------------------- | --------------------------------------------------------------------------------- | | Alight | Basic framework built-in routing, database, caching, etc. | | Alight-Admin | A full admin panel extension based on Alight. No front-end coding required. | | Alight-Project | A template for beginner to easily create web applications by Alight/Alight-Admin. |

Requirements

PHP 7.4+

Getting Started

• Installation
• Configuration
• Routing
• Database
• Caching
• Error Handling
• Job Scheduling
• Helpers

Installation

Step 1: Install Composer

Don’t have Composer? Install Composer first.

Step 2: Creating Project

Using template with create-project

$ composer create-project juneszh/alight-project {PROJECT_DIRECTORY}

The project template contains common folder structure, suitable for MVC pattern, please refer to: Alight-Project.

It is easy to customize folders by modifying the configuration. But the following tutorials are based on the template configuration.

Step 3: Configuring a Web Server

Nginx example (Nginx 1.17.10, PHP 7.4.3, Ubuntu 20.04.3):

server {
    listen 80;
    listen [::]:80;

    root /var/www/{PROJECT_DIRECTORY}/public;

    index index.php;

    server_name {YOUR_DOMAIN};

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
    }
}

Configuration

All of the configuration options for the Alight framework will be imported from the file 'config/app.php', which you need to create yourself. For example:

File: config/app.php

<?php

return [
    'app' => [
        'debug' => false,
        'timezone' => 'Europe/Kiev',
        'storagePath' => 'storage',
        'domainLevel' => 2,
        'corsHeaders' => null,
        'corsMethods' => null,
        'cacheAdapter' => null,
        'errorHandler' => null,
        'errorPageHandler' => null,
    ],
    'route' => 'config/route/web.php',
    'database' => [
        'type' => 'mysql',
        'host' => '127.0.0.1',
        'database' => 'alight',
        'username' => 'root',
        'password' => '',
    ],
    'cache' => [
        'type' => 'file',
    ],
    'job' => 'config/job.php',
];

Get some items in the config

<?php

Alight\Config::get('app');
Alight\Config::get('app', 'storagePath');

Available Configuration

See Config.php for details.

Routing

Before learning routing rules, you need to create a php file first that stores routing rules. Because the routing cache is updated or not, it is based on the modification time of the routing file. For example:

File: config/route/web.php

Alight\Route::get('/', 'Controller::index');

File: config/app.php

<?php

return [
    'route' => 'config/route/web.php'
    // Also supports multiple files
    // 'route' => ['config/route/web.php', config/route/api.php'] 
];

By the way, the route configuration supports importing specified files for subdomains:

<?php

return [
    'route' => [
        //Import on any request
        '*' => 'config/route/web.php', 
        //Import when requesting admin.yourdomain.com
        'admin' => 'config/route/admin.php', 
        //Import multiple files when requesting api.yourdomain.com
        'api' => ['config/route/api.php', 'config/route/api_mobile.php'], 
    ]
];

Basic Usage

Alight\Route::get($pattern, $handler);
// Example
Alight\Route::get('/', 'Controller::index');
Alight\Route::get('/', ['Controller', 'index']);
// Or try this to easy trigger hints from IDE
Alight\Route::get('/', [Controller::class, 'index']);
// With default args
Alight\Route::get('post/list[/{page}]', [Controller::class, 'list'], ['page' => 1]);

// Common HTTP request methods
Alight\Route::options('/', 'handler');
Alight\Route::head('/', 'handler');
Alight\Route::post('/', 'handler');
Alight\Route::delete('/', 'handler');
Alight\Route::put('/', 'handler');
Alight\Route::patch('/', 'handler');

// Map for Custom methods
Alight\Route::map(['GET', 'POST'], 'test', 'handler');

// Any for all common methods
Alight\Route::any('test', 'handler');

Regular Expressions

// Matches /user/42, but not /user/xyz
Alight\Route::get('user/{id:\d+}', 'handler');

// Matches /user/foobar, but not /user/foo/bar
Alight\Route::get('user/{name}', 'handler');

// Matches /user/foo/bar as well, using wildcards
Alight\Route::get('user/{name:.+}', 'handler');

// The /{name} suffix is optional
Alight\Route::get('user[/{name}]', 'handler');

// Root wildcards for single page app
Alight\Route::get('/{path:.*}', 'handler');

nikic/fast-route handles all regular expressions in the routing path. See FastRoute Usage for details.

Options

Group

Alight\Route::group('admin');
// Matches /admin/role/list
Alight\Route::get('role/list', 'handler');
// Matches /admin/role/info
Alight\Route::get('role/info', 'handler');

// Override the group
Alight\Route::group('api');
// Matches /api/news/list
Alight\Route::get('news/list', 'handler');

Customize 'any'

You can customize the methods contained in Alight\Route::any().

Alight\Route::setAnyMethods(['GET', 'POST']);
Alight\Route::any('only/get/and/post', 'handler');

Disable route caching

Not recommended, but if your code requires:

// Effective in the current route file
Alight\Route::disableCache();

Life cycle

All routing options only take effect in the current file and will be auto reset by Alight\Route::init() before the next file is imported. For example:

File: config/admin.php

Alight\Route::group('admin');
Alight\Route::setAnyMethods(['GET', 'POST']);

// Matches '/admin/login' by methods 'GET', 'POST'
Alight\Route::any('login', 'handler');

File: config/web.php

// Matches '/login' by methods 'GET', 'POST', 'PUT', 'DELETE', etc
Alight\Route::any('login', 'handler');

Utilities

Cache-Control header

Send a Cache-Control header to control caching in browsers and shared caches (CDN) in order to optimize the speed of access to unmodified data.

// Cache one day
Alight\Route::get('about/us', 'handler')->cache(86400);
// Or force disable cache
Alight\Route::put('user/info', 'handler')->cache(0);

Handling user authorization

We provide a simple authorization handler to manage user login status.

// Define a global authorization verification handler
Alight\Route::authHandler([\svc\Auth::class, 'verify']);

// Enable verification in routes
Alight\Route::get('user/info', 'handler')->auth();
Alight\Route::get('user/password', 'handler')->auth();

// No verification by default
Alight\Route::get('about/us', 'handler');

// In general, routing with authorization will not use browser cache
// So auth() has built-in cache(0) to force disable cache
// Please add cache(n) after auth() to override the configuration if you need
Alight\Route::get('user/rank/list', 'handler')->auth()->cache(3600);

File: app/service/Auth.php

namespace svc;

class Auth
{
    public static function verify()
    {
        // Some codes about get user session from cookie or anywhere
        // Returns the user id if authorization is valid
        // Otherwise returns 0 or something else for failure
        // Then use Router::getAuthId() in the route handler to get this id again
        return $userId;
    }
}

Request cooldown

Many times the data submitted by the user takes time to process, and we don't want to receive the same data before it's processed. So we need to set the request cooldown time. The user will receive a 429 error when requesting again within the cooldown.

// Cooldown only takes effect when authorized
Alight\Route::put('user/info', 'handler')->auth()->cd(2);
Alight\Route::post('user/status', 'handler')->auth()->cd(2);

Cross-Origin Resource Sharing (CORS)

When your API needs to be used for Ajax requests by a third-party website (or your project has multiple domains), you need to send a set of CORS headers. For specific reasons, please refer to: Mozilla docs.

// The specified domain will receive the common cors header
Alight\Route::put('share/specified', 'handler')->cors('abc.com');
Alight\Route::put('share/config', 'handler')->cors(['abc.com', 'def.com']); 

// The specified domain will receive the specified cors header
Alight\Route::put('share/specified2', 'handler')->cors('abc.com', 'Authorization', ['GET', 'POST']);

// All domains will receive a 'Access-Control-Allow-Origin: *' header
Alight\Route::put('share/all/http', 'handler')->cors('*'); 

// All domains will receive a 'Access-Control-Allow-Origin: [From Origin]' header
Alight\Route::put('share/all/https', 'handler')->cors('origin');

*If your website is using CDN, please use this utility carefully. To avoid request failure after the header is cached