Divergence comes with a suite of controllers to aid in building APIs rapidly as well as a built in helper class for building your own controllers.

Divergence does away with routing configuration files. Instead controllers "take over" a directory path during runtime, bubbling down from the main application controller to other controllers until eventually one of the controllers responds to the request and ends the PHP thread.

To illustrate how this works in practice, let's take a look at this simple example:

<?php
namespace application\Controllers;

use Divergence\Responders\TwigBuilder;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

class Main extends \Divergence\Controllers\RequestHandler
{
    public function __construct()
    {
        $this->responseBuilder = TwigBuilder::class;
    }

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        switch ($action = $this->shiftPath()) {
            case 'admin':
                return (new Admin())->handle($request);

            case 'api':
                return (new API())->handle($request);

            case 'media':
                return (new Media())->handle($request);

            default:
                return $this->respond('home.twig');
        }
    }
}

By default our file /public/index.php will run:

require(__DIR__.'/../bootstrap/autoload.php');
require(__DIR__.'/../bootstrap/app.php');
require(__DIR__.'/../bootstrap/router.php');

Subsequently these 3 requires run code equivalent to:

define('DIVERGENCE_START', microtime(true));
require(__DIR__.'/../vendor/autoload.php');

use project\App as App;

$app = new App(realpath(__DIR__.'/../'));
$app->handleRequest();

Typically the name of the application will be different, so of course your namespace will be different. You should extend the App class and write your own root handler.

$this->shiftPath() returns the next directory in the request URI every time it is executed.

For this path:

/api/blog/1/edit

shiftPath() will return api, then blog, then 1, and finally edit.

If there is nothing left in the stack it will return false.

Utilizing this method it does not matter where in the tree the controller is. It will always be able to pick up from where it is currently.

All Divergence controllers extend abstract class Divergence\Controllers\RequestHandler.

RequestHandler keeps track of the path, where you are in it, and provides utility methods for responding to a request.

$this->responseBuilder

Current Divergence chooses response format through the response builder attached to the controller. The base helper is:

respond($responseID, $responseData = [])

These are controller methods intended to be used from inside your handlers.

The current controller base also supports endpoint registration internally:

• handlers register endpoint classes
• __call() lazily instantiates endpoint objects
• request-handling methods like handleBrowseRequest() are delegated into those endpoint classes

This is mostly an internal implementation detail, but it explains why current controller code is more modular than the older docs suggested.

Typically your app should have a controller namespace under your main application namespace, which means you should have a src/Controllers directory. This directory is recommended for storing all your controllers so that they are easy to find. You can create subdirectories for various types of controllers.

You should organize your controllers by type or subdivision of your project. For example you might organize controllers related to an admin control panel in a folder called Admin.

Divergence in no way prevents you from using third-party routing libraries. Simply register the third party library in your application's root controller handle(...) flow.

Feel free to write your own

Divergence\Controllers\RecordsRequestHandler gives you a pre-made controller for doing REST operations on a Divergence\Models\ActiveRecord model.

Example class

<?php
namespace project\Controllers\Records;

class BlogPost extends \Divergence\Controllers\RecordsRequestHandler
{
    use Permissions\LoggedIn;

    public static $recordClass = 'project\\Models\\BlogPost';
}

Internally the current implementation registers dedicated endpoint classes for:

• browse
• record
• create
• edit
• delete
• multi-save
• multi-destroy

The public API is still the familiar CRUD surface, but the internals are now split into focused endpoint classes instead of being one large handler.

/**
 * Routes
 *  /api/blogpost
 *  /api/tags
 */
public function handle(ServerRequestInterface $request): ResponseInterface
{
    switch ($action = $this->shiftPath()) {
        case 'blogpost':
            return (new BlogPost())->handle($request);

        case 'tags':
            return (new Tag())->handle($request);
    }
}

Example Trait

<?php
namespace project\Controllers\Records\Permissions;

use project\App as App;
use Divergence\Models\ActiveRecord;

trait LoggedIn
{
    public function is()
    {
        /*
         * Here we are simply checking that the user is logged in.
         * In this case that is all we need to verify their permissions.
         * Of course you should use your own logic based on the
         * authentication system you have configured.
         */
        return App::$App->is_loggedin();
    }

    public function checkBrowseAccess($arguments)
    {
        return $this->is();
    }

    public function checkReadAccess(ActiveRecord $Record)
    {
        return $this->is();
    }

    public function checkWriteAccess(ActiveRecord $Record)
    {
        return $this->is();
    }

    public function checkUploadAccess()
    {
        return $this->is();
    }

    /*
     * have this return false to disable API access entirely
     */
    public function checkAPIAccess()
    {
        return $this->is();
    }
}

Security in Divergence is mostly enforced at the controller layer. The framework gives you hooks, but your application is responsible for defining the actual policy.

The main security hooks you should care about are:

• checkBrowseAccess()
• checkReadAccess()
• checkWriteAccess()
• checkUploadAccess()
• checkAPIAccess()

In practice:

• checkAPIAccess() gates JSON API access
• checkWriteAccess() protects create, edit, delete, and batch save/destroy paths
• checkUploadAccess() protects media uploads
• shared authorization logic belongs in reusable traits

This API reference is for classes that extend Divergence\Controllers\RecordsRequestHandler.

For simplicity let's assume we have our API controller mounted at /api/tags/.

One important current detail:

• JSON mode is entered by routing through /json
• that means JSON paths look like /api/tags/json/...
• they do not look like /api/tags/.../json

That matches the current RecordsRequestHandler::handle() implementation.

URI: /api/tags/json

Method: GET, POST

Specify sort rules with a JSON encoded array.

[
    [
        'property' => 'LastName',
        'direction' => 'ASC',
    ],
    [
        'property' => 'FirstName',
        'direction' => 'ASC',
    ]
]

Specify filter rules with a JSON encoded array.

[
    [
        'property' => 'FirstName',
        'value' => 'John',
    ],
    [
        'property' => 'LastName',
        'value' => 'Doe',
    ]
]

Content-Type: application/json

{
    "success": true,
    "data": [ /* array of objects corresponding to your model */ ],
    "conditions": [],
    "total": "5",
    "limit": false,
    "offset": false
}

$ curl -s http://localhost:8080/api/tags/json | jq

{
  "success": true,
  "data": [
    {
      "ID": "1",
      "Class": "project\\Models\\Tag",
      "Created": 1523869087,
      "CreatorID": null,
      "Tag": "ssh",
      "Slug": "ssh"
    },
    {
      "ID": "2",
      "Class": "project\\Models\\Tag",
      "Created": 1523870415,
      "CreatorID": "1",
      "Tag": "linux",
      "Slug": "linux"
    }
  ],
  "conditions": [],
  "total": "7",
  "limit": false,
  "offset": false
}

Browse with sort and filter:

curl -sG http://localhost:8080/api/tags/json \
  --data-urlencode 'limit=10' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'sort=[{"property":"Created","direction":"DESC"}]' \
  --data-urlencode 'filter=[{"property":"Tag","value":"linux"}]' | jq

$ curl -s http://localhost:8080/api/blogposts/json | jq

{
  "success": false,
  "failed": {
    "errors": "API access required."
  }
}

This will be returned if your controller's checkAPIAccess() method returns false.

It returns true by default. You must redefine it to set up permissions.

URI: /api/tags/json/:handle

Method: GET, POST

The generic RecordsRequestHandler resolves records through getRecordByHandle($action). In practice that means this path segment is whatever your model exposes through getByHandle(...), not necessarily a numeric primary key.

$ curl -s http://localhost:8080/api/tags/json/2 | jq

{
  "success": true,
  "data": {
    "ID": "2",
    "Class": "project\\Models\\Tag",
    "Created": 1523870415,
    "CreatorID": "1",
    "Tag": "linux",
    "Slug": "linux"
  }
}

URI: /api/tags/json/:handle/edit

Method: POST, PUT

Values that do not belong to this model are ignored. The record is returned.

$ curl -d "param1=value1&param2=value2" -X POST -s http://localhost:8080/api/tags/json/2/edit | jq

{
  "success": true,
  "data": {
    "ID": "2",
    "Class": "project\\Models\\Tag",
    "Created": 1523870415,
    "CreatorID": "1",
    "Tag": "linux",
    "Slug": "linux"
  }
}

Trying to change the primary key will be ignored.

$ curl -d "ID=2" -X POST -s http://localhost:8080/api/tags/json/2/edit | jq

{
  "success": true,
  "data": {
    "ID": "2",
    "Class": "project\\Models\\Tag",
    "Created": 1523870415,
    "CreatorID": "1",
    "Tag": "linux",
    "Slug": "linux"
  }
}

Changes will be returned with the record.

$ curl -d "Tag=curl&Slug=curl" -X POST -s http://localhost:8080/api/tags/json/2/edit | jq

{
  "success": true,
  "data": {
    "ID": "2",
    "Class": "project\\Models\\Tag",
    "Created": 1523870415,
    "CreatorID": "1",
    "Tag": "curl",
    "Slug": "curl"
  }
}

Feel free to use a JSON string as your data payload with Content-Type: application/json.

$ curl -d '{"Tag":"JSON", "Slug":"json"}' -H "Content-Type: application/json" -X POST -s http://localhost:8080/api/tags/json/2/edit | jq

{
  "success": true,
  "data": {
    "ID": "2",
    "Class": "project\\Models\\Tag",
    "Created": 1523870415,
    "CreatorID": "1",
    "Tag": "JSON",
    "Slug": "json"
  }
}

Validation failures bubble up from the model cleanly.

$ curl -d '{"Tag":"J", "Slug":"j"}' -H "Content-Type: application/json" -X POST -s http://localhost:8080/api/tags/json/2/edit | jq

{
  "success": false,
  "data": {
    "ID": "2",
    "Class": "project\\Models\\Tag",
    "Created": 1523870415,
    "CreatorID": "1",
    "Tag": "J",
    "Slug": "j",
    "validationErrors": {
      "Tag": "Tag must be at least two characters."
    }
  }
}

Know which field caused the error and why.

Click here for many validation definition examples.

URI: /api/tags/json/create

Method: POST

The return will provide you with the new primary key and timestamp of when it was created.

$ curl -d '{"Tag":"ActiveRecord", "Slug":"activerecord"}' -H "Content-Type: application/json" -X POST -s http://localhost:8080/api/tags/json/create | jq

{
  "success": true,
  "data": {
    "ID": "8",
    "Class": "project\\Models\\Tag",
    "Created": 1527133465,
    "CreatorID": null,
    "Tag": "ActiveRecord",
    "Slug": "activerecord"
  }
}

URI: /api/tags/json/:handle/delete

Method: POST

The return will provide you with the data from the model that was deleted.

$ curl -H "Content-Type: application/json" -X POST -s http://localhost:8080/api/tags/json/8/delete | jq

{
  "success": true,
  "data": {
    "ID": "8",
    "Class": "project\\Models\\Tag",
    "Created": 1527133465,
    "CreatorID": null,
    "Tag": "ActiveRecord",
    "Slug": "activerecord"
  }
}

If you request the delete URL without POST, the generic endpoint returns a confirmation response instead of destroying the record immediately.

URI: /api/tags/json/save

METHOD: POST, PUT

The current batch save endpoint expects a payload shaped like:

{
  "data": [
    { "Tag": "one", "Slug": "one" },
    { "ID": 2, "Tag": "updated", "Slug": "updated" }
  ]
}

Example:

curl -s -X POST http://localhost:8080/api/tags/json/save \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "Tag": "Batch One", "Slug": "batch-one" },
      { "ID": 2, "Tag": "Batch Updated", "Slug": "batch-updated" }
    ]
  }' | jq

Representative response:

{
  "success": true,
  "data": [
    {
      "ID": "9",
      "Tag": "Batch One",
      "Slug": "batch-one"
    },
    {
      "ID": "2",
      "Tag": "Batch Updated",
      "Slug": "batch-updated"
    }
  ],
  "failed": []
}

URI: /api/tags/json/destroy

METHOD: POST, PUT, DELETE

The current batch delete endpoint expects data as either:

• an array of IDs
• an array of objects containing the primary key

Example:

curl -s -X DELETE http://localhost:8080/api/tags/json/destroy \
  -H "Content-Type: application/json" \
  -d '{ "data": [8, 9] }' | jq

Representative response:

{
  "success": true,
  "data": [
    { "ID": "8" },
    { "ID": "9" }
  ],
  "failed": []
}

If data is malformed you will get an error similar to:

{
  "success": false,
  "failed": {
    "errors": "Save expects \"data\" field as array of records."
  }
}

Divergence\Controllers\MediaRequestHandler extends the generic records controller with media-specific behavior for Divergence\Models\Media\Media.

In addition to the record endpoints above, it registers endpoints for:

• upload
• open/media streaming
• info
• download
• caption
• thumbnail
• media browse
• media delete

Important current behavior:

• byte-range requests are supported for streamed media
• cache headers and ETag headers are added on media responses
• uploads default to the file field name mediaFile
• JSON mode is again entered through /json at the start of the media controller path

Examples:

Browse media as JSON:

curl -s http://localhost:8080/media/json/browse | jq

Upload media:

curl -s -X POST http://localhost:8080/media/json/upload \
  -F 'mediaFile=@./tests/assets/logo.png' \
  -F 'Caption=Example upload' | jq

Get media metadata:

curl -s http://localhost:8080/media/json/info/1 | jq

Download the original media:

curl -OJ http://localhost:8080/media/download/1/logo.png

Stream partial media:

curl -i http://localhost:8080/media/open/1 \
  -H 'Range: bytes=0-1023'