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

nathanmac / parser

Maintainers

Details