Parser
Simple PHP Parser Library for API Development, parse a post http payload into a php array.
Also see the Responder library for handling output.
Installation
Begin by installing this package through Composer. From the Terminal:
composer require nathanmac/parser
Laravel/Lumen Users
| Laravel/Lumen Verison | Supported Library Verison |
|---|---|
| Laravel/Lumen 5+ | > 3.* |
| Laravel 4 | 2.* |
Laravel Users (Adding the Service Provider)
If you are a Laravel user, then there is a service provider that you can make use of to automatically prepare the bindings and such.
Include the service provider within app/config/app.php.
'providers' => [
...,
Nathanmac\Utilities\Parser\ParserServiceProvider::class
];And, for convenience, add a facade alias to this same file at the bottom:
'aliases' => [
...,
'Parser' => Nathanmac\Utilities\Parser\Facades\Parser::class,
];Lumen Users (Adding the Service Provider)
If you are a Lumen user, then there is a service provider that you can make use of to automatically prepare the binding and such.
// bootstrap/app.php
$app->register('Nathanmac\Utilities\Parser\ParserServiceProvider');Lumen users can also add the facade alias.
// bootstrap/app.php
class_alias('Nathanmac\Utilities\Parser\Facades\Parser', 'Parser');Using the Facade
public function index()
{
Parser::payload('application/json');
Parser::json($payload); // JSON > Array
Parser::xml($payload); // XML > Array
Parser::yaml($payload); // YAML > Array
Parser::querystr($payload); // Query String > Array
Parser::serialize($payload); // Serialized Object > Array
Parser::bson($payload); // BSON > Array
Parser::msgpack($payload); // MSGPack > Array
Parser::all(); // Return all values
Parser::has('key'); // Does a key exist, with value.
Parser::get('key', 'default value'); // Get value by key, set an optional default.
Parser::only('id', 'name', 'email'); // Only return value from the selected keys.
Parser::except('password'); // Don't return values from the selected keys.
Parser::mask($mask); // Return masked values (see Mask Function, below).
}All the examples below assume you aren't using Laravel (or Lumen), and therefore don't have access to the facade. As with any other facade, instead of:
$parser = new Parser();
$parser->{$method}($payload);just use:
Parser::{$method}($payload);Usage
Parsing Functions
$parser->json($payload); // JSON > Array
$parser->xml($payload); // XML > Array
$parser->yaml($payload); // YAML > Array
$parser->querystr($payload); // Query String > Array
$parser->serialize($payload); // Serialized Object > Array
$parser->bson($payload); // BSON > Array
$parser->msgpack($payload); // MSGPack > ArrayParse Input/Payload (PUT/POST)
$parser = new Parser();
$parser->payload(); // Auto Detect Type - 'Content Type' HTTP Header
$parser->payload('application/json'); // Specifiy the content typeHelper functions
$parser = new Parser();
$parser->all(); // Return all values
$parser->has('key'); // Does a key exist, with value.
$parser->get('key', 'default value'); // Get value by key, set an optional default.
$parser->only('id', 'name', 'email'); // Only return value from the selected keys.
$parser->except('password'); // Don't return values from the selected keys.
$parser->mask($mask); // Return masked values (see Mask Function, below).Mask function
The mask function processes payload data using a configuration mask, thereby returning only a selected subset of the data.
It works just like the only method but with the added benefit of allowing you to specify a mask in the form of an array,
this means you can generate masks on-the-fly based on system and/or user defined conditions.
Demo
Mask
Defining the mask, masks consist of basic array structure, for this particular example we have some rules for the data to be returned they include: - the title of the post - all the body's for all the comments.
$mask = [
'post' => [
'title' => '*',
'comments' => [
'body' => '*'
]
]
];Sample Payload
{
"post": {
"title": "Hello World",
"author": "John Smith",
"comments": [
{"body": "This is a comment", "date": "2015-02-20"},
{"body": "This is another comment", "date": "2015-05-09"}
]
}
}Applying the Mask
$parser = new Parser();
$output = $parser->mask($mask);Output
This is the output generated as a result of applying the mask against the sample payload provided above.
$output = [
'post' => [
'title' => 'Hello World',
'comments' => [
['body' => 'This is a comment'],
['body' => 'This is another comment']
]
]
];Wildcards/Special Keys (*, %, :first, :last, :index[0], :item[0])
$parser = new Parser();
$parser->has('message.*'); // Does a key exist, with value. (Wildcard key returns first item found)
$parser->get('message.*'); // Get value by key. (Wildcard key returns first item found)
$parser->has('message.:first'); // Does a key exist, with value. (:first key returns first item found)
$parser->get('message.:first'); // Get value by key. (:first key returns first item found)
$parser->has('message.:last'); // Does a key exist, with value. (:last key returns last item found)
$parser->get('message.:last'); // Get value by key. (:last key returns last item found)
$parser->has('message.:index[0]'); // Does a key exist, with value. (:index[0] key returns item at index 0)
$parser->get('message.:index[0]'); // Get value by key. (:index[0] key returns item at index 0)
$parser->has('message.:item[0]'); // Does a key exist, with value. (:item[0] key returns item at index 0)
$parser->get('message.:item[0]'); // Get value by key. (:item[0] key returns item at index 0)Parse JSON
$parser = new Parser();
$parsed = $parser->json('
{
"message": {
"to": "Jack Smith",
"from": "Jane Doe",
"subject": "Hello World",
"body": "Hello, whats going on..."
}
}');Parse XML
$parser = new Parser();
$parsed = $parser->xml('
<?xml version="1.0" encoding="UTF-8"?>
<xml xmlns:ns="http://example.com/xmlns">
<message status="sent">
<ns:meta hint="created">Created 5 minutes ago</ns:meta>
<to>Jack Smith</to>
<from>Jane Doe</from>
<subject>Hello World</subject>
<body>Hello, whats going on...</body>
</message>
</xml>');Parse Query String
$parser = new Parser();
$parsed = $parser->querystr('to=Jack Smith&from=Jane Doe&subject=Hello World&body=Hello, whats going on...');Parse Serialized Object
$parser = new Parser();
$parsed = $parser->serialize('a:1:{s:7:"message";a:4:{s:2:"to";s:10:"Jack Smith";s:4:"from";s:8:"Jane Doe";s:7:"subject";s:11:"Hello World";s:4:"body";s:24:"Hello, whats going on...";}}');Parse YAML
$parser = new Parser();
$parsed = $parser->yaml('
---
message:
to: "Jack Smith"
from: "Jane Doe"
subject: "Hello World"
body: "Hello, whats going on..."
');Parse BSON
$parser = new Parser();
$parsed = $parser->bson('BSON DATA HERE');Parse MSGPack
$parser = new Parser();
$parsed = $parser->msgpack('MSGPACK DATA HERE');Custom Parsers/Formatters
You can make your own custom parsers/formatters by implementing FormatInterface, the below example demostrates the use of a custom parser/formatter.
use Nathanmac\Utilities\Parser\Formats\FormatInterface;
/**
* Custom Formatter
*/
class CustomFormatter implements FormatInterface {
/**
* Parse Payload Data
*
* @param string $payload
*
* @return array
*
* @throws ParserException
*/
public function parse($payload)
{
$payload; // Raw payload data
$output = // Process raw payload data to array
return $output; // return array parsed data
}
}Using the CustomFormatter
use Acme\Formatters\CustomFormatter;
$parser = new Parser();
$parsed = $parser->parse('RAW PAYLOAD DATA', new CustomFormatter());Autodetecting the CustomFormatter
use Acme\Formatters\CustomFormatter;
$parser = new Parser();
$parser->registerFormat('application/x-custom-format', 'Acme\Formatters\CustomFormatter');
$parser->payload('application/x-custom-format');Testing
To test the library itself, run the tests:
composer test
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.
Appendix
Supported Content-Types
XML
---
application/xml > XML
text/xml > XML
JSON
----
application/json > JSON
application/x-javascript > JSON
text/javascript > JSON
text/x-javascript > JSON
text/x-json > JSON
YAML
----
text/yaml > YAML
text/x-yaml > YAML
application/yaml > YAML
application/x-yaml > YAML
BSON
----
application/bson > BSON
MSGPack
-------
application/msgpack > MSGPack
application/x-msgpack > MSGPack
MISC
----
application/vnd.php.serialized > Serialized Object
application/x-www-form-urlencoded' > Query String
