manhim/cervo

This package is abandoned and no longer maintained. The author suggests using the nevraxe/cervo package instead.

A lightweight and highly modular structure framework for PHP.

4.0.0 2017-10-28 17:42 UTC

README

Scrutinizer Code Quality

About Cervo

A lightweight and highly modular structure framework for PHP.

Requirements

Requires PHP 7.1.0.

Versioning

Version model: (MAJOR).(MINOR).(PATCH)

  • MAJOR version when we make incompatible API changes,
  • MINOR version when we add functionality in a backwards-compatible manner, and
  • PATCH version when we make backwards-compatible bug fixes.

Installing

Using composer

"require": {
    "nevraxe/cervo": "4.0.*"
}

How to get started

Preamble

There is a lot of possible configurations for Cervo, but this guide assumes that you are using defaults.

Initializing Cervo

First you need to create your index.php file. It's purpuse is to load your composer dependencies (which includes Cervo), to configure Cervo and then to initialize it.

<?php


// An util that is used throughout Cervo (Not required)
if (!defined('DS'))
    define('DS', DIRECTORY_SEPARATOR);


// Include the composer vendor files
require 'vendor/autoload.php';


// We get the Config Cervo library
$config = \Cervo\Core::getLibrary('Cervo/Config');

// This configuration is required. It can be set either here, or in the config.json file directly.
$config->set('Cervo/Application/Directory', realpath(__DIR__ . '/Application') . \DS);


// We initialize Cervo and load config.json.
\Cervo\Core::init(__DIR__ . '/config.json');

By default, a config.json file is not required unless you want to specify the application directory path in it or want to set Production to true in order for Cervo to cache the routing information.

The folder structure

The application folder needs to contains modules which are simply sub-folders of it's directory.

Inside a module you may have the Controllers, Libraries, Templates and Views directories as well as the Router.php file.

Any folders fully support the PSR-4 standard, so you can create Application/My/Classes/MyClass.php and it will be autoloaded.

Application/
 -> My/
   -> Controllers/
   -> Libraries/
   -> Templates/
   -> Views/
   -> Router.php

Creating a Controller

Checklist

  • In a controller, you have to set your namespace to Application/MyModule/Controllers. As you can notice, the Module suffix needs to be added for modules.
  • The filename requires to be exactly the same as the class name (With correct case).
  • The class requires to extend the \Cervo\Controller class or a derivative.
  • The end-point methods may have an $args and a $params parameters to receive the arguments from the Router calls and the parameters set in the route.
<?php
// Application/My/Controllers/My.php

namespace Application\MyModule\Controllers;

use Cervo\Controller;
use Cervo\Core as _;

class My extends Controller
{
    public function Index($args = [], $params = [])
    {
        // We process the user input
        $value = $args[0];
        
        if (strlen($value) == 0) {
            if (strlen($params['default']) > 0) {
                $value = $params['default'];
             } else {
                $value = 'My default value';
             }
        }
        
        $value = _::getLibrary('My')->sanitize($value);
    
        // Then we go through rendering logic
    }
}

The controllers methods purpose are to serve as an end-point for the router. You should include the data input processing in it.

Creating a Template

The template file is where you put your HTML and consume the variables for display.

The template wrapper has a magic __get() method that you can use to get the assigned parameters.

There is no specific recommendations on what to pass to a template, it may be only strings and booleans, objects with getters or anything of your preference.

<html>
<head>
    <title>My application</title>
</head>
<body>
    <?php if ($this->ShowHelloWorld): ?>
        <p>Hello world!</p>
    <?php endif; ?>
    <p><?=$this->Value?></p>
</body>
</html>

Creating a Library

Checklist

  • In a library, you have to set your namespace to Application/MyModule/Libraries.
  • The filename requires to be exactly the same as the class name (With correct case).

A library is simply a singleton class that contains code that is re-used. The Cervo getLibrary() function handles the singleton part, so you can use your class directly in your tests.

<?php
// Application/My/Libraries/My.php

namespace Application\MyModule\Libraries;

use Cervo\Libraries\Router;
use Cervo\Core as _;

class My
{
    public function sanitize($input)
    {
        // Sanitize $input...
        return $input;
    }
    
    public function verify(Router $router)
    {
        if (_::getLibrary('Users')->getCurrentUser() === null) {
            // Returning false will prevent the controller to be called.
            return false;
        }
        
        return true;
    }
}

The Router.php file

The Router.php file in your module's root is loaded automatically by Cervo's Router. It is included from within the Router's object so you can use it's methods.

<?php
// Application/My/Router.php

use Cervo\Libraries\Router;

return function (Router $router) {

    // The first parameter is the HTTP method or CLI. You may use an array to define multiple.
    // The second one is the path. It supports the nikic/FastRoute default notation.
    // The third parameter is the Module/Controller/Method, you can use a controller that is in a sub-folder, so you could load it like Module/SubFolder/Controller/Method.
    // The sub-folder structure supports infinite dept: Module/SubFolder/AnotherSubFolder/YetAnotherSubFoler/Controller/Method
    $router->addRoute('GET', '/', 'Test/Test/Test');
    $router->addRoute('GET', '/test/{name}', 'Test/Test/Named');
    
    // The middleware is an array in the format ['MyModule/MyLibrary', 'Method']. The first part is the equivalent of doing \Cervo\Core::getLibrary() and the second part is the method called.
    // You can add an array as the fourth parameter, those informations will be passed to the controller/method as second parameter.
    // Any data that you put in each routes needs to be serializable in order to be cached.
    $router->middleware('My', 'verify', function (Router $router) {
        $router->addRoute('GET', '/admin/test/{name}', 'Test/Admin/Test/Named', ['param' => 'test']);
    });
    
};

Production

If you set the configuration option Production to true, the Router will automatically create a cache file named router.cache.php at the root of your Application folder.

You will have to delete this file if you make changes to your routes.