PHP with a cup of coffee

2.1.1 2019-07-19 02:22 UTC

README

PHP with a cup of coffee

Travis (.org) Codacy branch coverage Codacy grade Packagist Version PHP from Packagist GitHub code size in bytes GitHub last commit GitHub issues

Introduction

Espresso is an HTTP micro framework for your web application built with PHP. It is heavily inspired in Node's Express.

We aim to make PHP development as simple as writing a Node Js app, while using PHP awesome object oriented features, the best patterns and the FIG standards for maximum interoperability.

To know more about middleware, PSR-7 and related things, check this awesome blog by Matthew Weier O'Phinney, project lead of Zend Framework (now Laminas Project).

Installation

To install Espresso, simply run:

composer require espresso/app

Or, if you prefer an skeleton project with some directory structure you can use:

composer create-project espresso/skeleton <folder>

Please refer to the skeleton documentation to know how to use it.

NOTE: Espresso is an HTTP framework that comes with some tooling out of the box to make your life easier. If you don't need all that tooling, you might be fine just by using espresso/http-module, which is the base class for Espresso.

Usage

Check the examples folder to quickly see how to use Espresso. The api is really similar to the one of Express JS.

Creating a Espresso instance

First, you need to create the espresso instance. It takes two arguments.

  1. A callable that must return an instance of PSR-7 ServerRequestInterface.
  2. A callable that must emit an instance of PSR-7 ResponseInterface.

In Espresso, we recommend using Zend Diactoros as an HTTP abstraction, and HTTP Interop Response Sender as a response sender function.

To install them both just run:

composer require zendframework/zend-diactoros http-interop/response-sender

Then, to create an Espresso app using those:

<?php

$app = \Espresso\App\Espresso::create();

Then, the application is ready to be configured. When you are done configuring it, you can run it using the $app->run() method.

Using a DI Container

Espresso allows you to use an instance of PSR-11 ContainerInterface. This can be done by injecting the container into the app instance with the $app->setContainer() method or at the moment of creation using the Espresso::create() method. This container will be used for service resolution on arguments that are strings and match a service name.

We recommend the excellent league/container. All Espresso packages come with a preconfigured Service Provider for that container implementation.

Using Middleware

Espresso can use any sort of PSR-15 Middleware in it's execution chain.

You can register middleware with the $app->use() method. This method takes any number of arguments that can be either:

  • An instance of PSR-15 middleware
  • An instance of PSR-15 request handler (it will be decorated to a middleware instance)
  • A callable with PSR-15 middleware signature (it will be decorated to a middleware instance)
  • A string containing a service name (that will be resolved from the container and lazy loaded)

Registering Routes

Espresso is very flexible and lightweight. It does not need a routing/dispatching middleware, nor a route collector or anything else in order to work. Routes are middleware themselves and they can be manually prepended to a path in order to compose Http Modules that share common functionality.

Espresso provides convenient methods to register routes. These are the standard:

  • get
  • post
  • put
  • patch
  • delete
  • any

Each of these takes two arguments:

  • A string defining the path of the route (Ex: /users/:id)
  • An indefinite number of handlers

These handlers can be either:

  • An instance of PSR-15 middleware
  • An instance of PSR-15 request handler (it will be decorated to a middleware instance)
  • A callable with PSR-15 middleware signature (it will be decorated to a middleware instance)
  • A string containing a service name (that will be resolved from the container and lazy loaded)

Registering Modules

Espresso has a very flexible module system based on simple callables where you can configure an instance of HttpModule. This module can be routed and has middleware of its own. Think of it as almost another instance of the Espresso app. They can be prepended with a as well, and every route inside of it will be relative to that path.

This is an example of configuration of a users module:

<?php

use Espresso\HttpModule\HttpModule;

// First you create the module.
$module = $app->module(static function (HttpModule $module) {  
    $module->get('/', 'list-users'); // Since this is a string, it will be resolved by the container
    $module->get('/:id', 'show-user');
    $module->post('/', 'create-user');
    $module->put('/:id', 'update-user');
    $module->delete('/:id', 'delete-user');
});

// Second, you inject it in the app.
$app->use('/users', $module);

The cool thing about this, is that we can create configurable Http Modules in callable classes. These classes will configure themselves, easing the module creation process. In fact, Espresso official modules are composed like that.

Bundled HTTP Plugins

Espresso has libraries containing common plugins for different tasks. If you need special functionality like CORS, Proxy Trust, Cookies and the like, Espresso provides methods to add them.

Body Parser

You can parse the body of a request and make it available via ServerRequestInterface::getParsedBody(). register body parser using:

<?php
$app->parseBody('json', 'form');

Session

You can uniquely identify a client using encrypted sessions stored on the client side. You can enable this feature using:

NOTE: The secret key must be 32 bytes long. If not, session encryption will fail.

<?php
$app->session('<secret-key-here>');

Proxies

NOTE: Not yet implemented

<?php
$app->trustProxy('ip/range');