Note: This package is a fork and may / may not be maintained independently depending on whether the original maintainer starts maintaining his source as of 4/18/2018. Please use with caution and Watch the source repo for updates.
All the documentation below should still be relevant although items such as build status may not reflect reality for this fork.
Simple PHP Parser Library for API Development, parse a post http payload into a php array.
Also see the Responder library for handling output.
Begin by installing this package through Composer. From the Terminal:
composer require peterdkc/parser
| Laravel/Lumen Verison | Supported Library Verison |
|---|---|
| Laravel/Lumen 5+ | > 3.* |
| Laravel 4 | 2.* |
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'
];And, for convenience, add a facade alias to this same file at the bottom:
'aliases' => [
'...',
'Parser' => 'Nathanmac\Utilities\Parser\Facades\Parser',
];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');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);$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 = new Parser();
$parser->payload(); // Auto Detect Type - 'Content Type' HTTP Header
$parser->payload('application/json'); // Specifiy the content type$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).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.
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' => '*'
]
]
];{
"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"}
]
}
} $parser = new Parser();
$output = $parser->mask($mask);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']
]
]
];$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)$parser = new Parser();
$parsed = $parser->json('
{
"message": {
"to": "Jack Smith",
"from": "Jane Doe",
"subject": "Hello World",
"body": "Hello, whats going on..."
}
}');$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>');$parser = new Parser();
$parsed = $parser->querystr('to=Jack Smith&from=Jane Doe&subject=Hello World&body=Hello, whats going on...');$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...";}}');$parser = new Parser();
$parsed = $parser->yaml('
---
message:
to: "Jack Smith"
from: "Jane Doe"
subject: "Hello World"
body: "Hello, whats going on..."
');$parser = new Parser();
$parsed = $parser->bson('BSON DATA HERE');$parser = new Parser();
$parsed = $parser->msgpack('MSGPACK DATA HERE');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
}
}use Acme\Formatters\CustomFormatter;
$parser = new Parser();
$parsed = $parser->parse('RAW PAYLOAD DATA', new CustomFormatter());use Acme\Formatters\CustomFormatter;
$parser = new Parser();
$parser->registerFormat('application/x-custom-format', 'Acme\Formatters\CustomFormatter');
$parser->payload('application/x-custom-format');To test the library itself, run the tests:
composer test
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see License File for more information.
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