Respect\Conversion

The most awesome conversion engine ever written for PHP.

Featuring:

Built-in support for many data formats: tree, collection, table, chart, image, xml, etc.
Fluent interface like Converter::table()->col(2)->remove(); and Converter::chart()->rowSeries("Income")->line("red")
Seamless convertion between formats: tree to collection, table to tree, collection to chart, collection to xml, chart to image, etc...

Disclaimer: Not all features described here are implemented, some of them are incomplete and unfinished. They're all marked as TODO when appropriate. Coding standards are also sloppy, we're going to fix that.

Please get in touch if you want to help or if you have any feedback.

Installation

For now, clone our repo and set up a PSR-0 autoloader for the source folder. Composer and PEAR packages are on their way!

Configuration

Just import our namespace:

<?php
use Respect\Conversion\Converter;

Feature Guide

Let's start with a small sample. We're going to remove the third item from an array:

$data = array('foo', 'bar', 'baz');     //Data being transformed
$result = Converter::collection()       //Type dimension
		               ->item(2)        //Selector
		                   ->delete()   //Operator
		           ->transform($data);  //The conversion method

print_r($result); //array('foo', 'bar') //The result

The type dimensions tell selectors and operators how to behave. The delete() operator for instance needs to know if it is acting on a table row, or a collection item, or a XML tag.

Selectors tell operators in which part of the data input they're gonna operate. In the sample above, we're going to operate on the third item of a collection.

Operators, finally, act on a selected part of the input data and transform it.

Let's see a better sample:

$data = array(
	array('id' => 0, 'first_name' => 'Foo', 'last_name' => 'Bar'),
	array('id' => 1, 'first_name' => 'Lorem', 'last_name' => 'Ipsum'),
	array('id' => 2, 'first_name' => 'John', 'last_name' => 'Doe'),
);
$result = Converter::table()                            //Operating in the table dimension
                       ->col("id")                      //Select the column "id"
                           ->delete()                   //And delete it.
                       ->td(array(null, "first_name"))  //Select the cells from the column "first_name"
                       	   ->append(" ")                //And append a " " (blank space)
                       ->col("first_name", "last_name") //Select the "first_name" and "last_name" columns
                           ->hydrate("name")            //Join them with an array of their two cells as "name"
                       ->td(array(null, "name"))        //Select the "name" cells from any row
                           ->callback('implode')        //Implode the containing array
                       ->col("name")                    //Select the column "name"
                       	   ->up()                       //Make the selected column the transformed data
                       ->transform($data);              //Effectively apply the transformations
print_r($result); //array('Foo Bar', 'Lorem Ipsum',     //
                                          'John Doe');  //The Result

In the sample above, we've operated in the table dimension to transform data and extract the raw full names from a table array.

Respect\Conversion works on four main component types:

Operators, that really to the conversion work.
Selectors, that allow targeting the data being converted.
Types, the converting dimensions of data being transformed.
The Converter, that knows how to use the components above.

Let's try a hardcore sample (illustrative, code not implemented yet for this):

$data = array(
	'All' => array('investment' => 32.0, 'income' => 26.5)
	'A'   => array('investment' => 12.0, 'income' => 6.5),
	'B'   => array('investment' => 9.0,  'income' => 5.5),
);
$result = Converter::chart()                 //Operate the table as a dataseries for a chart
                       ->rowSeries("All")    //Select the first row series
                       	   ->line("#000", 3) //Make it a black chart line with 3px width
                       ->rowSeries("A", "B") //Select all row series
                           ->line(null, 1)   //Make them a line chart with random color and 1px width
                   ->image()                 //Operate on the image dimension
                   	   ->background()        //Select the image background
                   	       ->color("white")  //Make the background white (default is transparent)
                       ->frames()            //Select all frames (all lines from chart)
                           ->flatten()       //Merge lines into a single image
                   	   ->canvas()            //Select the canvas
                   	       ->grow(20, 20)    //Grow it by 20px, simulating a 10px border
                   	   ->format()            //Select the format
                   	       ->type('png')     //Make it PNG
                   ->transform($data);       //Effectively apply the transformations

This will generate this image:

//TODO CODE AND SAMPLE

On the Collection dimension we operate on a list of things. Possible selectors and operators:

Item

Selects all items.

$data = array('foo', 'bar', 'baz'); //Sample data

$result = Converter::collection()             //Collection dimension
                       ->item()               //Selects all items
                           ->{$operator}()    //Apply some operator
                   ->transform($data);        //Effectively apply the transformations

Item($key[, $key[, $key...]])

Selects an item from its key.

$data = array('foo', 'bar', 'baz', 'lorem' => 'ipsum'); 

$result = Converter::collection()             //Collection dimension
                       ->item(1)              //Selects only the item 1 (bar)
                           ->{$operator}()    //Apply some operator
                   ->transform($data);        //Effectively apply the transformations

Another Selector samples are:

		  		       ->item("lorem")        //Selects only the item named lorem

		  		       ->item("lorem", 0)     //Selects the item lorem and the item 0

Item($callback[, $callback[, $callback...]])

Selects an item matching a callback function.

$data = array('foo', 'bar', 'baz', 'lorem' => 'ipsum'); 
$strlen3   = function($item) { return strlen($item) === 3; };
$containsr = function($item) { return false !== stripos('r', $item); };

$result = Converter::collection()             //Collection dimension
		               ->item($strlen3)       //Selects only items with 3 letters in value
		  		     	  ->{$operator}()     //Apply some operator
		  		   ->transform($data);        //Effectively apply the transformations

Another selector samples: ->item($containsr) //Selects only items with the 'r' letter

		               ->item($strlen3, 
			                     $containsr)  //Selects only items with three letters and an 'r'

Using Respect\Validation create() utility you can create callbacks that matches several patterns including v::odd(), v::even(), v::multipleOf() and more specific ones like v::object()->attribute('name') (item must be an object with the attribute name).

use Respect\Validation\Validator as v;

$validateOdd = v::create(null, null, v::odd()); //closure for $item, $key, $lineNo

$result = Converter::collection()             //Collection dimension
			           ->item($validateOdd)   //Selects only odd items
		  		     	  ->{$operator}()     //Apply some operator
		  		   ->transform($data);        //Effectively apply the transformations

Item($mixed[, $mixed[, $mixed...]])

$result = Converter::collection()             //Collection dimension
		               ->item(0, $cb2)        //Selects the item 0 and elements with the 'r' letter
		  		     	  ->{$operator}()     //Apply some operator
		  		   ->transform($data);        //Effectively apply the transformations

Item(x) + Item(y) == Item(x,y)

An item called after an item...

Converter::collection()
             ->item(0)
             ->item(1)

...binds to an item with both their arguments equivalent to:

Converter::collection()
             ->item(0,1)

Bounding also occours with Table\First and Table\Last.

Item\Append($string)

Appends a string at the end of the item value.

$data = array('foo', 'bar', 'baz'); //Sample data

$result = Converter::collection()             //Collection dimension
                       ->item()               //Selects all items
                           ->append('0')      //Appends a zero at the end
                   ->transform($data);        //Effectively apply the transformations
                
print_r($result); //array('foo0', 'bar0', 'baz0')

Item\Callback($callback)

Applies a callback at any item.

$data = array('foo', 'bar', 'baz'); //Sample data

$result = Converter::collection()             //Collection dimension
                       ->item()               //Selects all items
                           ->callback(
                               		'strrev') //Reverses their content
                   ->transform($data);        //Effectively apply the transformations
                
print_r($result); //array('oof', 'rab', 'zab')

Conversion

Install / Use

README