PHPEncoder is a PHP library for exporting variables and generating PHP code
representations for said variables similar to the built in function
var_export()
. Compared to the built in function, however, this library
provides more options to customize the output, which makes it easier to generate
code for different kinds of purposes such as readable configuration files or
optimized cache files.
The purpose of this library is to address some of the shortcomings with the
built in var_export()
. For example, there is no way to control the amount of
whitespace in the output and there is no way to choose between different array
notations. This library also provides functionality to convert objects into PHP
code that is actually useful when compared to the built in function.
The large number of customization options in this library allows you to create code that fits your purposes. You can create very compact code, when you need to limit the size of the output, or you can create code in the style that actually fits in any of your dynamically generated PHP files.
The API documentation, which can be generated using Apigen, can be read online at: http://kit.riimu.net/api/phpencoder/
In order to use this library, the following requirements must be met:
- PHP version 5.4
This library can be installed by using Composer. In
order to do this, you must download the latest Composer version and run the
require
command to add this library as a dependency to your project. The
easiest way to complete these two tasks is to run the following two commands
in your terminal:
php -r "readfile('https://getcomposer.org/installer');" | php
php composer.phar require "riimu/kit-phpencoder:2.*"
If you already have Composer installed on your system and you know how to use
it, you can also install this library by adding it as a dependency to your
composer.json
file and running the composer install
command. Here is an
example of what your composer.json
file could look like:
{
"require": {
"riimu/kit-phpencoder": "2.*"
}
}
After installing this library via Composer, you can load the library by
including the vendor/autoload.php
file that was generated by Composer during
the installation.
You can also install this library manually without using Composer. In order to
do this, you must download the latest release
and extract the src
folder from the archive to your project folder. To load
the library, you can simply include the src/autoload.php
file that was
provided in the archive.
The most relevant method provided by this library is the encode()
method
provided by PHPEncoder
. The method takes any value as an argument and returns
the PHP code representation for that value.
For example:
<?php
require 'vendor/autoload.php';
$encoder = new \Riimu\Kit\PHPEncoder\PHPEncoder();
echo $encoder->encode(['foo' => 'bar', [1, true, false, null, 1.0]]);
This would create the following output:
[
'foo' => 'bar',
[1, true, false, null, 1.0],
]
Of course, the most important feature of this library is the ability to
customize the created the PHP code. As the second argument, the encode()
method takes an array of options, which can be used to customize the returned
PHP code. For example:
<?php
require 'vendor/autoload.php';
$encoder = new \Riimu\Kit\PHPEncoder\PHPEncoder();
echo $encoder->encode(['foo' => 'bar', [1, true, false, null, 1.0]], [
'array.inline' => false,
'array.omit' => false,
'array.indent' => 2,
'boolean.capitalize' => true,
'null.capitalize' => true,
]);
This would create the following output:
[
'foo' => 'bar',
0 => [
0 => 1,
1 => TRUE,
2 => FALSE,
3 => NULL,
4 => 1.0,
],
]
Encoding options allow you to customize the output of the encode()
method. It
is possible to set these options in three different ways:
- Options can be provided as an array to the
PHPEncoder
constructor. - Option values can be set via the
setOption()
method. - Options can be passed as an array as the second argument to the
encode()
method.
Note that options passed to the encode()
method are only temporary and do not
apply to following calls.
-
whitespace : <boolean> (true)
When set tofalse
, generation of all extra whitespace is disabled and all other settings that affect whitespace are ignored. -
null.capitalize : <boolean> (false)
When set totrue
, allnull
values are written in upper case instead of lower case. -
boolean.capitalize : <boolean> (false)
When set totrue
, alltrue
andfalse
values are written in upper case instead of lower case. -
float.integers : <boolean|"all"> (false)
When set totrue
, any float that represents an integer and has a value that is accurately represented by the floating point number will be encoded as an integer instead of a float. (e.g. the value2.0
will be encoded as2
). To include the values that are not accurately represented, you may set option to"all"
. -
float.precision : <integer|false> (17)
The maximum precision of encoded floating point values, which usually also means the maximum number of digits in encoded floats. If the value is set tofalse
, the PHP ini settingserialize_precision
will be used instead. Note that due to the way floating point values work, a value greater than 17 does not provide any additional precision. -
string.escape : <boolean> (true)
When set totrue
, all strings containing bytes outside the 32-126 ASCII range will be written with double quotes and the characters outside the range will be escaped. -
array.short : <boolean> (true)
When set totrue
, arrays are enclosed using square brackets[]
instead using of the long array notationarray()
. -
array.base : <integer|string> (0)
Base indentation for arrays as a number of spaces or as a string. Provides convenience when you need to output code to a file with specific level of indentation. -
array.indent : <integer|string> (4)
Amount of indentation for single level of indentation as a number of spaces or a string. -
array.align : <boolean> (false)
When set totrue
, array assignment operators=>
are aligned to the same column using spaces. Even if enabled,array.omit
andarray.inline
options are still respected, but only if all the keys in the specific array can be omitted. -
array.inline : <boolean|integer> (70)
When set totrue
, any array that can be written without any array keys will be written in a single line. If an integer is provided instead, the array will be written as a single line only if it does not exceed that number of characters. This option has no effect whenarray.omit
is set to false. -
array.omit : <boolean> (true)
When set totrue
, any redundant array keys will not be included (e.g. the array[0 => 'a', 1 => 'b']
would be encoded just as['a', 'b']
). -
array.eol : <string|false> (false)
The end of line character used by array output. When set tofalse
, the defaultPHP_EOL
will be used instead. -
object.method : <boolean> (true)
When set totrue
, any encoded object will be checked for methodstoPHP()
andtoPHPValue()
. If the methodtoPHP()
exists, the returned string will be used as the PHP code representation of the object. If the methodtoPHPValue()
exists instead, the returned value will be encoded as PHP and used as the code representation of the object. -
object.format : <string> ('vars')
Default object encoding format. The possible values are:string
casts the object to string and then encodes that string as PHP.serialize
serializes the object and wraps it withunserialize()
export
mimics thevar_export()
object representationarray
casts the object to an array and encodes that arrayvars
turns object into an array usingget_object_vars()
iterate
turns the object into an array by iterating over it withforeach
-
object.cast : <boolean> (true)
Whether to add an(object)
cast in front of arrays generated from objects or not when using the object encoding formatsvars
,array
oriterate
. -
recursion.detect : <boolean> (true)
When set totrue
, the encoder will attempt to detect circular references in arrays and objects to avoid infinite loops. -
recursion.ignore : <boolean> (false)
When set totrue
, any circular reference will be replaced withnull
instead of throwing an exception. -
recursion.max : <integer|false> (false)
Maximum number of levels when encoding arrays and objects. Exception is thrown when the maximum is exceeded. Set tofalse
to have no limit.
This library is copyright 2013 - 2015 to Riikka Kalliomäki.
See LICENSE for license and copying information.