Fast Forward

by Marco Stoll

Introduction - What is Fast Forward?

Fast Forward (in short FF) is a generic application template for building web and/or command line applications fast and easy. It addresses the common tasks and provides configurable and/or extendable default implementations for you to use.

Currently FF is composed of the following features:

Services and the Service Factory
Events and the Event Broker
Runtime event handlers
Templating and Twig as a Service
Dispatching and Controllers
Sessions

More features will follow (see the Road Map section below).

A Warning before you start

FF is highly opinionated and depends on a bunch of conventions! So be sure to consult the documentation before deciding to develop your application based on FF.
But if you do FF ensures a minimal amount of setup, letting you concentrate your efforts on your business logic instead of some framework configuration.

Dependencies

Fast Forward Family

FF makes heavy usage of the Fast Forward Family components, a collection of independent components providing generic implementations (like data structures of design patterns) used by many of FF's features.

Installation

Via Composer (recommended)

Manual Installation

Bootstrapping

Bootstrap a web application

Bootstrap a command line application

Services and the Service Factory

Services - a Definition

From the FF perspective a service is a singular component (mostly class) that provide needed functionality as part of certain domain. Common attributes of services should be

Make minimal assumptions of the surrounding runtime environment.
Be stateless.
Be unit testable.

Writing Services

[CONVENTION] Service classes extend FF\Services\AbstractService.
[CONVENTION] Services must be located in your project's MyProject\Services namespace (or any sub namespace thereof) to be found by the ServicesFactory.

Example: Basic service implementation

namespace MyProject\Services;

use FF\Services\AbstractService;

class MyService extends AbstractService
{

}

FF services can be configured if needed. The ServicesFactory will initialize a service's instance with available config options. But it will be your responsibility to validate that any given options will meet your service's requirements.

Example: Configurable service implementation

namespace MyProject\Services;

use FF\Services\AbstractService;

class MyConfigurableService extends AbstractService
{
    /**
     * {@inheritDoc}
     */
    protected function validateOptions(array $options, array &$errors): bool
    {
        // place you option validation logic here
        // example
        if (!isset($options['some-option'])) {
            $errors[] = 'missing options [some-options]';
            return false;
        }
        
        return true;
    }
}

Using the Service Factory

FF's service factory is based on the AbstractSingletonFactory of the FF-Factories component. Be sure to consult component's documentation for further information about using FF factories.

To retrieve a service from the factory you have to know thw service's class identifier. These class identifiers are composed of the service's class name prefixed by any sub namespace relative to FF\Services (for built-in services) or MyProject\Services (for you custom services).

For convenience reasons there is a shorthand class SF that lets you retrieve one or more services with minimal effort.

Example: Getting a single service

use FF\Factories\SF;
use MyProject\Services\MyService;

/** @var MyService $myService */
$myService = SF::i()->get('MyService'); // finds MyProject\Services\MyService

Example: Getting multiple services at once

use FF\Factories\SF;
    use FF\Services\Events\EventBroker;
use MyProject\Services\MyService;

/** @var EventBroker $eventBroker */
/** @var MyService $myService */
list ($eventBroker, $myService) = SF::i()->get('Events\EventBroker', 'MyService');

Extending built-in FF Services

The ServicesFactory uses a FF\Factories\NamespaceClassLocator locator to find services definitions bases on a class identifier. To archive this, it searches the list of registered base namespace for any suitable service class in the given order.

This feature lets you sub class and replace FF's built-in service implementations easily by just following the naming conventions and registering the ServiceFactory as shown in the Bootstrapping section of this document.

Example: Extend/Replace a built-in service

namespace MyProject\Services\Runtime;

use FF\Services\Runtime\ExceptionHandler as FFExceptionHandler;

class ExceptionHandler extends FFExceptionHandler
{
    // place your custom logic here
}

###############

// when ever some component refers to the 'Runtime\ExceptionHandler' service via the ServicesFactory
// an instance of your service extension will be used instead of the built-in service

/** @var MyProject\Services\Runtime\ExceptionHandler $exceptionHandler */
$exceptionHandler = SF::get('Runtime\ExceptionHandler');

Events and the Event Broker

This feature provides a basic observer/observable pattern implementation. The key class is the EventBroker. Any other class may act as an observable by firing events using the EventBroker's api. Other classes my act as observers by subscribing to specific types of events and being notified by the EventBroker in each time this type of event was fired.

Firing Events

If an observable wants to notify potential observers of notable changes it simply fires a suitable event using the EventBroker's api.

Example: Fire an event

use FF\Factories\SF;
use FF\Services\Events\EventBroker;

class MyExceptionHandler
{
    /**
     * Generic exception handler callback
     *
     * @param \Throwable $e
     * @see http://php.net/set_exception_handler
     */
    public function onException(\Throwable $e)
    {
        try {
            /** @var EventBroker $eventBroker */
            $eventBroker = SF::i()->get('Events\EventBroker');
            $eventBroker->fire('Runtime\Exception', $e);
        } catch (\Exception $e) {
            // do not handle exceptions thrown while
            // processing the on-exception event
        }
    }
}

The fire method of the EventBroker uses the EventsFactory to instantiate the actual event object passing any additional argument provided to the event class's constructor.

Subscribing to Events

A valid event handling method must meet the following requirements:

must be public
must not be static or abstract
accept exactly one argument: the event classes instance

Example: Subscribe to an event

use FF\Events;
use FF\Factories\SF;
use FF\Services\Events\EventBroker;    

class MyErrorObserver
{
    /**
     * Event handling callback
     *
     * @param Runtime\Error $event
    public function onRuntimeError(Runtime\Error $event)
    {
        // handle the Error event
        var_dump(
            $event->getErrNo(), 
            $event->getErrMsg(), 
            $event->getErrFile(),
            $event->getErrLine()
        );
    }
}

// subscribe to the Runtime\Error event
/** @var EventBroker $eventBroker */
$eventBroker = SF::i()->get('Events\EventBroker');
$eventBroker->subscribe([new MyErrorObserver, 'onRuntimeError'], 'Runtime\Error');

The subscription is bases on the class identifier of the event class. This is exactly the same string to use by the observable when firing the event.

Defining Custom Events

[CONVENTION] Event classes extend FF\Events\AbstractEvent.
[CONVENTION] Events must be located in your project's MyProject\Events namespace (or any sub namespace thereof) to be found by the EventsFactory.

Example: A custom event

namespace MyProject\Events;

use FF\Events\AbstractEvent;

/**
 * This event's class identifier would just be 'Logoff'
 */
class Logoff extends AbstractEvent
{
    /**
     * Define constructor arguments (the event data) to meet your needs.
     */
    public function __construct($eventData)
    {
        var_dump($eventData);
    }
}

Runtime Event Handlers

This feature introduces three different handler classes for registering as callbacks to one of the three runtime events of the php engine (error, exception, shutdown). The handlers translate php's core event information to FF\Events event instances using the EventBroker.

Registering Runtime Event Handlers

All handlers implement the RuntimeEventHandlerInterface which lets you register() them on demand.
The ErrorHandler as well as the ExceptionHandler each are aware of any previous handlers that might have been registered to their runtime events and let you restore the previous state. When registering shutdown handlers no information regarding the previous state is provided by php.

Subscribing to Runtime Events

The handlers fire their own events containing all available event data which makes it easy for you to handle them by subscribing to the FF\Events\EventBroker.

Example:

use FF\Events\Runtime\Error;
use FF\Factories\SF;
use FF\Services\Events\EventBroker;
use FF\Services\Runtime\ErrorHandler;

// register the ErrorHandler
(new ErrorHandler())->register();

/** @var EventBroker $eventBroker */
$eventBroker = SF::i()->get('events\EventBroker');

// subscribe to the Runtime\Error event
$eventBroker->subscribe('Runtime\Error', function (Error $event) {
    // handle the event data
    var_dump($event->getErroNo(), $event->getErrMsg());  
}};

Templating and Twig as a Service

This feature provides the TemplateRendererInterface defining the basic api for adding concrete template rendering class.

Rendering Events

The TemplateRendererInterface defines that each concrete renderer may fire the following events while performing its render() method:

Templating\PreRender : directly before rendering the template
Templating\PostRender : directly after rendering the template

Adding observers for this events lets you manipulate the rendering input data as well as the rendering output document on your behalf.

Twig Support

A generic TwigRenderer renderer service is provided using a Twig\FilesystemLoader to locate templates.

Consult https://twig.symfony.com/ to learn more about Twig.

The TwigRenderer may be configured to fire rendering events if desired.

Dispatching and Controllers

This feature provides the Dispatcher service that lets you delegate requests to your desired controller action base on a defined routing as well as the AbstractController base class.

Routing

The Disptacher expects its routing configuration in yaml form. It will parse this information via Symfony's YamlFileLoader

As valid yml structure route entries in the configuration should look like this:

<< route name >>:
    path: << url path >>
    defaults: { controller: << controller class identifier >>, action: << action method >> }

The path my contain argument placeholder in the form of {arg}. The defaults section may additionally contain named arguments to provide default values for patharguments. You may provide a requirements section to specify route limitations (like patterns for acceptable argument values). See https://symfony.com/doc/current/routing.html for more information.

Some examples:

# route to the 'index' action of your project's IndexController
home:
    path: /
    defaults: { controller: IndexController, action: index }
    
# route to the 'list' action of your project's ArticlesController located in the sub package 'Articles'
# defines an optional path argument 'category' that will be fill with an empty string if omitted    
list-articles:
    path: /articles/{category}
    defaults: { controller: Articles\ArticlesController, action: list, category: '' }
    requirements:
        category: \w+

Writing Controllers

[CONVENTION] Controller classes extend FF\Controllers\AbstractController.
[CONVENTION] Controllers must be located in your project's MyProject\Controllers namespace (or any sub namespace thereof) to be found by the Controllers.

Any action method a controller defines must meet the following requirements: [CONVENTION] must be public [CONVENTION] must not be static [CONVENTION] must return an instance of Symfony\Component\HttpFoundation\Response

Action methods may define any number of arguments.

Each concrete controller must implement the getTemplateRenderer() method. If you like to use FF's built-in Twig rendering service, just provide a common base class for the controllers in your project and retrieve the TwigRenderer from the service factory.

Example: Twig-aware base controller

namespace MyProject\Controllers;

use FF\Controllers\AbstractController;
use FF\Factories\SF;
use FF\Services\Templating\TemplateRendererInterface;
use FF\Services\Templating\TwigRenderer;

/**
 * This event's class identifier would just be 'HelloWorld'
 */
class TwigAwareBaseController extends AbstractController
{
    /**
     * @{inheritDoc}
     * @return TwigRenderer
     */
    protected function getTemplateRenderer(): TemplateRendererInterface
    {
        return SF::i()->get('Templating\TwigRenderer');
    }  
}

Example: A hello world controller

namespace MyProject\Controllers;

use Symfony\Component\HttpFoundation\Response;

/**
 * This event's class identifier would just be 'HelloWorld'
 */
class HelloWorld extends TwigAwareBaseController
{
    /**
     * An action method
     *
     * The yml route configuration for thius action would be
     *
     + your-route-name:
     *      defaults: { controller: HelloWorld, action: helloWorld }
     *
     * @return Response
     */
    public function helloWorld()
    {
        return $this->render('hello-world.html.twig', ['msg' => 'Hello, World!']);
    }
}

Sessions

FF's built-it Session service in essence just wraps php's session functions in an object oriented way. It lets you start(), regenerate(), writeClose(), and destroy() sessions as well as get(), set(), and unset() values.

The service can be configured using all the known session.XYZ options that the php session module defines. The service defines some different default though, mostly to enhance the default security behaviour regarding session cookies.

Defining Custom Session Save Handlers

Observing Session Events

The Session service emits a number of events.

The defined events are classic life cycle events fired at distinct moments in a session's life. Observing this kind of events lets you manipulate the session's state on your behalf.

Example: Adding data to the session right after start

use FF\Events;
use FF\Factories\SF;
use FF\Services\Events\EventBroker;    

class MySessionObserver
{
    /**
     * Event handling callback
     *
     * @param Sessions\PostStart $event
    public function onPostStart(Sessions\PostStart $event)
    {
        $event->getSession()->set('foo', 'bar');
    }
}

// subscribe to the Sessions\PostStart event
/** @var EventBroker $eventBroker */
$eventBroker = SF::i()->get('Events\EventBroker');
$eventBroker->subscribe([new MySessionObserver, 'onPostStart'], 'Sessions\PostStart');

Road Map

Session Handlers
Security
CLI
ORM
Bootstrapping

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
bin		bin
docs/html		docs/html
src		src
tests		tests
.gitignore		.gitignore
composer.json		composer.json
license.md		license.md
phpdox.xml		phpdox.xml
readme.md		readme.md

License

marcostoll/FF

Folders and files

Latest commit

History

Repository files navigation