nathanmac / parser
Simple PHP Parser Utility Library for API Development
Installs: 966 846
Dependents: 5
Suggesters: 0
Security: 0
Stars: 213
Watchers: 13
Forks: 53
Open Issues: 13
Requires
- php: >=5.3.0
- symfony/yaml: ~2.0|~3.0
Requires (Dev)
- illuminate/support: ~5.0
- mockery/mockery: 0.9.3
- phpunit/phpunit: 4.*
- scrutinizer/ocular: ^1.1
This package is not auto-updated.
Last update: 2024-11-09 15:44:58 UTC
README
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 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 > Array
Parse Input/Payload (PUT/POST)
$parser = new Parser(); $parser->payload(); // Auto Detect Type - 'Content Type' HTTP Header $parser->payload('application/json'); // Specifiy the content type
Helper 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