StatusLib

Repository abandoned 2019-12-31

This repository has moved to laminas-api-tools/statuslib-example.

This is a library designed to demonstrate an Apigility "Code-Connected" REST API, and has been written in parallel with the Apigility documentation.

It uses the following components:

rhumsaa/uuid, a library for generating and validating UUIDs.
zfcampus/zf-configuration, used for providing PHP files as one possible backend for reading/writing status messages.
zendframework/zend-config for the actual configuration writer used by the zf-configuration module.
zendframework/zend-db, used for providing a database table as a backend for reading/writing status messages.
zendframework/zend-stdlib, specifically the Hydrator subcomponent, for casting data from arrays to objects, and for the ArrayUtils class, which provides advanced array merging capabilities.
zendframework/zend-paginator for providing pagination.

It is written as a Zend Framework module, but could potentially be dropped into other applications; use the StatusLib\*Factory classes to see how dependencies might be injected.

Installation

Use Composer to install the library in your application:

$ composer require zfcampus/statuslib-example

If you are using this as part of a Zend Framework or Apigility application, you may need to enable the module in your config/application.config.php file, if you are not using the zend-component-installer:

return [
    /* ... */
    'modules' => [
        /* ... */
        'StatusLib',
    ],
    /* ... */
];

Configuration

When used as a Zend Framework module, you may define the following configuration values in order to tell the library which adapter to use, and what options to pass to that adapter.

[
    'statuslib' => [
        'db' => 'Name of service providing DB adapter',
        'table' => 'Name of database table within db to use',
        'array_mapper_path' => 'path to PHP file returning an array for use with ArrayMapper',
    ],
    'service_manager' => [
        'aliases' => [
            // Set to either StatusLib\ArrayMapper or StatusLib\TableGatewayMapper
            \StatusLib\Mapper::class => \StatusLib\ArrayMapper::class,
        ],
    ],
]

For purposes of the Apigility examples, we suggest the following:

Create a PHP file in your application's data/ directory named statuslib.php that returns an array:
```
<?php
return [];
```

Edit your application's config/autoload/local.php file to set the array_mapper_path configuration value to data/statuslib.php:

<?php
return [
    /* ... */
    'statuslib' => [
      'array_mapper_path' => 'data/statuslib.php',
    ],
];

The above will provide the minimum necessary requirements for experimenting with the library in order to test an API.

Using a database

The file data/statuslib.sqlite.sql contains a SQLite schema. You can create a SQLite database using:

$ sqlite3 statuslib.db < path/to/data/statuslib.sqlite.sql

The schema can be either used directly by other databases, or easily modified to work with other databases.

StatusLib in a New Zend Framework Project

Create a new Zend Framework project from scratch; we'll use my-project as our project folder:

$ composer create-project zendframework/skeleton-application my-project

Install the StatusLib module:

$ composer require zfcampus/statuslib-example

Build a DataSource

Option A: Array data source:

First, copy the sample array to the data directory of thet application:

$ cp vendor/zfcampus/statuslib-example/data/sample-data/array-data.php data/status.data.php

Then, configure this datasource by setting up a local.php configuration file:

$ cp config/autoload/local.php.dist config/autoload/local.php

Next, add the StatusLib specific configuration for an array based data source:

'statuslib' => [
   'array_mapper_path' => 'data/status.data.php',
],
'service_manager' => [
    'aliases' => [
        \StatusLib\Mapper::class => \StatusLib\ArrayMapper::class,
    ],
],

Option B: Sqlite data source:

First, create a sqlite3 database, and fill it with the sample data:

$ sqlite3 data/status.db < vendor/zfcampus/statuslib-example/data/statuslib.sqlite.sql
$ sqlite3 data/status.db < vendor/zfcampus/statuslib-example/data/sample-data/db-sqlite-insert.sql

Then, configure this datasource by setting up a local.php configuration file:

$ cp config/autoload/local.php.dist config/autoload/local.php

Next, add the StatusLib specific configuration for a sqlite database based data source:

'db' => [
    'adapters' => [
        'MyDb' => [
            'driver' => 'pdo_sqlite',
            'database' => __DIR__ . '/../../data/status.db'
        ],
    ],
],
'statuslib' => [
    'db' => 'MyDb',
    'table' => 'status',
],
'service_manager' => [
    'aliases' => [
        \StatusLib\Mapper::class => \StatusLib\TableGatewayMapper::class,
    ],
],

Create a test script to prove the data source is working:

// test.php
namespace StatusLib;

use Zend\Mvc\Application;
use Zend\Stdlib\ArrayUtils;

include 'vendor/autoload.php';

$appConfig = include 'config/application.config.php';

if (file_exists('config/development.config.php')) {
    $appConfig = ArrayUtils::merge(
        $appConfig,
        include 'config/development.config.php'
    );
}

$app = Application::init($appConfig);
$services = $app->getServiceManager();

$statusMapper = $services->get(Mapper::class);
foreach ($statusMapper->fetchAll() as $status) {
    printf(
        "[%d] [%s] %s (by %s)\n",
        $status->timestamp,
        $status->id,
        $status->message,
        $status->user
    );
}