Download the PHP package kilylabs/phprest without Composer

Kily Labs

Added PHP 7.0 support!

Phprest

Description

REST-like PHP micro-framework.

It's based on the Proton (StackPhp compatible) micro-framework.

Phprest gives you only the very basics to build your own architecture within your own framework and assemble any folder structure you like. It is just a thin layer around your application with the help of some great libraries.

Components

• League\Container
• League\Route
• League\Event
• League\BooBoo
• Willdurand\Negotiation
• Willdurand\Hateoas
• Monolog\Monolog
• Stack\Builder

Skills

• Dependency injection
• Routing
• Error handling
• Serialization
• Deserialization
• HATEOAS
• API versioning
• Pagination
• Logging

ToC

• Installation
• Usage
  • Services
  • Setup
    • Configuration
    • Logging
    • Usage with Stack
  • API versioning
  • Routing
    • Simple routing
    • Routing with arguments
    • Routing through a controller
    • Routing through a service controller
    • Routing with annotations
  • Controller
  • Serialization, Deserialization, HATEOAS
    • Serialization example
    • Deserialization example
  • Pagination
  • Responses
    • 1xx, 2xx, 3xx status codes
      • Example
      • Types
    • 4xx, 5xx status codes
      • Example
      • Types
  • Dependency Injection Container
  • CLI
• Error handler
  • On a single exception
• Authentication
  • Basic Authentication
  • JWT Authentication
• API testing
• API documentation

Installation

Install it through composer.

tip: you should browse the phprest/phprest page to choose a stable version to use, avoid the @stable meta constraint.

Usage

Services

There are a couple of services which can help you to solve some general problems:

• Validator
• Request Filter
• Orm

These are separate repositories.

Setup

Configuration

You should check the Config class.

Logging

Usage with Stack

You can register middlewares trough the function.

API Versioning

Phprest works with API versions by default. This means that the ApiVersion Middleware manipulates the incoming request. The version (based on the current Accept header) is added to the path.

What does it mean?

* It is not a redirect or a forward method, it is just an inner application routing through a middleware.

API Version only can be one of the following ranges:

• 0 - 9
• 0.0 - 9.9

• If Accept header is not parsable

  • then Phprest throws a Not Acceptable exception
• If you do a deserialization and Content-Type header is not parsable
  • then Phprest throws an Unsupported Media Type exception

Routing

For more information please visit League/Route.

Simple routing

• The ApiVersion Middleware manipulates the inner routing every time, so you have to care about the first part of your route as a version number.
• This route is available in all API versions (see the regular expression)
• You can set a fix API version number too e.g.

Routing with arguments

• This route is available only in API version 2.4

Routing through a controller

Routing through a service controller

Routing with annotations

You have to register your controller.

• tag is optional
• tag is optional

Controller

To create a Phprest Controller simply extends your class from .

Serialization, Deserialization, Hateoas

• Phprest will automatically serialize* your response based on the Accept header.
• Phprest can deserialize your content based on the Content-Type header.

Except*:

• If your response is not a Response instance (e.g. it a simple string)
• If your response is empty

Serialization example

Let's see a Temperature entity:

You do not have to use annotations! You can use configuration files! Browse in Jms\Serializer and Willdurand\Hateoas

The router:

Json response (Accept: application/vnd.vendor+json; version=1):

Xml response (Accept: application/vnd.vendor+xml; version=1):

Properties will be translated from camel-case to a lower-cased underscored name, e.g. camelCase -> camel_case by default. If you want to use a custom serialized name you have to use the @SerializedName option on your attribute.

Deserialization example

You have to use the HATEOAS Util trait in your controller to do deserialization.

Pagination

For more informations please visit the HATEOAS docs

Responses

There are several responses you can use by default, one of them is the Ok response.

1xx, 2xx, 3xx status codes

These are simple Response objects.

Example

Types

4xx, 5xx status codes

These are Exceptions.

Example

Types

Dependency Injection Container

See Proton's doc and for more information please visit League/Container.

CLI

You can use a helper script if you want after a composer install ().

You have to provide the (bootstrapped) app instance for the script. You have two options for this:

• Put your app instance to a specific file:
  • You have to return with the bootstrapped app instance in the proper file
• Put the path of the app instance in the file
  • You have to return with an array from the file with the app file path under the array key

Error handler

Phprest handles error with League\BooBoo. The default formatter is Json and Xml Formatter.

On a single exception

The response is content negotiationed (xml/json), the status code is 503.

Authentication

Basic Authentication

You'll need this package:

• Dflydev\Dflydev-stack-basic-authentication

JWT Authentication

You'll need this package:

• Jsor\Stack-jwt

API testing

There are a couple of great tools out there for testing your API.

• Postman and Newman
  • Tip: Create collections in Postman and then run these in Newman
• Frisby
  • Frisby is a REST API testing framework built on node.js and Jasmine that makes testing API endpoints easy, fast, and fun.
• Runscope
  • For Api Monitoring and Testing

API documentation

Just a few recommendations:

• API Blueprint
  • API Blueprint is a documentation-oriented API description language. A couple of semantic assumptions over the plain Markdown.
• Swagger
  • With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.