Getting Started

Getting Started with Aye Aye

1. Pre-requisites
2. Installation
3. Hello World

Pre-requisites

You will require:

• PHP 5.5* or greater, or HHVM
• Composer

* Aye Aye currently works on PHP 5.4, but this is not considered a supported configuration

Installation

Aye Aye currently only supports installation through composer. You can start a new project using Aye Aye like this:

php -r "readfile('https://getcomposer.org/installer');" | php # Install composer to the current directory
./composer.phar init --require="ayeaye/api ^1.0.0@rc" -n      # Create composer.json and require AyeAye/Api
./composer.phar install                                       # Install dependencies

If you've already started a composer project and want to add Aye Aye to it, then you can add it like this:

./composer.phar require "ayeaye/api ^1.0.0@rc"

Hello World

Aye Aye works through a tree of controllers. You start with an initial controller, and this may branch to further controllers, or it might have endpoints, or both. This example uses a single controller with a single endpoint.

We'll start by creating a file called HelloWorldController.php

<?php   // HelloWorldController.php

use AyeAye\Api\Controller;

class HelloWorldController extends Controller
{
    /**
     * Our first command
     * @param string $name Optional, defaults to 'Captain'
     * @returns string
     */
    public function getAyeAyeEndpoint($name = 'Captain')
    {
        return "Aye Aye $name";
    }
}

To use the controller we'll need an entry point into our program. To this end, let's make an index.php

<?php   // index.php

require_once 'vendor/autoload.php';      // Require the autoloader provided by Composer
require_once 'HelloWorldController.php'; // Require our Hello World file

$initialController = new HelloWorldController(); // Instantiating our controller
$api = new \AyeAye\Api\Api($initialController);  // Instantiate the API, telling it which controller to start with

$api->go()->respond();

We can try this out with PHP's built in server

php -S localhost:8000 index.php &   # Run the internal web server in the background using index.php
curl localhost:8000/aye-aye         # Get the default response from our end point
# {"data":"Aye Aye Captain"}
curl localhost:8000/hello?name=Sexy # Override the default name on our end point
# {"data":"Aye Aye Sexy"}
curl localhost:8000                 # See the documentation for our initial controller
# {"data":{"controllers":[],"endpoints":{"get":{"aye-aye":{"description":"Our first command","parameters":{"name":{"type":"string","description":"Optional, defaults to 'Captain'"}}}}}}}
fg                                  # Bring the server back into the foreground
^C                                  # Stop the server with Ctrl + C

Note: you should never use PHP's built in server for production

Let's have a closer look at that final response from the api that included our documentation:

{
  "data": {
    "controllers": [
            
    ],
    "endpoints": {
      "get": {
        "aye-aye": {
          "description": "Our first command",
          "parameters": {
            "name": {
              "type":        "string",
              "description": "Optional, defaults to 'Captain'"
            }
          }
        }
      }
    }
  }
}

This is Aye Aye's self documentation. Aye Aye uses Reflection to analyse your controllers, identify endpoints and controllers, and read the comments you wrote to describe how they work to your end users.

Note: Currently, there is no way to prevent or override this functionality so be careful what you write here. This is planned for a future release, after version 1.0.0.

Notice that Aye Aye broke down the name of your endpoint, removing the HTTP verb get from the beginning, and the Endpoint identifier from the end. It then lowercases, and hyphenates the remaining name to create the aye-aye endpoint.