classes/format.html

<!doctype html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" href="./../assets/css/combined.css?20170912">
	<link rel="shortcut icon" href="./../favicon.ico" />
	<script src="https://www.google.com/jsapi" type="text/javascript"></script>
	<script type="text/javascript">
		var path = './../';
		var class_prefix = "Form::";
	</script>
	<script src="./../assets/js/combined.js?20170912"></script>
	<title>Format - Classes - FuelPHP Documentation</title>
</head>
<body>
	<div id="container">
		<header id="header">
			<div class="table">
				<div id="cse">
					<gcse:searchbox-only newWindow="true"></gcse:searchbox-only>
				</div>
				<h1>
					<a href="https://fuelphp.com"><img height="37px" width="147px" src="./../assets/img/fuel.png" /></a>
					<strong>Documentation</strong>
				</h1>
			</div>
			<nav>
				<div class="clear"></div>
			</nav>
			<a href="#" id="toc_handle">table of contents</a>
			<div class="clear"></div>
		</header>

		<div id="main">

			<h2>Format Class</h2>
			<p>The Format class helps you convert between various formats such as XML, JSON, CSV, etc.</p>

			<article>
				<h3 id="configuration">Configuration</h3>

				<p>The Format class is configured through the <kbd>fuel/core/config/format.php</kbd> 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.</p>
				<p>The following configuration settings can be defined:</p>

				<h4>CSV</h4>
				<table class="config">
					<tbody>
						<tr class="header">
							<th>Param</th>
							<th>Type</th>
							<th>Default</th>
							<th>Description</th>
						</tr>
						<tr>
							<th>delimiter</th>
							<td>string</td>
							<td><pre class="php"><code>','</code></pre></td>
							<td>The field delimiter</td>
						</tr>
						<tr>
							<th>enclosure</th>
							<td>string</td>
							<td><pre class="php"><code>'"'</code></pre></td>
							<td>The enclosure character</td>
						</tr>
						<tr>
							<th>newline</th>
							<td>string</td>
							<td><pre class="php"><code>'\n'</code></pre></td>
							<td>The newline character used by to_csv() method</td>
						</tr>
						<tr>
							<th>escape</th>
							<td>string</td>
							<td><pre class="php"><code>'\\'</code></pre></td>
							<td>The escape character</td>
						</tr>
					</tbody>
				</table>
				<p>
					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.
				</p>

				<table class="config">
					<tbody>
						<tr>
							<th>regex_newline</th>
							<td>string</td>
							<td><pre class="php"><code>'\n'</code></pre></td>
							<td>The newline character used by regex to convert input data</td>
						</tr>
						<tr>
							<th>enclose_numbers</th>
							<td>bool</td>
							<td><pre class="php"><code>true</code></pre></td>
							<td>If false, numbers will not be enclosed. If true, numbers will be enclosed too</td>
						</tr>
					</tbody>
				</table>

				<h4>XML</h4>
				<table class="config">
					<tbody>
						<tr class="header">
							<th>Param</th>
							<th>Type</th>
							<th>Default</th>
							<th>Description</th>
						</tr>
						<tr>
							<th>basenode</th>
							<td>string</td>
							<td><pre class="php"><code>'xml'</code></pre></td>
							<td>XML basenode name</td>
						</tr>
						<tr>
							<th>use_cdata</th>
							<td>boolean</td>
							<td><pre class="php"><code>false</code></pre></td>
							<td>Whether to use CDATA in nodes</td>
						</tr>
						<tr>
							<th>bool_representation</th>
							<td>mixed</td>
							<td><pre class="php"><code>null</code></pre></td>
							<td>How booleans must be represented (0/1 vs false/true)</td>
						</tr>
					</tbody>
				</table>

				<h4>JSON</h4>
				<table class="config">
					<tbody>
						<tr class="header">
							<th>Param</th>
							<th>Type</th>
							<th>Default</th>
							<th>Description</th>
						</tr>
						<tr>
							<th>options</th>
							<td>integer</td>
							<td><pre class="php"><code>JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP</code></pre></td>
							<td>json_encode() options</td>
						</tr>
					</tbody>
				</table>
			</article>

			<p class="note">
				 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.
			</p>

			<article>
				<h4 class="method" id="method_forge">forge($data = null, $from_type = null, $params = null)</h4>
				<p>The <strong>forge</strong> method returns a new format object. <strong>$from_type</strong> supports <strong>'xml'</strong>, <strong>'yaml'</strong>, <strong>'csv'</strong>, <strong>'json'</strong>, <strong>'serialize'</strong> and <strong>'xml:ns'</strong>. 'xml:ns' allows you to parse fully namespaced-xml. When $from_type is not specified, <strong>$data</strong> will be delivered as it is.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$data</kbd></th>
									<td><pre class="php"><code>null</code></pre></td>
									<td>Data to be converted.</td>
								</tr>
								<tr>
									<th><kbd>$from_type</kbd></th>
									<td><pre class="php"><code>null</code></pre></td>
									<td>Format of the data provided.</td>
								</tr>
								<tr>
									<th><kbd>$param</kbd></th>
									<td><pre class="php"><code>null</code></pre></td>
									<td>Optional parameter to be passed on to the converter.</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Fuel\Core\Format Object</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$array = array('foo' => 'bar');
print_r(Format::forge($array));

// Returns
Fuel\Core\Format Object
(
	[_data:protected] => Array
	(
		[foo] => bar
	)
)</code>
							</pre>
						</td>
					</tr>
					</tbody>
				</table>
				<p class="note">
						When converting from CSV format, you can pass <kbd>false</kbd> as <kbd>$param</kbd> to indicate the CSV source does not contain any headers. If so, the end result will be an indexed array.
				</p>
			</article>

			<article>
				<h4 class="method" id="method_to_array">to_array($data = null)</h4>
				<p>The <strong>to_array</strong> method returns the given data as an array. Do not call this directly, use the <strong>forge</strong> method as described in the example.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$data</kbd></th>
									<td><pre class="php"><code>null</code></pre></td>
									<td>Data to be converted.</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>array</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$json_string = '{"foo":"bar","baz":"qux"}';
print_r(Format::forge($json_string, 'json')->to_array());

// Returns
Array
(
	[foo] => bar
	[baz] => qux
)</code>
							</pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_to_xml">to_xml($data = null, $structure = null, $basenode = 'xml', $use_cdata = false)</h4>
				<p>The <strong>to_xml</strong> method returns the given data as an XML string. Do not call this directly, use the <strong>forge</strong> method as described in the example.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$data</kbd></th>
									<td><pre class="php"><code>null</code></pre></td>
									<td>Data to be converted.</td>
								</tr>
								<tr>
									<th><kbd>$structure</kbd></th>
									<td><pre class="php"><code>null</code></pre></td>
									<td>Object of class SimpleXMLElement.</td>
								</tr>
								<tr>
									<th><kbd>$basenode</kbd></th>
									<td>"xml"</td>
									<td>Basenode of XML markup.</td>
								</tr>
								<tr>
									<th><kbd>$use_cdata</kbd></th>
									<td>false</td>
									<td>Whether to use CDATA in nodes.</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>string</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$array = array('foo' => 'bar', 'baz' => 'qux');
print_r(Format::forge($array)->to_xml());

// Returns
// &lt;?xml version="1.0" encoding="utf-8"?&gt;
// &lt;xml&gt;
// 	&lt;foo&gt;bar&lt;/foo&gt;
// 	&lt;baz&gt;qux&lt;/baz&gt;
// &lt;/xml&gt;</code>
							</pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_to_csv">to_csv($data = null, $delimiter = null, $enclose_numbers = null, array $headings = array())</h4>
				<p>The <strong>to_csv</strong> method returns the given data as a CSV string. Do not call this directly, use the <strong>forge</strong> method as described in the example.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tr>
									<th>Param</th>
									<th>Default</th>
									<th class="description">Description</th>
								</tr>
								<tr>
									<th><kbd>$data</kbd></th>
									<td><pre class="php"><code>null</code></pre></td>
									<td>Data to be converted. If not given, the input of forge() is used.</td>
								</tr>
								<tr>
									<th><kbd>$delimiter</kbd></th>
									<td><pre class="php"><code>null</code></pre></td>
									<td>CSV field separator. If not given, the configured default is used.</td>
								</tr>
								<tr>
									<th><kbd>$enclose_numbers</kbd></th>
									<td><pre class="php"><code>null</code></pre></td>
									<td>If false, number will not be enclosed. If true, numbers will be enclosed too. If not given, the configured default is used.</td>
								</tr>
								<tr>
									<th><kbd>$headings</kbd></th>
									<td><pre class="php"><code>array()</code></pre></td>
									<td>Array of CSV fieldnames. If not given, the fieldnames will be based on what is defined in the first row of the data array.</td>
								</tr>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>string</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$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</code>
							</pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>
			<article>
				<h4 class="method" id="method_to_json">to_json()</h4>
				<p>The <strong>to_json</strong> method returns the given data as a JSON string. Do not call this directly, use the <strong>forge</strong> method as described in the example.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>string</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$array = array('foo' => 'bar', 'baz' => 'qux');
print_r(Format::forge($array)->to_json());

// Returns
// {"foo":"bar","baz":"qux"}</code>
							</pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_to_serialized">to_serialized()</h4>
				<p>The <strong>to_serialized</strong> method returns the given data as a serialized string. Do not call this directly, use the <strong>forge</strong> method as described in the example.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>string</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$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";}</code>
							</pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_to_php">to_php()</h4>
				<p>The <strong>to_php</strong> 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.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>string</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$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',
	),
)</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

		</div>

		<footer>
			<p>
				&copy; FuelPHP Development Team 2010-2025 - <a href="https://fuelphp.com">FuelPHP</a> is released under the MIT license.
			</p>
		</footer>
	</div>
</body>
</html>