(This is a slightly modified version of the QUICKSTART.md in your Fortissimo application's doc/ directory.)

This short document describes how to quickly create a Fortissimo application.

Fortissimo-Base will get your project scaffolded very quickly. You will need to get Composer, though.

Create a new Fortissimo command by adding a new file in the src/includes directory.

Here is a simple Hello World command, stored in src/includes/HelloWorld.cmd.php:

<?php
    class HelloWorld extends \Fortissimo\Command\Base {
    
      public function expects() {
        return $this->description('A simple hello world script.');
      }
    
      public function doCommand() {
        print '<h1>Hello World</h1>';
      }
    }
?>

This is a simple command that prints Hello World to the client. Typically, a command extends BaseFortissimoCommand and implements the two required methods:

• expects(): This is a documentation function, and is absolutely required. The example above is the bare minimum allowed by Fortissimo. It teaches Fortissimo about your app, and also provides developer documentation.
• doCommand(): This method is the workhorse. It handles all of the command processing. If it returns a value, the value will be placed into the application's context, which means other commands can access and use that value.

Now that we have a command, we can map it to a request.

Clients (browsers) make requests. We map a request to a chain of commands. The process looks something like this:

    browser -> 
              request->
                       command1
                          |
                       command2
                          |
                     <-command3
            <-request
    browser          

In the above, the request runs three commands before returning to the client. We'll look at a much simpler example here. In this example, we will create a simple request that has only one command.

We will use the HelloWorld command we created above.

The config.php file is located in config/config.php`. Edit this file.

To create a new request, we add a simple section to the PHP configuration file:

<?php

$registry->route('hello')->does('\HelloWorld', 'helloworld');
?>

This tells Fortissimo that when a browser requests http://yoursite.com/hello (or http://yoursite.com/index.php?ff=hello) then it should execute the helloworld command. This is accomplished by Fortissimo invoking HelloWorld. Essentially, what that means is that it will call HelloWorld::doCommand(). Using our stick diagram, then, this looks like this:

    browser -> 
              hello->
                    <-helloworld (HelloWorld::doCommand())
            <-hello
    browser

We can easily add lots of commands to a single request. In fact, we could very easily modify the above to emit 'Hello World' twice:

    <?php
    $registry->route('hello')
      ->does('\HelloWorld', 'helloworld')
      ->does('\HelloWorld', 'helloworld2');
    ?>

All we did is copy the command again, changing the name of the second one to 'helloworld2'. It must have a different name because Fortissimo uses names to keep track of what commands are executed inside of a request.

Again with the stick diagram:

      browser -> 
                hello->
                       helloworld (HelloWorld::doCommand())
                           |
                     <-helloworld2 (HelloWorld::doCommand())
              <-hello
      browser

Fortissimo's hello request executes two commands (helloworld and helloworld2) and then returns.

We could have done the entire Hello World script with even less work. We could have just used the FortissimoEcho command (located in src/Fortissimo/Command/EchoText.php):

    <?php
    $registry->route('hello')
      // Our command that we created above:
      ->does('\HelloWorld', 'helloworld')
      // The built-in FortissimoEcho command:
      ->does('\Fortissimo\Command\EchoText`, 'helloworld2')
        ->withParam('text', 'Hello Again')
    ;
    ?>

The above request will print output something like this:

    <h1>Hello World</h1>
    Hello Again

The first line comes from our \HelloWorld class, and the second from the \Fortissimo\Command\EchoText class, which provides a great example of how to write Fortissimo commands. Here's the source (well, actually an old version of it):

<?php
    class EchoText extends \Fortissimo\Command\Base {

      public function expects() {
        return $this
          ->description('Echo the contents of the "text" parameter to standard output.')
          ->usesParam('text', 'The text to echo.')
          ;
      }

      public function doCommand() {
        print $this->param('text');
      }
    }
?>

This class implements the same two functions, expects() and doCommand(). But it uses a parameter, so it is slightly more complicated.

In the expects() function, it declares its parameter with ->usesParam(). This tells Fortissimo what the name of the parameter is, and provides a one-sentence description for humans.

The doCommand() function accesses that parameter ($this->param()), and prints it to the output.

Note that no escaping or filtering is done on the text. We could very simply filter the text parameter to allow only plain text:

<?php
    class EchoText extends \Fortissimo\Command\Base {

      public function expects() {
        return $this
          ->description('Echo the contents of the "text" parameter to standard output.')
          ->usesParam('text', 'The text to echo.')
          ->withFilter('string')
          ;
      }

      public function doCommand() {
        print $this->param('text');
      }
    }
?>

The ->withFilter() function says that the text param should be filtered using the 'string' filter. This takes advantage of PHP's built-in filtering system, and you can read more about it in the API documentation. But in a nutshell, it will strip markup and non-printing characters out of the text before doCommand() executes.

Filters, then, are a good way of adding some security to your application.

So far, you have seen some light coding samples. Here are some good next steps:

• Look at the built-in commands provided with Fortissimo.
  • \Fortissimo\Command\Context\DumpContext is a good example of a simple command.
  • \Fortissimo\Command\Util\ShowPHPInfo shows some other good techniques, and is also very simple.
  • \Fortissimo\Command\IO\FileLoader is a good example of a complex command.
• Read the API docs. In particular, look at \Fortissimo\Command\Base. That's the class that gets it done for you.
• Look at the Fortissimo-Twig library. This adds Twig template support to Fortissimo. It's amazing how much you can get done with Twig templates and Fortissimo chains.

Most applications uses databases or data storage of one type or another. Fortissimo uses a concept of Datasources to handle this sort of thing.

Check out Fortissimo\Datasource\PDO to get an idea for how to work with relational databases. MongoDB support is also provided in \Fortissimo\Datasource\MongoDB.

You can, of course, use any existing database library. Extending \Fortissimo\Datasource\Base is as easy as writing a new command.

Along with Databases, Fortissimo supports caching services (like Memcached) directly. In this way, you can trivially and almost transparently add caching to your application. See \Fortissimo\Cache\Base and \Fortissimo\Cache\Memcache.