synapsestudios/synapse-base

Base code for the API template

Wednesday, January 25, 2017
by synapsestudios
Repository
35 Watchers
2 Stars
10,998 Installations

PHP
1 Dependents
0 Suggesters
4 Forks
21 Open issues
68 Versions
0 % Grown

The README.md

Synapse Base

, _(*1)

Overview

Synapse Base is a bootstrapping library for PHP applications build in the Silex microframework. It's intended for REST APIs that serve and consume JSON., _(*2)

This library provides an opinionated, secure starting point for your REST API using the following tools and libraries:, _(*3)

Silex
bshaffer's OAuth2 server
Zend DB
chrisboulton's php-resque
Mandrill PHP SDK for emails
Symfony's Console, Security, and Validator components
Monolog for logging
And many others

Setting up your Project

Quick Start

For new projects, just clone the API Template as a starting point and composer install., _(*4)

Expectations of the Library

Architectural Expectations

A MySQL server for app data
A Redis server for job queues

Project Codebase Expectations

(If you just use API Template, you don't need to know most of this.), _(*5)

Some named constants are expected to exist.
The APP_ENV environment variable should be set. (To development, production, or staging.)
Specific config files should be set up in [APPDIR]/config/. To set up environment-specific configuration overrides, put identical config files in [APPDIR]/config/development/, etc. See API Template for examples.

Setting Up Required Config Files

The default config files contain sufficient documentation in DocBlocks. Just read those., _(*6)

Database Interaction

Database Installs and Migrations

Use the console utility in API Template to perform DB installs and migrations., _(*7)

Install a clean copy of the database: ./console install:run --drop-tables
Create a migration: ./console migrations:create "Add inventory table"
Install any migrations that haven't been applied: ./console migrations:run (Or just ./console install:run)
Generate a new database install file from the current state of the database: ./console install:generate

When you create a new migration, it's created in [APPDIR]/src/Application/Migrations/. Use the Zend DB Adapter to perform queries like this., _(*8)

Note about Generating a Database Install File: When you run ./console install:generate, it generates 2 files -- (1) a DbStructure.sql file with the table structure based on the current snapshot of your database, and (2) a DbData.sql file with data from specific tables. Specify which tables in the install config., _(*9)

How to Read/Write from the Database

Use Mappers like this to perform database queries. Database results are returned as Entities., _(*10)

bshaffer's OAuth2 server is used for authentication. The user POSTs to /oauth/token with their email/password and receives an access token which can be used to make requests. (Per the OAuth2 specification.), _(*11)

In order to secure endpoints, the Symfony Security module is used. Firewalls are used to constrain an endpoint to logged in users or to make it public. Access Rules are used to make an endpoint accessible only to users with certain roles. Read the Symfony Security docs for more details., _(*12)

Notes:, _(*13)

When you specify a listener in a firewall ('anonymous' => true, 'oauth-optional' => true), the code that runs is in the Listeners. (These are added in the OAuth2\SecurityServiceProvider.)
There is a catch-all firewall that constrains all endpoints to be protected by OAuth (non-public) unless specified otherwise. More details here.

Utility Classes

Array Helper

$people = [
    ['name' => 'Linus',   'age' => 10],
    ['name' => 'Brendan', 'age' => 11],
    ['name' => 'Rasmus',  'age' => 12, 'colors' => ['Red', 'Green', 'Blue']],
];

Arr::get($people[0], 'name');     // Linus
Arr::get($people[3], 'name');     // null
Arr::pluck($people, 'name');      // ['Linux', 'Brendan', 'Rasmus'];
Arr::path($people, '2.colors.1'); // Green

DataObject

Use these to encapsulate concepts and typehint them in your app., _(*14)

class Car extends DataObject
{
    protected $object = [
        'make'    => null,
        'model'   => null,
        'year'    => null,
        'totaled' => false,
    ];
}

$car = new Car(['make' => 'Toyota']);
$car->setModel('Corolla');
$car->getMake();    // Toyota
$car->getModel();   // Corolla
$car->getYear();    // null
$car->getTotaled(); // false

// These are helpful for typehinting purposes to make your code more robust
function purchaseCar(Car $car) {
    // Do stuff
}

Test Helpers

Various abstract PHPUnit test cases are available for controllers, mappers, etc., to make it easier to test them., _(*15)

The Versions

25/01 2017

dev-master

9999999-dev

Base code for the API template

library synapse-base

Base code for the API template

synapsestudios/synapse-base

The README.md

Synapse Base

Overview

Setting up your Project

Quick Start

Expectations of the Library

Architectural Expectations

Project Codebase Expectations

Setting Up Required Config Files

Database Interaction

Database Installs and Migrations

How to Read/Write from the Database

Authentication / Login System

Utility Classes

Array Helper

DataObject

Test Helpers

The Versions

dev-master

The Requires

The Development Requires

v5.0.5

The Requires

The Development Requires

v5.0.4

The Requires

The Development Requires

v5.0.3

The Requires

The Development Requires

v5.0.2

The Requires

The Development Requires

v5.0.1

The Requires

The Development Requires

dev-mailgun-sender-fixes

The Requires

The Development Requires

v5.0.0

The Requires

The Development Requires

dev-test-monolog-version

The Requires

The Development Requires

v4.1.1

The Requires

The Development Requires

v4.1.0

The Requires

The Development Requires

dev-release/4.1.0

The Requires

The Development Requires

v4.0.6

The Requires

The Development Requires

v4.0.5

The Requires

The Development Requires

v4.0.4

The Requires

The Development Requires

v2.0.1

The Requires

The Development Requires

dev-feature/225-configurable-rollbar-threshold

The Requires

The Development Requires

v4.0.3

The Requires

The Development Requires

v4.0.2

The Requires

The Development Requires

v4.0.1

The Requires