fathomminds/php-rest-models

Framework independent PHP REST models with schema validation and multiple database engine support.

1.5.1 2018-06-15 14:37 UTC

Requires

• php: >=7.0
• guzzlehttp/guzzle: ^6.2
• vlucas/phpdotenv: ~2.2

Requires (Dev)

• aws/aws-sdk-php: ^3.24
• clusterpoint/php-client-api-v4: dev-master
• mockery/mockery: ~0.9
• mongodb/mongodb: ^1.0.0
• phpunit/phpunit: ^6.0

MIT

• Csaba Petrás
• Fathom Minds
• Péter Petrás

• mongodb
• rest
• api
• aws
• dynamodb
• laravel
• models
• clusterpoint
• lumen

README

PHP REST MODELS

Framework independent PHP REST models with schema validation and multiple database engine support.

IMPORTANT!

Clusterpoint support is discontinued. Currently only the MongoDB support is actively developed and supported. DynamoDB and Clusterpoint codes are deprecated and will be removed.

Database engines supported

• MongoDB
• Clusterpoint
• DynamoDB

Usage

1. DEFINE THE SCHEMA: Define schema in a single location How to create a schema?
2. DEFINE THE REST OBJECT: Set the corresponding Schema and define the database properties (table name, primary key, indexes) How to create a REST Object?
3. DEFINE THE MODEL: Simply set the corresponding REST Object How to create a Model?
4. IMPLEMENT BUSINESS LOGIC: the package implements the CRUD operations, so your Model is clean and you can focus on the application behaviour How to implement the business logic?
5. USE THE MODELS in your application How to use the Models?
6. ENABLE IDE AUTOCOMPLETION How to enable IDE autocompletion?
7. DO SIMPLE PAGINATION AND FILTERING How to do simple pagination and filtering
8. EXECUTE CUSTOM QUERIES How to execute custom queries

Features

• REST operations (GET, POST, PUT, DELETE) implemented for the supported databases under the hood
• Basic model operations with a simple API (Model API):
  • Model::create()
  • Model::update()
  • Model::replace()
  • Model::one($resourceId)
  • Model::all()
  • Model::delete()
  • Model::validate()
  • Model::resource($resource)
  • Model::toArray()
  • Model::find()
  • Model::query()
• IDE autocompletion friendly
  • Schema rules and property hints for IDEs in single file
• Filtering and pagination (Finder API)
  • MongoDB
  • Clusterpoint
  • DynamoDb
  • Finder::database($databaseName)
  • Finder::select($fieldNamesArray)
  • Finder::from($collectionName)
  • Finder::where($whereConditions)
  • Finder::orderBy($fieldName, $sortMode = 'ASC')
  • Finder::limit($limit)
  • Finder::offset($offset)
  • Finder::get()
  • Finder::first()
  • Finder::all()
• Custom queries
  • MongoDb
  • Clusterpoint
  • DynamoDb
• Easily customizable model behaviour
  • add any business logic
  • extend the schema validation with consistency validation
  • write complex queries in model methods directly with the database API to maximize performance
• Easily customizable schema validation
  • validators can implement any complex rules of your choice
  • use base validator classes from the package and extend them as you need
• JOINS AND RELATIONS BETWEEN MODELS ARE INTENTIONALLY NOT PART OF THE IMPLEMENTATION

Model API reference

Model API

Finder API

Example application

Todo Application: REPOURL

Requirements

• PHP 7+
• Composer
• Use with Clusterpoint: Clusterpoint V4 PHP client
• Use with DynamoDB: AWS SDK for PHP
• Use with MongoDB: PHP MongoDB driver
• For generating code coverage report: Xdebug PHP extension

Install

composer require fathomminds/php-rest-models

You must install the Database Engine specific packages in your project. (Left out from dependencies intentionally to allow installing only the required one.)

If you use Clusterpoint: composer require clusterpoint/php-client-api-v4

If you use DynamoDb: composer require aws/aws-sdk-php

If you use MongoDB: composer require mongodb/mongodb

Configuration

• Use with Clusterpoint: Clusterpoint configuration
• Use with DynamoDB: DynamoDb configuration
• Use with MongoDB: MongoDB configuration

Contribution

• Fork the repository
• Make modifications in the code
• Create a pull request targeting develop branch
• Provide a meaningful description what the changes do and why they are needed
• Don't forget to write unit tests
• Pull Request best practices

Running tests

Clone the repository and install dependencies:

composer install

Run unit tests:

vendor/bin/phpunit

Test coverage report is logged to folder: log

Run integration tests:

vendor/bin/phpunit --configuration phpunit-integration-test.xml

Integration tests will interact with real databases. You need to follow the configuration steps to be able to run these tests. The tests use the example FooSchema class for both databases. Please make sure the required objects (tables and indexes) are created before executing integration tests.

HOW TO

• Create a Schema?
• Create a Rest Object?
• Create a Model?
• Implement business logic?
• Use the models?
• Enable IDE autocompletion?
• Create and use a DynamoDb secondary index?
• Allow undefined schema fields?
• Do simple pagination and filtering
• Execute custom queries

License

Licensed under the MIT license. See LICENSE