andrewscaya/statuslib-example

Library for use with Apigility documentation examples

1.2.0 2018-04-21 03:12 UTC

This package is auto-updated.

Last update: 2020-05-29 05:48:03 UTC


README

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:

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

  1. 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
  1. Install the StatusLib module:
$ composer require zfcampus/statuslib-example
  1. 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,
          ],
      ],
  2. 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
        );
    }