Middleware all the things

Image result for middleware psr 15

The middleware pattern is really awesome, you have layers of midlleware classes that take a request and return a reponse, but pass to a handler first, eventually reaching the original callable your request routed to.

My framework Bone MVC makes use of PSR-7 requests, so I’ve been refactoring for v3.0.0 to use league/route and it’s middleware stack, and I’ve just realised a great use case, so I’m about to refactor and create a middleware!

Take a look at this controller action:

/**
* @param ServerRequestInterface $request
* @param array $args
* @return ResponseInterface
* @throws \Doctrine\ORM\EntityNotFoundException
*/
public function viewAction(ServerRequestInterface $request, array $args): ResponseInterface
{
$dragon = $this->service->getRepository()->find($args['id']);
$server = $request->getServerParams();
$hal = [
'_links' => [
'self' => [
'href' => $server['REQUEST_SCHEME'] . '://' . $server['SERVER_NAME'] . '/api/dragon/' . $args['id']
]
],
];
$payload = array_merge($hal, $dragon->toArray());

return new JsonResponse($payload);
}

As well as returning the entity in array format to the JSON response, I’m also creating HAL content negotiation. I was about to do the same for the index listing the collection of entities, when i thought I could simplify my controller by taking HAL stuff out of it!

The middleware signature looks like this:

namespace Psr\Http\Server;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

/**
 * Participant in processing a server request and response.
 *
 * An HTTP middleware component participates in processing an HTTP message:
 * by acting on the request, generating the response, or forwarding the
 * request to a subsequent middleware and possibly acting on its response.
 */
interface MiddlewareInterface
{
    /**
     * 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.
     */
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface;
}

So first up I’ll create my Middleware class and make it do nothing but pass stuff along as it was received

<?php

namespace Bone\Http\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class HalEntity implements MiddlewareInterface
{
    /**
     * @param ServerRequestInterface $request
     * @param RequestHandlerInterface $handler
     * @return ResponseInterface
     */
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        return $handler->handle($request);
    }
}

Then register the middleware on your stack. For myself using league/router, you can add middleware to all routes, groups of routes, or individual routes, which is what I’ll do here:

$route->map('GET', '/dragon/{id:number}', [DragonApiController::class, 'viewAction'])
->middleware(new HalEntity());

A quick check, and yes, the page is still loading as per normal. So now to get the refactoring done!

First we strip out the HAL link stuff and the array merge, and move it to a class impolementing the PSR middleware interface, to make it look like this:

<?php

namespace Bone\Http\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class HalEntity implements MiddlewareInterface
{
/**
* @param ServerRequestInterface $request
* @param RequestHandlerInterface $handler
* @return ResponseInterface
*/
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
$uri = $request->getUri();

$hal = [
'_links' => [
'self' => [
'href' => $uri->getScheme() . '://' . $uri->getHost() . $uri->getPath(),
]
],
];

$response = $handler->handle($request);

$data = \json_decode($response->getBody()->getContents(), true);
$data = \array_merge($hal, $data);

$body = $response->getBody();
$body->rewind();
$body->write(\json_encode($data));

return $response->withBody($body);
}
}

And your controller action will look like this 🙂 :

/**
 * @param ServerRequestInterface $request
 * @param array $args
 * @return ResponseInterface
 * @throws \Doctrine\ORM\EntityNotFoundException
 */
public function viewAction(ServerRequestInterface $request, array $args): ResponseInterface
{
    $dragon = $this->service->getRepository()->find($args['id']);

    return new JsonResponse($dragon->toArray() );
}

Change BIOS time of a VirtualBox VM

Firstly, go here and tweak this script, adding the date you need. Click run. The result displayed is the number of milliseconds that you need to shave off the current bios time.

https://3v4l.org/GYPWE

<?php
// Now
$time = time();
// Date you want
$date = new DateTime('2014-09-18');
$newTime = $date->format('U');
// Copy paste the result into the command below
echo ($time - $newTime) * 1000;

Make sure the box is shut down. Now in your terminal, run these:

VBoxManage setextradata "NAME_OF_VM_HERE" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1
VBoxManage modifyvm "NAME_OF_VM_HERE" --biossystemtimeoffset PASTE_NUMBER_HERE

That’s it! VM is now running in the past.

Bone MVC Framework v3 released

vX.Y.Z – Major.minor.patch – or, BC breaks, features, hotfixes! The best software would be 1.∞.x, as that would mean an absolute tonne of new features have been added, without breaking any backwards compatibility!

Having said all of that, I would now like to present my latest BC break, and announce the release of Bone MVC Framework v3.0 😀

https://bonemvc.delboysplace.co.uk/en_PI

What’s new? Quite a lot. Try it out! We (I) ripped out the old Bone Router and replaced it with league/route, a PSR-15 middleware router based on Fastroute! We replaced Pimple with delboy1978uk/barnacle, a PSR-11 wrapper for Pimple (Pimple has a PSR-11 wrapper but it doesn’t implement the interface correctly and so doesn’t work. Fabien Potencier has went in a huff with the PHP-Fig group so I didn’t bother sending him a Pull Request 😐). Both of these improvements have allowed for a far more flexible and modular approach to site building, as you will see if you try it out!

Ok then, let’s see it in action

The recommended approach is to use Docker, as this means you can get the identical dev enironment that I do, regardless of your operating system. If you don’t wish to take this approach, you can set a virtualhost and database yourself.

Docker VM dev environment setup

To get the Docker VM working, make sure you have Git, VirtualBox (or VMWare), and Docker installed. Once you do, open a terminal window. We need to run a one off command, telling Docker to create a VirtualBox VM which will be your new Docker Machine.

docker-machine create --driver virtualbox default

You now have a Docker Machine. So, the usual process when you would like to begin coding ais as follows:

docker-machine start

Now it’s started, run this for every tab you open in the terminal to set up environment vars in your terminal

eval $(docker-machine env)

Installing Bone MVC Framework

By default, we use a fake domain https://awesome.scot, so sudo nano /etc/hosts and add the following:

awesome.scot 192.168.99.100

Now if you cd into wherever you wish to store the project (~/Sites in my case), we can clone the framework skeleton project:

git clone https://github.com/delboy1978uk/bonemvc
cd bonemvc

Inside the skeleton files, you’ll see a docker-compose.yml, and a build folder. If your’e nosey, have a look and you’ll see how it works! The VM comes with Apache, PHP 7.3, XDebug and a stack of PHP modules, Composer, Mariadb, Mailhog, self signed SSL certificate, and most of the stuff you need. Lets start it up.

docker-compose up

This will take a few minutes the first time you do this, but thereafter should be a lot faster, even with different Bone MVC projects in different folders.

At this point, your terminal is now tailing the logs from each of your services, mail, php, apache, mariadb, and so we need another tab open as we want to log into to the Linux VM to run composer. Remember when you open a new tab, you need to run the eval command again to get the environment variables.

eval $(docker-machine env)
docker-compose exec php /bin/bash

At this point, you’ll notice a slight change in your shell’s look. We are now logged into the server! Lets install the dependencies and we are ready to rock!

eval $(docker-machine env)
docker-compose exec php /bin/bash
composer install

Once composer is finished doing it’s thing, we are ready to browse to the project! Open https://awesome.scot in your browser, and you should see the following!

Okay great, so how is it all structured?

As per most projects these days, the main entrypoint is public/index.php, and all public assets are installed in public/. Bone use the environment variable APPLICATION_ENV to differentiate between your dev setup and staging, production, etc.

The build folder is part of the Docker setup as mentioned earlier, so can be ignored.

The config folder allows for subfolders based on the APPLICATION_ENV, which will override the config files sitting directly under config/. You can add as many .php files into these folders that you like.

The data folder containsa variety of things. There is a cache storage folder (delboy/bone-cache coming soon), a logs folder (delboy1978uk/bone-log coming soon), a proxies folder (for doctrine entity proxies if using delboy1978uk/bone-doctrine), a translations folder with several languages pre-configured (use poedit to edit these files), and an uploads folder.

The migrations folder is use to store database migrations if using delboy1978uk/bone-doctrine.

The src/ folder contains your applications modules, and currently only contains one module, App.

Inside src/App, you will see a class called AppPackage.php, look inside!

All packages implement RegistrationInterface, and any packages containing controller routes will also implement RouterConfigInterface. addToContainer() allows you to create object factories so you can inject any dependencies. In the AppPackage, the Controller requires the view engine so it can render pages, so we create a controller factory and pull the view from the container (view is set up automatically by Bone):

    /**
     * @param Container $c
     */
    public function addToContainer(Container $c)
    {
        $c[IndexController::class] = $c->factory(function (Container $c) {
            $view = $c->get(PlatesEngine::class);
            return new IndexController($view);
        });
    }

The addRoutes() method tells the router which actions in which controller to call.

    /**
     * @param Container $c
     * @param Router $router
     * @return Router
     */
    public function addRoutes(Container $c, Router $router): Router
    {
        $router->map('GET', '/', [IndexController::class, 'indexAction']);
        $router->map('GET', '/learn', [IndexController::class, 'learnAction']);

        return $router;
    }

If you have Doctrine entities, return true in the hasEntityPath() method, and return the path to the Entity folder in the getEntityPath() method.

Controllers now just take in a PSR-7 request, and return a PSR-7 Response. However we can wrap the request and response in middleware! See league/route docs for more info.

For a bit of fun, I’ll show you a module with a Doctrine entity, and just how quickly you can add a new feature! In the VM CLI, type the following:

composer require delboy1978uk/bone-doctrine
composer require delboy1978uk/bone-gentest

You now have the doctrine and my test entity package in the vendor folder.

Open config/packages.php, and add the two packages.

<?php

use BoneMvc\Module\App\AppPackage;
use BoneMvc\Module\BoneMvcDoctrine\BoneMvcDoctrinePackage;
use Random\Developer\JediPackage;

return [
    'packages' => [
        AppPackage::class,
        BoneMvcDoctrinePackage::class,
        JediPackage::class,
    ],
    'viewFolder' => 'src/App/View'
];

Ok, so we have entities need migrated to the database. In the VM CLI, type the following:

migrant diff
migrant migrate

You’ll notice that migrant is just Doctrine migrations, but tweaked for usage with Bone MVC. Now you have migrated, head over to https://awesome.scot/jedi

You now have a demo module with an index list page, add edit and delete functionality, with form filtering and validation and rendering done via delboy1978uk/form. Have a look through the module code to see how to set everything up!

Please play around and have fun with it, and feel free to leave any comments!

Hack an apt-get style installer into Cygwin

As you’ll probably know, you can install a bunch of plugins into Cygwin, but only during installation. Do the following to make life easier for yourself.

After installation, copy the setup executable into the cygwin folder.

Create install-pkg.bat with the following contents:

setup-x86_64.exe --no-desktop --no-shortcuts --no-startmenu --quiet-mode --root "%cd%" --packages %*

Now you can cd into /cygdrive/c/cygwin64 and install a package like so:

$ ./install-pkg.bat wget 

Ready to rock PHP 7.3 Docker LAMP Stack

I have built a full LAMP stack that comes with the following:

  • Apache
  • PHP 7.3.3
  • Mariadb
  • MailHog
  • XDebug
  • HTTPS Virtualhost with holding page

Here’s how you get a full LAMP stack up and running in no time at all, which will be identical on any platform.

Firstly, install Docker and Virtualbox if you don’t have them. Then create a default base VM.

https://www.docker.com/community-edition

https://www.virtualbox.org/

docker-machine create --driver virtualbox default

OK. So, first thing you need to do is start your VM:

docker-machine start
docker-machine env
eval $(docker-machine env)

You should run eval $(docker-machine env) in any other terminal tabs you open too, this sets up environment vars for setting up docker. Take a note of that IP address, and edit your /etc/hosts file

192.168.99.100 awesome.scot

Ok, lets clone the LAMP stack:

git clone https://github.com/delboy1978uk/lamp
cd lamp

This is another one off, build the image.

docker-compose build

That’s it! Now start your docker image like this

docker-compose up

and you can finally open your browser to

https://awesome.scot