Format Class

The Format class helps you convert between various formats such as XML, JSON, CSV, etc.

Configuration

The Format class is configured through the fuel/core/config/format.php configuration file. It is already populated with a default configuration group. You can override this configuration by copying this config file to your application config directory, and modify that file as needed.

The following configuration settings can be defined:

CSV

Param Type Default Description
delimiter string 
','
 The field delimiter
enclosure string 
'"'
 The enclosure character
newline string 
'\n'
 The newline character used by to_csv() method
escape string 
'\\'
 The escape character

By default, these configuration settings are used both for import and for export of CSV data. In case you need to configure different settings for either import or export, you can an array key for it, and move the configuration in there. The default configuration file already has this setup for you.

regex_newline string 
'\n'
 The newline character used by regex to convert input data
enclose_numbers bool 
true
 If false, numbers will not be enclosed. If true, numbers will be enclosed too

XML

Param Type Default Description
basenode string 
'xml'
 XML basenode name
use_cdata boolean 
false
 Whether to use CDATA in nodes
bool_representation mixed 
null
 How booleans must be represented (0/1 vs false/true)

JSON

Param Type Default Description
options integer 
JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP
 json_encode() options

Be aware that the result of some combinations are unpredicable. For example, if you have CSV data without enclosure characters, no headings, and embedded newline characters in the first row, the correct number of fields in the file can not be calculated.

forge($data = null, $from_type = null, $params = null)

The forge method returns a new format object. $from_type supports 'xml', 'yaml', 'csv', 'json', 'serialize' and 'xml:ns'. 'xml:ns' allows you to parse fully namespaced-xml. When $from_type is not specified, $data will be delivered as it is.

Static Yes
Parameters
Param Default Description
$data 
null
 Data to be converted.
$from_type 
null
 Format of the data provided.
$param 
null
 Optional parameter to be passed on to the converter.
Returns Fuel\Core\Format Object
Example 
$array = array('foo' => 'bar');
print_r(Format::forge($array));

// Returns
Fuel\Core\Format Object
(
	[_data:protected] => Array
	(
		[foo] => bar
	)
)

When converting from CSV format, you can pass false as $param to indicate the CSV source does not contain any headers. If so, the end result will be an indexed array.

to_array($data = null)

The to_array method returns the given data as an array. Do not call this directly, use the forge method as described in the example.

Static No
Parameters
Param Default Description
$data 
null
 Data to be converted.
Returns array
Example 
$json_string = '{"foo":"bar","baz":"qux"}';
print_r(Format::forge($json_string, 'json')->to_array());

// Returns
Array
(
	[foo] => bar
	[baz] => qux
)

to_xml($data = null, $structure = null, $basenode = 'xml', $use_cdata = false)

The to_xml method returns the given data as an XML string. Do not call this directly, use the forge method as described in the example.

Static No
Parameters
Param Default Description
$data 
null
 Data to be converted.
$structure 
null
 Object of class SimpleXMLElement.
$basenode "xml" Basenode of XML markup.
$use_cdata false Whether to use CDATA in nodes.
Returns string
Example 
$array = array('foo' => 'bar', 'baz' => 'qux');
print_r(Format::forge($array)->to_xml());

// Returns
// <?xml version="1.0" encoding="utf-8"?>
// <xml>
// 	<foo>bar</foo>
// 	<baz>qux</baz>
// </xml>

to_csv($data = null, $delimiter = null, $enclose_numbers = null, array $headings = array())

The to_csv method returns the given data as a CSV string. Do not call this directly, use the forge method as described in the example.

Static No
Parameters
Param Default Description
$data 
null
 Data to be converted. If not given, the input of forge() is used.
$delimiter 
null
 CSV field separator. If not given, the configured default is used.
$enclose_numbers 
null
 If false, number will not be enclosed. If true, numbers will be enclosed too. If not given, the configured default is used.
$headings 
array()
 Array of CSV fieldnames. If not given, the fieldnames will be based on what is defined in the first row of the data array.
Returns string
Example 
$json_string = '{"foo":"bar","baz":"qux","nr":1}';
print_r(Format::forge($json_string, 'json')->to_csv(null, null, false));

// Returns
// "foo","baz","nr"
// "bar","qux",1

$json_string = '{"foo":"bar","baz":"qux","nr":1}';
print_r(Format::forge($json_string, 'json')->to_csv(null, null, false, array('this', 'that', 'num')));

// Returns
// "this","that","num"
// "bar","qux",1

to_json()

The to_json method returns the given data as a JSON string. Do not call this directly, use the forge method as described in the example.

Static No
Returns string
Example 
$array = array('foo' => 'bar', 'baz' => 'qux');
print_r(Format::forge($array)->to_json());

// Returns
// {"foo":"bar","baz":"qux"}

to_serialized()

The to_serialized method returns the given data as a serialized string. Do not call this directly, use the forge method as described in the example.

Static No
Returns string
Example 
$array = array('foo' => 'bar', 'baz' => 'qux');
print_r(Format::forge($array)->to_serialized());

// Returns
// a:2:{s:3:"foo";s:3:"bar";s:3:"baz";s:3:"qux";}

to_php()

The to_php method returns the given data as a PHP representation of the data in a string. You could pass this into eval() or use it for other crazy things.

Static No
Returns string
Example 
$array = array(1, 2, array('a', 'b', 'c'));
print_r(Format::forge($array)->to_php());

// Returns
Array
(
	0 => 1,
	1 => 2,
	2 => array(
		0 => 'a',
		1 => 'b',
		2 => 'c',
	),
)