ggedde/spry

PHP API Framework

Spry

A lightweight PHP API Framework
Great for CRUD applications, _(*1)

    , _(*2)

@PSR2 and @Symfony Compliant, _(*3)

Documentation

• Installation
• Quick Start
• Configuration
• Components
• Routes
• Database
• Logger
• Response
• Response Codes
• Tests
• Rate Limits
• Lifecycle Hooks & Filters (Middleware)
• Todos

Installation

The best way to install Spry and use it is through the CLI. https://github.com/ggedde/spry-cli, _(*4)

composer global require ggedde/spry-cli

Please reference the Installation Process on the CLI Page.
Then from the command line:, _(*5)

spry new [project_name]
cd [project_name]

An enpoint is automatically created for you, _(*6)

public/index.php, _(*7)

include dirname(__DIR__).'/vendor/autoload.php';
include dirname(__DIR__).'/spry/init.php';

, _(*8)

Manual Installation

composer require ggedde/spry

You will need to add the composer autoloader if it has not already been added. Then use the run method and include a path to your config file or include a config object. See configuration, _(*9)

Example:, _(*10)

include_once '/vendor/autoload.php';
Spry\Spry::run('../config.php');

QuickStart

Create a project through the CLI

spry new [project_name]
cd [project_name]

Folder Structure

- public/
    index.php
- spry/
    - components/
    - logs/
        - api.log
        - php.log
    - config.php
    - init.php

To Start the Spry test server run

spry up

Then open a separate termal and run some tests

spry test

Create a Single FIle Component

spry component MyComponent

Now View and Edit spry/components/MyComponent.php, _(*11)

Update Database Schema from New Component to Database

spry migrate

Run Tests again with new Component

spry test

Thats It!
Happy Coding, _(*12)

Well, I guess you might need more info. Most of all your coding will be in the components files you create and the rest will most likely be in the configuration file. See more details below :), _(*13)

, _(*14)

Configuration

Spry requires a config file or a config object., _(*15)

When using a config file Spry will pass a pre-initialized $config object to the file. You will just need to set the variables within the object, _(*16)

Example Config File:, _(*17)

<?php
$config->salt = '';
$config->endpoint = 'http://localhost:8000';
$config->componentsDir = __DIR__.'/components';
...

Accessing Config Settings

You can access any setting by calling the config() object from Spry, _(*18)

Example:, _(*19)

echo Spry::config()->salt;
echo Spry::config()->db['database_name']

## Extending Config Settings

You can add your own settings and then access them later in your component, provider or plugin, _(*20)

config.php, _(*21)

$config->mySetting = '123';

MyComponent.php, _(*22)

echo Spry::config()->mySetting;

Components

Spry is mainly used through components added in the componentsDir set in the Spry config., _(*23)

Components are classes within the SpryComponent Namespace.
Components can set their own Routes, Response Codes, DB Schema and Tests by using built in methods. Or you can configure everything through the config.php, _(*24)

These built in Methods are Optional:, _(*25)

Any Methods that resolve a route is called a Controller and gets passed any Parameters from the route., _(*26)

Basic Example:, _(*27)

<?php

namespace Spry\SpryComponent;

use Spry\Spry;

class MyComponent
{
    private static $id = 2; // Component ID

    public static function setup() {
        Spry::addFilter('configure', 'MyComponent::stuff');
    }

    public static function stuff($config) {
        // Do Stuff
        return $config;
    }

    public static function getRoutes() {
        return [
            '/items/{id}' => [
                'label' => 'Get Item',
                'controller' => 'MyComponent::get',
                'access' => 'public',
                'methods' => 'GET',
                'params' => [
                    'id' => [
                        'required' => true,
                        'type' => 'int',
                    ],
                ],
            ],
        ];
    }
    public static function getCodes() {
        return [
            0 => [
                'success' => ['en' => 'Successfully Retrieved Item'],
                'warning' => ['en' => 'No Item with that ID Found'],
                'error' => ['en' => 'Error: Retrieving Item'],
            ],
            1 => [
                'info' => ['en' => 'Empty Results'],
                'success' => ['en' => 'Successfully Retrieved All Items'],
                'error' => ['en' => 'Error: Retrieving All Items'],
            ],
        ];
    }
    public static function getSchema() {
        return [
            'items' => [
                'columns' => [
                    'name' => [
                        'type' => 'string',
                    ],
                ],
            ],
        ];
    }
    public static function getTests() {
        return [
            'items_get' => [
                'label' => 'Get Example',
                'route' => '/items/123',
                'method' => 'GET',
                'params' => [],
                'expect' => [
                    'status' => 'success',
                ],
            ],
        ];
    }

    public static function get($params = [])
    {
        $response = Spry::db()->get('items', '*', $params)
        return Spry::response(self::$id, 01, $response);
    }
}

Routes

When using single file components you can set the routes in the Components by returning the routes in the getRoutes() method., _(*28)

Example:, _(*29)

public static function getRoutes() {
    return [
        '/items/{id}' => [
            'label' => 'Get Item',
            'controller' => 'MyComponent::get',
            'access' => 'public',
            'methods' => 'GET',
            'params' => [
                'id' => [
                    'required' => true,
                    'type' => 'int',
                ],
            ],
        ],
    ];
}

Or within the Config Settings

$config->routes[
    '/items/{id}' => [
        'label' => 'Get Item',
        'controller' => 'MyComponent::get',
        'access' => 'public',
        'methods' => 'GET',
        'params' => [
            'id' => [
                'required' => true,
                'type' => 'int',
            ],
        ],
    ],
    ...
];

Route Options

Param Options

Database

Spry's default Database Provider is SpryDB based on Medoo
See SpryDB's full documentation, _(*30)

This allows you to swap out the Provider later on without having to change your project code., _(*31)

Spry::db()->get('items', '*', ['id' => 123]);
Spry::db()->select('items', '*', ['date[>]' => '2020-01-01']);
Spry::db()->insert('items', ['name' => 'test', 'date' => '2020-01-01']);
Spry::db()->update('items', ['name' => 'newtest'], ['id' => 123]);
Spry::db()->delete('items', ['id' => 123]);

Spry Config Settings

$config->dbProvider = 'Spry\\SpryProvider\\SpryDB';
$config->db = [... ];

Logger

Spry's default Log Provider is SpryLogger
See SpryLogger's full documentation, _(*32)

This allows you to swap out the Provider later on without having to change your project code., _(*33)

Spry::log()->message("My Message");
Spry::log()->warning("Warning");
Spry::log()->error("Error");

Spry Configuration

$config->loggerProvider = 'Spry\\SpryProvider\\SpryLogger';
$config->logger = [... ];

, _(*34)

Response

Spry has 2 built in functions for building the response (response and stop)., _(*35)

response

Spry::response($data = null, $responseCode = 0, $responseStatus = null, $meta = null, $additionalMessages = []);

You can use this to build the response data and return it from the Controller., _(*36)

$responseCode: This is the Response code id from the Component. $responseStatus: This can be either null | info | success | warning | error
If null then the function will auto detect the status based on the value of $data, _(*37)

Example:, _(*38)

$data = ['id' => 123, 'name' => 'John'];
return Spry::response($data, 0);

stop

Spry::stop($responseCode = 0, $responseStatus = null, $data = null, $additionalMessages = [], $privateData = null);

This will immediately kill the application and return the response, _(*39)

Example:, _(*40)

if ($error) {
    Spry::stop(0);
}

* See Response Codes Below to see how this works, _(*41)

, _(*42)

ResponseCodes

Single File Component Example:

public static function getCodes()
{
    return [
        0 => [ // Get Single
            'success' => ['en' => 'Successfully Retrieved Item'],
            'warning' => ['en' => 'No Item with that ID Found'],
            'error' => ['en' => 'Error: Retrieving Item'],
        ],
        1 => [ // Get Multiple
            'info' => ['en' => 'No Results Found'],
            'success' => ['en' => 'Successfully Retrieved Items'],
            'error' => ['en' => 'Error: Retrieving Items'],
        ],
        2 => [ // Insert
            'success' => ['en' => 'Successfully Created Item'],
            'error' => ['en' => 'Error: Creating Item'],
        ],
        3 => [ // Update
            'success' => ['en' => 'Successfully Updated Item'],
            'error' => ['en' => 'Error: Updating Item'],
        ],
        4 => [ // Delete
            'success' => ['en' => 'Successfully Deleted Item'],
            'error' => ['en' => 'Error: Deleting Item'],
        ],
    ];
}

Config File Example

Notice you will need to add a Group Group Number for the component codes. This is not needed in the Single File Component setup, _(*43)

$config->tests[
    1 => [
        0 => [ // Get Single
            'success' => ['en' => 'Successfully Retrieved Item'],
            'warning' => ['en' => 'No Item with that ID Found'],
            'error' => ['en' => 'Error: Retrieving Item'],
        ],
        1 => [ // Get Multiple
            'info' => ['en' => 'No Results Found'],
            'success' => ['en' => 'Successfully Retrieved Items'],
            'error' => ['en' => 'Error: Retrieving Items'],
        ],
        2 => [ // Insert
            'success' => ['en' => 'Successfully Created Item'],
            'error' => ['en' => 'Error: Creating Item'],
        ],
        3 => [ // Update
            'success' => ['en' => 'Successfully Updated Item'],
            'error' => ['en' => 'Error: Updating Item'],
        ],
        4 => [ // Delete
            'success' => ['en' => 'Successfully Deleted Item'],
            'error' => ['en' => 'Error: Deleting Item'],
        ],
    ],
    2 => [
        0 => [ // Get Single
            'success' => ['en' => 'Successfully Retrieved Other Item'],
            'warning' => ['en' => 'No Other Item with that ID Found'],
            'error' => ['en' => 'Error: Retrieving Other Item'],
        ],
        1 => [ // Get Multiple
            'info' => ['en' => 'No Results Found'],
            'success' => ['en' => 'Successfully Retrieved Other Items'],
            'error' => ['en' => 'Error: Retrieving Other Items'],
        ],
        2 => [ // Insert
            'success' => ['en' => 'Successfully Created Other Item'],
            'error' => ['en' => 'Error: Creating Other Item'],
        ],
        3 => [ // Update
            'success' => ['en' => 'Successfully Updated Other Item'],
            'error' => ['en' => 'Error: Updating Other Item'],
        ],
        4 => [ // Delete
            'success' => ['en' => 'Successfully Deleted Other Item'],
            'error' => ['en' => 'Error: Deleting Other Item'],
        ],
        5 => ['redirect' = ['en' => 'Depricated: This route is depricated']],
        6 => ['error' = ['en' => 'Error: Custom Error Message']],
        7 => ['error' = ['en' => 'Error: Another Custom Error Message']],
        8 => ['error' = ['en' => 'Error: And Another Custom Error Message']],
    ],
    ...
];

Component Group Number

The first number is to separate the Components codes by ID
Ex., _(*44)

1-200   # Success For Component A 
2-200   # Success For Component B 

Multi-Language Support

1 => [
    'success' => [
        'en' => 'Success!',
        'es' => '¡Éxito!'
    ]
]

Format - Info, Success, Redirect or Depricated, Client Error and Server Error

The first number in the code represents the code type., _(*45)

[group_id]-[1]xx - the 1 represents 'Info' or 'Empty'
[group_id]-[2]xx - the 2 represents 'Success'
[group_id]-[3]xx - the 3 represents 'Redirect' or 'Depricated'
[group_id]-[4]xx - the 4 represents 'Client Error', or 'Unkown'
[group_id]-[5]xx - the 5 represents 'Server Error', _(*46)

When using Spry::response() you can pass just the last 2 digits as the code and the data parameter., _(*47)

Ex., _(*48)

Spry::response($data, 1); 

If $data is an array but empty then the response will automatically Prepend the code with a 1 and return 1-101.
If $data has a value and is not empty then the response will automatically Prepend the code with a 2 and return 1-201.
If $data is an array but not null then the response will automatically Prepend the code with a 4 and return 1-401.
If $data is false or null then the response will automatically Prepend the code with a 5 and return 1-501., _(*49)

Response Status

In the response there will be a key of status
The possible values for this will only be success, error, or unknown, _(*50)

info, success, and redirect all represent a successfully response and will return success
warning and error represent a failed response and will return error, _(*51)

, _(*52)

Tests

Spry comes with its own pre-built testing solution. You can still use other like PHPUnit, but Spry's Tests utilize's Spry's config for rapid testing. When using single file components you can set the routes in the Components by returning the routes in the getTests() method., _(*53)

Example:, _(*54)

public static function getTests() {
    return [
        'items_insert' => [
            'label' => 'Insert Item',
            'route' => '/items/insert',
            'method' => 'POST',
            'params' => [
                'name' => 'TestData',
            ],
            'expect' => [
                'status' => 'success',
            ],
        ],
        'items_get' => [
            'label' => 'Get Item',
            'route' => '/items/{items_insert.body.id}',
            'method' => 'GET',
            'params' => [],
            'expect' => [
                'status' => 'success',
            ],
        ],
        'items_delete' => [
            'label' => 'Delete Item',
            'route' => '/items/delete/',
            'method' => 'POST',
            'params' => [
                'id' => '{items_insert.body.id}'
            ],
            'expect' => [
                'status' => 'success',
            ],
        ],
    ];
}

Or within the Config Settings

$config->tests[
    'items_get' => [
        'label' => 'Get Example',
        'route' => '/items/123',
        'params' => [],
        'expect' => [
            'code' => '1-200',
        ],
    ],
    'items_get' => [
        'label' => 'Get Example',
        'route' => '/items/123',
        'params' => [],
        'expect' => [
            'body.id[>]' => 12,
        ],
    ],
    ...
];

Test Options

Running Tests with Spry CLI

All Tests, _(*55)

spry test

Specific Test, _(*56)

spry test items_get

More Options, _(*57)

spry test --verbose --repeat 10

, _(*58)

RateLimits

Spry's default Rates Limits is SpryRateLimits
See full documentation, _(*59)

This allows you to swap out the Provider later on without having to change your project code., _(*60)

Add a Global Rate Limit

$config->rateLimits = [
  'driver' => 'file',
  'fileDirectory' => __DIR__.'/rate_limits',
  'excludeTests' => false,
  'default' => [
      'by' => 'ip',
      'limit' => 10,
      'within' => 1,
      'hook' => 'configure',
      'excludeTests' => false
  ]
];

Adding Limits per route

$config->routes = [
    '/auth/login' => [
        'label' => 'Auth Login',
        'controller' => 'Auth::login',
        'access' => 'public',
        'methods' => 'POST',
        'limits' => [
            'by' => 'ip',
            'limit' => 1,
            'within' => 3,
            'excludeTests' => false
        ],
        'params' => [
            'email' => [
                'required' => true,
                'type' => 'string',
            ],
            'password' => [
                'required' => true,
                'type' => 'string',
            ],
        ],
    ],
];

See full documentation, _(*61)

, _(*62)

Lifecycle

Hooks & Filters Lifecycle in order of completion:
, _(*63)

Non Lifecycle Hooks & Filters

Hooks

Hooks allow you to run your own code at specific times and life cycles. This is how you can run middleware and other life cycle aware code., _(*64)

Adding Hooks

Spry::addHook(string $hookName, string|callable $controller, [ mixed $extraData = null [, int $order = 0 ]] ) : void

Example:, _(*65)

Spry::addHook('configure', 'Spry\\SpryComponent\\MyComponent::myMethod', ['bar' => 345], 100);

Running Hooks

Spry::runHook(string $hookName, [ mixed $data ] ) : void

Example:, _(*66)

Spry::runHook('configure',['foo' => 123] [[ mixed $data = null ], mixed $meta = null ] );

Your Controller, _(*67)

class MyComponent

public static function myMethod($data = null, $meta = null, $extraData = null) {
    $data // [foo => 123]
    $meta // null
    $extraData // [bar => 345]
    // Do Stuff
}

Filters

Filters allow you to filter data at specific times and life cycles. A filter typically requires a return value., _(*68)

Adding Filters

Spry::addFilter(string $filterName, string|callable $controller, [ mixed $extraData = null [, int $order = 0 ]] ) : void

Example:, _(*69)

Spry::addFilter('configure', 'Spry\\SpryComponent\\MyComponent::myMethod', ['bar' => 345], 100);

Running Filters

Spry::runFilter(string $filterName, [[ mixed $data = null ], mixed $meta = null ] ) : void

Example:, _(*70)

$config = Spry::runFilter('configure', $config, ['component' => 'someComponent', 'var' => 'abc']);

Your Controller, _(*71)

class MyComponent

public static function myMethod($config = null, $meta = null, $extraData = null) {
    $config // $config
    $meta // ['component' => 'someComponent', 'var' => 'abc']
    $extraData // [bar => 345]
    // Do Stuff
    return $config;
}

Todos

• Add PHPUnit Tests
• Add Types and Interfaces
• Review and optimize Performance
• Review PSR-7 for response
• Drink a Beer!