PHPackages                             realshadow/request-deserializer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. realshadow/request-deserializer

ActiveLibrary[API Development](/categories/api)

realshadow/request-deserializer
===============================

Package for providing JSON schema validation and request deserialization for API's built on top of Dingo API

1.0.1(8y ago)17MITPHPPHP ^5.6.0 || ^7.0

Since Jul 3Pushed 8y ago1 watchersCompare

[ Source](https://github.com/realshadow/request-deserializer)[ Packagist](https://packagist.org/packages/realshadow/request-deserializer)[ RSS](/packages/realshadow-request-deserializer/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependencies (9)Versions (2)Used By (0)

[![Scrutinizer Code Quality](https://camo.githubusercontent.com/3ed886aac9009081e8334e344007277c2fc35c1bc92aa16f0525a2b2717844be/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f7265616c736861646f772f726571756573742d646573657269616c697a65722f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/realshadow/request-deserializer/?branch=master)[![Build Status](https://camo.githubusercontent.com/cb20d6d76f493b8386a0b2128a14d14fbf8cfdbaa309e1b627e70a720b1fcb22/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f7265616c736861646f772f726571756573742d646573657269616c697a65722f6261646765732f6275696c642e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/realshadow/request-deserializer/build-status/master)

Request deserializer
====================

[](#request-deserializer)

Package for providing JSON schema validation and request deserialization for API's built on top of [Dingo API](https://github.com/dingo/api).

Installation
------------

[](#installation)

Since this package is built on top [Dingo API](https://github.com/dingo/api) it has to be installed first, see its installation instructions for details.

Now you can run

```
composer require realshadow/request-deserializer

```

Add package provider to list of providers in `app.php` configuration file

```
\Realshadow\RequestDeserializer\Providers\LaravelServiceProvider::class

```

and add the request deserialization middleware to Kernel

```
Realshadow\RequestDeserializer\Http\Middleware\RequestDeserializationMiddleware::class

```

And for the last step publish configuration files with

```
php artisan vendor:publish --provider="Realshadow\RequestDeserializer\Providers\LaravelServiceProvider

```

I should note that this package relies on [Purifier](https://github.com/mewebstudio/Purifier) package and if you are using it, you will have to update its configuration accordingly or use the `--force` option for publishing.

Usage
-----

[](#usage)

After you complete the installation steps you can add the `DeserializesRequests` trait to your controller. Now you can create a new schema and request object pair (see how it works section for more details).

How it works
------------

[](#how-it-works)

This package is built on top of [Dingo API](https://github.com/dingo/api) and combines two great packages - [JMS serializer](https://github.com/schmittjoh/serializer) and [JSON schema validator](https://github.com/justinrainbow/json-schema) to create a powerful validation and deserialization layer for all incoming requests.

Note: I will assume you are familiar with at least one of the required packages.

### Now for the actual magic

[](#now-for-the-actual-magic)

Middleware will catch every request and looks if the called method in controller expects any request object in its arguments. If its found the request will run trough 3 steps:

- data will be sanitized (cleaned by [HTML Purifier](https://github.com/mewebstudio/Purifier) and all special characters will be converted via **htmlspecialchars** method
- validated against provided JSON schema
- validated data will be deserialized into a request object

Basic request object looks like this

```
class PaginatedRequest implements RequestInterface
{

    /**
     * @var int $page
     *
     * @JMS\Since("1.x")
     * @JMS\Type("integer")
     * @JMS\SerializedName("page")
     */
    private $page;

    // If the request should be validated against schema or not
    public static function shouldValidate()
    {
        return true;
    }

    // Request version - this allows to use the same request for multiple API versions
    public static function getVersionConstraint()
    {
        return '1.0';
    }

    // Most important method - returns path to JSON schema this request should validate against
    public function getSchema()
    {
        return resource_path('schemas/foo.json');
    }

    /**
     * @return int
     */
    public function getPage()
    {
        return $this->page;
    }

}

```

Request object **must** implement `RequestInterface`. This interface contains three helper methods that will describe the request for us (see phpdoc in code above) and list of properties and their respective *getter* methods.

When the validation of a request fails, it will throw **HTTP 422 Validation Exception** with list of violated constraints.

### GET requests

[](#get-requests)

PHP will handle every parameter in query string as a *string*. In this case the validation process will use **type coercion**. Furthermore all passed data is deserialized to the correct type defined in request object.

### Caveats

[](#caveats)

Since all properties are *always* present in request objects (or any object for that matter) it is impossible to distinguish between properties that should have *null values* and properties that are not present in request body as they will always be null. You can get around it by using Laravels `Input` facade or any other viable method that works with the original request directly.

Configuration
-------------

[](#configuration)

Package contains two configuration files:

- modified configuration file for HTML purifier
- package configuration file

### Package configuration

[](#package-configuration)

Package configuration is merged so if you want to extend it just copy the required options from package configuration.

Cache directory for serializer can be configured in *.env* by setting *SERIALIZER\_STORAGE\_PATH* key.

Helper command
--------------

[](#helper-command)

Since creation of bigger request objects can become tedious this package includes a helper command that will generate a new request object from provided JSON schema. Usage is very simple

```
php artisan schema:convert {path to schema} {reqeust object}

// e.g.

php artisan schema:convert pagination.json PaginationRequest.php

```

JSON schema and created request are always relative to directories set in configuration including the namespace the request object will belong to.

Examples
--------

[](#examples)

In the example folder you can find two directories with request objects and their respecitive schemas - a simple request and a more complicated request with nested schema. These should work out of the box so it should be enough just to copy them to their respective folders (dont forget to add methods in routes!)

Furthermore you can [import a Postman collection](https://documenter.getpostman.com/view/273296/request-deserializer/6fVVjhS) with two example requests that will for with example schemas.

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

3237d ago

PHP version history (2 changes)1.0.0PHP >=5.6.0

1.0.1PHP ^5.6.0 || ^7.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/f031a679e7413a3d8be4b8f345524670bd0510b7e13ffbafc33a13b54bdf64c3?d=identicon)[realshadow](/maintainers/realshadow)

---

Top Contributors

[![realshadow](https://avatars.githubusercontent.com/u/6673222?v=4)](https://github.com/realshadow "realshadow (6 commits)")

---

Tags

deserializationjson-apijson-schemarequest

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/realshadow-request-deserializer/health.svg)

```
[![Health](https://phpackages.com/badges/realshadow-request-deserializer/health.svg)](https://phpackages.com/packages/realshadow-request-deserializer)
```

###  Alternatives

[php-opencloud/openstack

PHP SDK for OpenStack APIs. Supports BlockStorage, Compute, Identity, Images, Networking and Metric Gnocchi

2292.2M24](/packages/php-opencloud-openstack)[slince/shopify-api-php

Shopify API Client for PHP

131236.9k1](/packages/slince-shopify-api-php)[devizzent/cebe-php-openapi

Read and write OpenAPI yaml/json files and make the content accessable in PHP objects.

379.0M49](/packages/devizzent-cebe-php-openapi)[tomaj/nette-api

Nette api

36261.8k4](/packages/tomaj-nette-api)[dsc/mercado-livre

Client para integração com API do Mercado Livre

8138.7k](/packages/dsc-mercado-livre)[webit/w-firma-api

wFirma.pl API

1820.2k](/packages/webit-w-firma-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)