An Overview of Fortissimo Commons

Fortissimo is a chain of command (CoCo) framework written in PHP. Its main goal is to enable developers to write highly re-usable component-based web applications. Recently we added a new GitHub project, Fortissimo Commons, to hold dozens of utilities that we use over and over again with Fortissimo.

In this post I give an overview of these commands.

First Things First: Using Fortissimo-Commons

Just like the rest of the Masterminds PHP projects, Fortissimo-Commons is installed via Composer. Just add these lines to your composer.json:

"require": {
  "masterminds/fortissimo": "dev-master",
  "masterminds/fortissimo-commons": "dev-master",
},

The first includes Fortissimo itself, and the second includes Fortissimo-Commons.

As a general reminder, a Fortissimo chain of command looks something like this:

$registry->route('@JSONerror')
    ->usesGroup("bootstrap")
    ->does('\Fortissimo\Commons\HTTP\AddHeaders', '_set_headers')
      ->using('code', 500)
    ->does('\Fortissimo\Commons\Arrays\Build', 'json')
      ->using('error', 'An error occurred')->from('cxt:errorTitle')
      ->using('message', 'An error occurred')->from('cxt:errorMessage')
    ->does('\Fortissimo\Commons\JSON\EchoJSON')
      ->using('object', array('error' => 'No data'))->from('cxt:json')

(The above is a real route from an app in production. It sends JSON errors to a jQuery client.)

Arrays

There are a few utilities for working with arrays. In general, they make it easy to extract context data into arrays or to put an array's contents into context.

Fortissimo\Commons\Arrays\Build

Take values out of your context and put them into an array.

Example:

$registry->does('foo')
    ->does('Fortissimo\Commons\Arrays\Build', 'a')
        ->using('foo', 'bar')
        ->using('name')->from('get:user')
;

The example above will put an array named a into the context. Assuming that $_GET['user'] is matt the array will look like this:

array(
  'foo' => 'bar,
  'name' => 'matt'
);

Fortissimo\Commons\Arrays\Extract

Extract does the opposite of Build: It takes an associative array and merges it into the context. This is a convenient way to put existing data into the context.

Formatting

Fortissimo\Commons\Format\Sprintf

As the name implies, this provides a print formatter at the command level:

$registry->does('foo')
    ->does('Fortissimo\Commons\Format\Sprintf', 'a')
        ->using('format', 'My name is %s')
        ->using('1')->from('get:user')
;

Assuming $_GET['user'] is matt, the above will put a into the context with the value My name is matt. Note that for the formatter, arguments are 1-indexed integers: 1 replaces the first % var, 2 replaces the second, and so on.

HTTP

Fortissimo is written for web applications, and this part of Commons has some of the utility commands that we often need for web apps.

Fortissimo\Commons\HTTP\AddHeaders

Add arbitrary HTTP headers. This is very useful for setting content types and other standard HTTP headers.

Fortissimo\Commons\HTTP\CreateURL

This utility function provides a standard way to build a URL from a relative path. It uses information from $_SERVER to piece together a full URL without you needing to configure anything.

There's an example of this command in the Redirect section below.

Fortissimo\Commons\HTTP\ExternalCacheHeaders

This command adds cache control headers that external caches and reverse proxies use. It's great for working with Akamai, Squid, and Varnish.

Fortissimo\Commons\HTTP\ForceSSL

With this command you can force clients who connect over HTTP to redirect to the HTTPS (secure) version of the site.

Fortissimo\Commons\HTTP\Redirect

This provides convenient access to the HTTP 3xx family of redirects. It differs from Fortissimo's internal Reroute facility in that this returns an HTTP message to the client, and the client must then make a new request for the correct URL.

$registry->does('foo')
    ->does('Fortissimo\Commons\HTTP\Redirect', 'a')
        ->using('redirect_type', 301)
        ->using('url', 'http://technosophos.com')
;

The above will cause any browswer that accesses foo to be permanently redirected to http://technosophos.com. The HTTP spec requires that url is an absolute URL (domain and protocol included). Since building the url is easy with the CreateURL command above, the two could be combined like this:

$registry->does('foo')
    ->does('Fortissimo\Commons\HTTP\CreateURL', 'redirectTo')
        ->using('path', '/another/path')
    ->does('Fortissimo\Commons\HTTP\Redirect', 'a')
        ->using('redirect_type', 301)
        ->using('url')->from('cxt:redirectTo')
;

A common form posting idiom is to redirect a browser after a form submission. This command is useful for that.

IO

This package is newly migrated from Fortissimo itself into Fortissimo Commons. So far it only has one command.

Fortissimo\Commons\IO\UploadFile

This command simplifies the process of receiving a file and then storing it on the local filesystem.

JSON

With JSON quickly supplanting XML as a data interchange format, it's good to have some convenient JSON commands.

Fortissimo\Commons\JSON\DecodeJSON

Take data from the context, decode it using json_decode(), and then put it back into the context.

Fortissimo\Commons\JSON\EncodeJSON

Understandably, this does the opposite of the DecodeJSON command.

Fortissimo\Commons\JSON\EchoJSON

This is a convenience command for taking any old PHP object or array, converting it to JSON, and sending it back to the client.

SESSION

PHP applications frequently make use of the HTTP session (and PHP's $_SESSION) to temporarily store data. Fortissimo Commons has a few utilities for helping with this.

Fortissimo\Commons\Session\PutValue

Store an arbitrary value in the session.

Here's an example:

$registry->does('foo')
    ->does('Fortissimo\Commons\Session\PutValue', 'a')
        ->using('name', 'username')
        ->using('value')->from('get:user')
;

Assuming that $_GET['user'] is matt, this would set $_SESSION['username'] to matt. Remember that in from() calls you can access session data like this: from('session:username').

Fortissimo\Commons\Session\PopValue

This removes an item from the $_SESSION and returns it into the context.

Fortissimo\Commons\Session\DeleteValue

This deletes a value from the $_SESSION. Unlike PopValue it does not put the removed value into the context.

General Utilties

Fortissimo\Commons\FilterVar

Apply any of the PHP filter_var() filters to anything in your context.

Conclusion

As we keep working on Fortissimo Commons this set will grow. There are also some other generally useful libraries for Fortissimo, such as the Fortissimo-Twig and Fortissimo-Guzzle libraries. Because they have external dependencies they can't be added to Fortissimo-Commons, but they are very useful nonetheless.

• php
• programming
• fortissimo
• coco