README

A super organized (with a sane folder structure) and very customizable skeleton for Slim Framework v4 with Twig Views. Use it to start working quickly on a new project.

NOTE: If you want this skeleton without Twig, go to: (https://github.com/ricardoper/slim4-skeleton).

This project use PHP Composer for a fast installation without any trouble.

• PHP >= 7.2
• Customizable with an easy configuration:
  • Views
  • Logger
  • Routes
  • Handlers
  • Middlewares
  • Configurations
  • Service Providers
  • Response Emitters
  • Error Handler
  • Shutdown Handler
• Twig Views
• Sessions
• Controllers
• Global Helpers
• PSR-3 for logging
• Environment variables with PHP dotenv
• Pimple as Dependency Injection Container
• ddumper for development (based on Symfony VarDumper)
• Better Error Handlers (HTML, JSON, XML, PlainText - Accept / Content Type)
• Medoo Database Framework (MySQL, PostgreSQL, SQLite, MS SQL Server, ...)

NOTES:

• Medoo is optional and is not enabled by default. You can use another library as a Service Provider. If you want to use this library, don't forget to install the required PDO extensions.

Table of Contents

• How to Install
• Most Relevant Folders
• Global Helpers
  • Development Only
• Configurations
  • Dot Notation
• Routes
• Controllers
  • Helpers
  • Flash Messages Helpers
• Views
  • Helpers
• Middlewares
• Response Emitters
• Models
  • Models Helpers
• Services Providers
• Handlers
• Database Support
• Exceptions
• Logging
• Debugging
• Demo
• Benchmarks

How to Install

Run this command from the directory in which you want to install your new Slim Framework v4 Skeleton with Twig Views.

composer create-project ricardoper/slim4-twig-skeleton [my-app-name]

NOTE:

• Replace [my-app-name]with the desired directory name for your new application.
• Ensure storage/ is web writeable.
• Point your virtual host document root to your new application's public/ directory.

Most Relevant Folders

• /app : Application code (App Namespace - PSR-4)
  • ./Controllers : Accepts input and converts it to commands for the model. Add your Controllers here.
  • ./Emitters : Emits a response, including status line, headers, and the message body, according to the environment. Add your Response Emitters here.
  • ./Handlers : Handles specified behaviors of the application. Add your Handlers here.
  • ./Middlewares : Provide a convenient mechanism for filtering HTTP requests entering your application. Add your Middlewares here.
  • ./Models : Manages the data, logic and rules of the application. Add your Models here.
  • ./Routes : Maps an HTTP request to a request handler (controller). Add your Routes here.
  • ./Services : Define bindings and inject dependencies. Add your Service Providers here.
  • ./Views : Any representation of information such as a chart, diagram or table. Add your Twig Views here
• /configs : Add/modify your Configurations here
• /public : Add your Assets files here

Global Helpers

• env(string $variable, string $default) - Returns environment variables (using DotEnv)
• app() - Returns App instance
• container(string $name) - Returns bindings and inject dependencies from Container
• configs(string $variable, string $default) - Returns Configs data
• base_path(string $path) - Returns base path location
• app_path(string $path) - Returns app path location
• configs_path(string $path) - Returns configs path location
• public_path(string $path) - Returns public path location
• storage_path(string $path) - Returns storage path location

Global Helpers for Development Only

• d($var1, $var2, ...) - Dump vars in collapsed mode by default
• ddd($var1, $var2, ...) - Dump & die vars in collapsed mode by default
• de($var1, $var2, ...) - Dump vars in expanded mode by default
• dde($var1, $var2, ...) - Dump & die vars in expanded mode by default

Configurations

You can add as many configurations files as you want (/configs). These files will be automatically preload and merged in the container based on selected environment.

If you have an environment called "sandbox" and you want to overwrite some configuration only for this environment, you need to create a subfolder "sandbox" in /configs. Something like that /configs/sandbox. Then create the file that includes the configuration that you need to replace and the respective keys and values inside it.

/configs/logger.php

return [

    'name' => 'app',

    'maxFiles' => 7,

];

/configs/local/logger.php

return [

    'name' => 'app-local',

];

Results of name for the environment:

• prod : 'app'
• sandbox : 'app'
• local : 'app-local'
• testing : 'app'

NOTE: You can see the example in this framework for the local environment.

Configurations Dot Notation

You can use dot notation to get values from configurations.

/configs/example.php

return [

    'types' => [
        'mysql' => [
            'host' => 'localhost',
            'port' => '3306',
        ],
        'postgre' => [
            'host' => 'localhost',
            'port' => '3306',
        ],
    ],

];

If you want the host value for MySQL type:

$this->getConfigs('example.types.mysql.host')  => 'localhost'

configs('example.types.mysql.host') => 'localhost'

container('configs')->get('example.types.mysql.host') => 'localhost'

Routes

Maps an HTTP request to a request handler (Closures or Controllers).

You can add as many routes files as you want (/app/Routes), but you need to enable these files in /apps/Routes/app.php file.

You can organize this routes as you like. There is a little Demo that you can see how to organize this files.

use App\Controllers\Demo\AddressesController;
use App\Controllers\Demo\HelloController;
use App\Controllers\Demo\HomeController;
use Slim\App;

/**
 * @var $app App
 */

$app->get('/', [(new HomeController()), 'index']);

$app->get('/flash', [(new HomeController()), 'flash']);

$app->get('/dump', [(new HomeController()), 'dump']);

$app->get('/hello/{name}', [(new HelloController()), 'index'])->setName('namedRoute');

$app->get('/addresses', [(new AddressesController()), 'list']);

$app->get('/addresses/pdo', [(new AddressesController()), 'pdo']);

Controllers

Accepts input and converts it to commands for the Models.

You can add as many Controllers as you want in a cleaning way (/app/Controllers).

After add your Controller, you can enable or disable it in your Routes.

NOTE: To have helpers you must extend the Controllers with ControllerAbstract located in \App\Kernel\Abstracts.

use App\Kernel\Abstracts\ControllerAbstract;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Twig\Error\LoaderError;
use Twig\Error\RuntimeError;
use Twig\Error\SyntaxError;

class HomeController extends ControllerAbstract
{

    /**
     * Index Action
     *
     * @param Request $request
     * @param Response $response
     * @return Response
     * @throws LoaderError
     * @throws RuntimeError
     * @throws SyntaxError
     */
    public function index(Request $request, Response $response): Response
    {
        unset($request, $response);

        return $this->render('Demo/Home/index.twig');
    }

Controllers Helpers

• getApp() - Returns App object
• getContainer(string $name) - Returns the App Container
• getConfigs(string $name) - Returns App Configs
• getService(string $service) - Returns Service Provider from container by name
• getRequest() - Returns HTTP Request
• getResponse() - Returns HTTP Response
• setEmitter(string $name, string $emitter) : Set a new Response Emitter
• getView() - Returns Twig object
• render(string $template, array $data, bool $sendHeaders) - Render Twig view

Flash Messages Helpers

• getFlash() - Return Flash Messages object
• setFlashMessage(string $key, $message) - Set Flash Message
• hasFlashMessage(string $key) - Verify if key of Flash Messages exists
• getFlashMessages(string $key) - Get one or all Flash Messages
• getFlashFirstFMessage(string $key, $default) - Get only the first Flash Messages of key

Views

You can add as many Views as you want in a cleaning way (/app/Views).

You can organize the folder structure as you like, too.

We recommend to use twig extension in your files to have code highlighting.

Views Helpers

• url_for() - returns the URL for a given route. e.g.: /hello/world
• full_url_for() - returns the URL for a given route. e.g.: http://www.example.com/hello/world
• is_current_url() - returns true is the provided route name and parameters are valid for the current path
• current_url() - returns the current path, with or without the query string
• get_uri() - returns the UriInterface object from the incoming ServerRequestInterface object
• base_path() - returns the base path

You can use url_for to generate complete URLs to any Slim application named route and use is_current_url to determine if you need to mark a link as active as shown in this example Twig template:

{% extends "layout.html" %}

{% block body %}
<h1>User List</h1>
<ul>
    <li><a href="{{ url_for('profile', { 'name': 'josh' }) }}" {% if is_current_url('profile', { 'name': 'josh' }) %}class="active"{% endif %}>Josh</a></li>
    <li><a href="{{ url_for('profile', { 'name': 'andrew' }) }}">Andrew</a></li>
</ul>
{% endblock %}

Middlewares

Provide a convenient mechanism for filtering HTTP requests entering your application.

You can add as many Middlewares as you want in a cleaning way (/app/Middlewares).

After add your Middleware, you can enable or disable it in configs/middlewares.php configuration file.

NOTE: Middlewares must respect the MiddlewareInterface located in \Psr\Http\Message.

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Server\MiddlewareInterface as Middleware;
use Psr\Http\Server\RequestHandlerInterface as RequestHandler;

class ExampleMiddleware implements Middleware
{

    /**
     * Process an incoming server request.
     *
     * Processes an incoming server request in order to produce a response.
     * If unable to produce the response itself, it may delegate to the provided
     * request handler to do so.
     *
     * @param Request $request
     * @param RequestHandler $handler
     * @return Response
     */
    public function process(Request $request, RequestHandler $handler): Response
    {
        $response = $handler->handle($request);

        $response = $response->withHeader('X-Example', 'Middleware');

        return $response;
    }
}

Enable it in configs/middlewares.php:

use App\Middlewares\Demo\ExampleMiddleware;

return [

    'example' => ExampleMiddleware::class,

];

Response Emitters

Emits a response, including status line, headers, and the message body, according to the environment.

You can add as many Response Emitters as you want in a cleaning way (/app/Emitters).

After add your Response Emitter, you can enable or disable it globally in configs/emitters.php configuration or you can add it in the Controller for a specific action.

NOTE: Response Emitters must respect the ResponseEmitterInterface located in \App\Kernel\Interfaces.

use App\Kernel\Interfaces\ResponseEmitterInterface;
use Psr\Http\Message\ResponseInterface;

class JsonResponseEmitter implements ResponseEmitterInterface
{

    /**
     * Send the response to the client
     *
     * @param ResponseInterface $response
     * @return ResponseInterface
     */
    public function emit(ResponseInterface $response): ResponseInterface
    {
        $response = $response
            ->withHeader('Content-Type', 'application/json; charset=UTF-8');

        return $response;
    }
}

Enable it in configs/emitters.php:

use App\Emitters\JsonResponseEmitter;

return [

    'json' => JsonResponseEmitter::class,

];

Models

Manages the data, logic and rules of the application.

You can add as many Models as you want in a cleaning way (/app/Models).

After add your Models, you use it for, for example, in a Controller.

NOTE: To have helpers you must extend the Model with ModelAbstract located in \App\Kernel\Abstracts.

use App\Kernel\Abstracts\ModelAbstract;
use PDO;

class AddressesModel extends ModelAbstract
{

    /**
     * Get Last Addresses with Pdo
     *
     * @param int $limit
     * @return array
     */
    public function getLastWithPdo(int $limit = 25): array
    {
        /** @var $db PDO */
        $db = $this->getDb()->pdo;

        $sql = 'SELECT `address`.`address_id`,`address`.`address`,`address`.`address2`,`address`.`district`,`city`.`city`,`address`.`postal_code`,`address`.`phone` FROM `address` ';
        $sql .= 'LEFT JOIN `city` ON `address`.`city_id` = `city`.`city_id` ';
        $sql .= 'ORDER BY `address_id` DESC LIMIT 10';

        return $db->query($sql)->fetchAll(PDO::FETCH_ASSOC);
    }

Models Helpers

• getApp() - Returns App object
• getContainer(string $name) - Returns the App Container
• getConfigs(string $name) - Returns App Configs
• getService(string $service) - Returns Service Provider from container by name
• getRequest() - Returns HTTP Request
• getResponse() - Returns HTTP Response
• getDb() - Returns Database object

Services Providers

Define bindings and inject dependencies.

You can add as many Services Providers as you want in a cleaning way (/app/Services).

After add your Services Provider, you can enable or disable it in configs/services.php configuration file.

NOTE: Service Providers must respect the ServiceProviderInterface located in \App\Kernel\Interfaces.

use App\Kernel\Interfaces\ServiceProviderInterface;
use Pimple\Container;

class ExampleServiceProvider implements ServiceProviderInterface
{

    /**
     * Service register name
     */
    public function name(): string
    {
        return 'example';
    }

    /**
     * Register new service on dependency container
     *
     * @param Container $container
     * @return mixed
     */
    public function register(Container $container)
    {
        return function (Container $c) {
            unset($c);

            return new Example();
        };
    }
}

Enable it in configs/services.php:

use App\Services\Demo\ExampleServiceProvider;

return [

    'example' => ExampleServiceProvider::class,

];

Handlers

Handles specified behaviors of the application.

You can override the following Handlers in a cleaning way (/app/Handlers):

• ErrorHandler (default located in /app/Handlers/ErrorHandler)
• ShutdownHandler (default located in /app/Handlers/ShutdownHandler)

After add your Handler, you can enable or disable it in configs/app.php configuration file.

use App\Handlers\ShutdownHandler;
use Slim\Handlers\ErrorHandler;

return [

    // Handlers //
    'errorHandler' => ErrorHandler::class,

    'shutdownHandler' => ShutdownHandler::class,

Database Support

Medoo is implemented out of box as a Service Provider. The use is optional and is not enabled by default.

To enable database support with Medoo you need to add this library/vendor with Composer:

composer require catfan/medoo

Once installed you need to enable the Service Provider in configs/services.php:

use App\Services\Database\DatabaseServiceProvider;

return [

    'database' => DatabaseServiceProvider::class,

];

Now you are ready to use it...

If you need more details, documentation, api reference, please visit Medoo webpage: https://medoo.in/

NOTES:

• Don't forget to load PDO extensions for your database. For example, if you need MySQL, you need to install pdo_mysql PHP extensions.
• You can use another library as a Service Provider (Native drivers for MySQLi, PostgreSQL, MongoDB, Redis, ...).

Exceptions

You have some Exceptions out the box, located in \App\Kernel\Exceptions, than you can use it:

ConfigsException  - For Configurations Exceptions
ModelException    - For Models Exceptions
ViewException     - For ViewsExceptions

Logging

Logging is enabled by default and you can see all the output in /storage/logs/app-{date}.log.

You can set this parameters in /.env or in /configs/app.php.

LOG_ERRORS |  logErrors  (bool)  - Enable/Disable logging.

LOG_ERRORS_DETAILS  |  logErrorDetails  (bool)  - Enable/disable extra details in the logging file.

LOG_TO_OUTPUT  | logToOutput  (bool)  - `true` to output the logs in console, `false` to output logs in file.

Debugging

Debugging is disabled by default. You can set this parameters in /.env or in /configs/app.php.

APP_DEBUG  |  displayErrorDetails  (bool)  - Enable/disable debugging.

Demo

This skeleton has a little Demo that you can see all this points in action.

Demo URL's:

 /               - Hello World Example.
 /flash          - Redirect with Flash Message.
 /hello/{name}   - Greet User. Replace {name} with your name.
 /addresses      - Database example with Medoo
 /addresses/pdo  - Database example with PDO from Medoo
 /dump           - See the source code of this action.

Benchmarks

Nothing is free, so let's compare the performance loss with Slim Skeleton.

Machine:
Intel® Core™ i5-8400 CPU @ 2.80GHz × 6
16Gb RAM
SSD

Versions:
Ubuntu 20.04 LTS
Docker v19.03.8
nginx 1.17.10
PHP v7.4.3
Zend OPcache enabled
SIEGE 4.0.4

Bench Details:
25 concurrent connections
500 requests per thread
No delays between requests
Command: siege -c25 -b -r500 "URL"

Enjoy the simplicity :oP