Refactor float encoding

Author: Riimu

.travis.yml

@@ -6,11 +6,13 @@ php:
   - 5.4
 
 before_script:
-  - composer require "satooshi/php-coveralls dev-master"
+  - composer require "satooshi/php-coveralls:dev-master"
+  - composer require "squizlabs/php_codesniffer:2.*"
 
 script:
   - mkdir -p build/logs
   - phpunit --coverage-clover build/logs/clover.xml
+  - php vendor/bin/phpcs --standard=PSR2 src
 
 after_script:
   - php vendor/bin/coveralls -v

CHANGES.md

@@ -1,5 +1,22 @@
 # Changelog #
 
+## v2.1.0 (2015-04-18) ##
+
+  * Encoder options with `null` default value will now be recognized
+  * The integer encoder will now add an `(int)` cast in front of integers, if
+    their value equals `PHP_INT_MAX * -1 - 1`.
+  * If `float.integers` is set to `true`, the float encoder will now only encode
+    floats as integers if the value is accurately represented by the float. Set
+    the value to `"all"` to restore the previous behavior.
+  * The float encoder no longer breaks if the PHP locale uses comma as a decimal
+    separator.
+  * The float encoder now behaves slightly differently when deciding whether to
+    use the exponential float notation or not.
+  * The float encoder now uses `serialize_precision` when the option `precision`
+    is set to `false` 
+  * Several methods will now throw an InvalidOptionException if any invalid
+    encoder options have been provided
+
 ## v2.0.2 (2015-01-21) ##
 
   * `array.align` will now respect `array.omit` and `array.inline` settings if

README.md

@@ -1,14 +1,17 @@
 # PHP Variable Exporter #
 
-*PHPEncoder* is a PHP library for exporting variables into PHP code similar to the
-built in function `var_export()`. Compared to the built in function, this 
-library provides a more customizable alternative that makes it easier to 
-dynamically create configuration files and cache files in the format you desire.
-
-The purpose of this library is to address some of the problems with
-`var_export()`. For example, there are no options to control the amount of
-whitespace in the output, which sometimes results in too verbose output. This
-library also offers more options in how to export objects.
+*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
@@ -30,8 +33,8 @@ In order to use this library, the following requirements must be met:
 
 ## Installation ##
 
-This library can be installed via [Composer](http://getcomposer.org/). To do
-this, download the `composer.phar` and require this library as a dependency. For
+This library can be installed via [Composer](http://getcomposer.org/). To do so,
+download the `composer.phar` and require this library as a dependency. For
 example:
 
 ```
@@ -51,12 +54,12 @@ Alternatively, you can add the dependency to your `composer.json` and run
 ```
 
 Any library that has been installed via Composer can be loaded by including the
-`vendor/autoload.php` file that was generated by Composer.
+`vendor/autoload.php` file that was generated by Composer during the install.
 
 It is also possible to install this library manually. To do this, download the
 [latest release](https://github.com/Riimu/Kit-PHPEncoder/releases/latest) and
-extract the `src` folder to your project folder. To load the library, include
-the provided `src/autoload.php` file.
+extract the `src` folder to your project folder. To load the library, simply
+include the provided `src/autoload.php` file.
 
 ## Usage ##
 
@@ -124,71 +127,81 @@ 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.
+  * 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.
 
 #### List of Options ####
 
   * **whitespace** : <boolean> (true)  
-    When set to false, generation of all extra whitespace is disabled and all
+    When set to `false`, generation of all extra whitespace is disabled and all
     other settings that affect whitespace are ignored.
 
   * **null.capitalize** : <boolean> (false)  
-    When set to true, nulls are written in upper case instead of lower case. 
+    When set to `true`, all `null` values are written in upper case instead of
+    lower case. 
 
   * **boolean.capitalize** : <boolean> (false)  
-    When set to true, true and false are written in upper case instead of lower case.
+    When set to `true`, all `true` and `false` values are written in upper case
+    instead of lower case.
 
-  * **float.integers** : <boolean> (false)  
-    When set to true, float values that represent integers are encoded as
-    integers instead of floats (e.g. '2.0' will be simply written as '2').
+  * **float.integers** : <boolean|"all"> (false)  
+    When set to `true`, 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 value `2.0` will be encoded as
+    `2`). To include the values that are not accurately represented, you may set
+    option to `"all"`.
 
   * **float.precision** : <integer|false> (17)  
-    Maximum number of decimals in floats. If set to false, the PHP ini setting
-    'precision' is used instead. Note that due to the way floating point values
-    work, more than 17 digits does not provide any additional precision.
+    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 to
+    `false`, the PHP ini setting `serialize_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 to true, all strings containing bytes outside the 32-126 ASCII
+    When set to `true`, 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 to true, arrays are enclosed using square brackets `[]` instead of
-    the `array()` notation.
+    When set to `true`, arrays are enclosed using square brackets `[]` instead
+    using of the long array notation `array()`.
 
   * **array.base** : <integer|string> (0)  
-    Base indentation for arrays as number of spaces or as a string. Useful, when
-    generating code into files with specific level of indentation.
+    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 number of spaces or
-    a string.
+    Amount of indentation for single level of indentation as a number of spaces
+    or a string.
 
   * **array.align** : <boolean> (false)  
-    When set to true, array assignment operators `=>` are aligned to the same
+    When set to `true`, array assignment operators `=>` are aligned to the same
     column using spaces. Even if enabled, `array.omit` and `array.inline`
-    options are still respected, but only if all the keys in the array (or in 
-    any multi level array) can be omitted.
+    options are still respected, but only if all the keys in the specific array 
+    can be omitted.
 
   * **array.inline** : <boolean|integer> (70)  
-    When set to true, 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 when `array.omit` is set to false.
+    When set to `true`, 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 when `array.omit` is set to
+    false.
 
   * **array.omit** : <boolean> (true)  
-    When set to true, any redundant array key will not be written. (e.g. the
-    array `[0 => 'a', 1 => 'b']` would be written just as `['a', 'b']`)
+    When set to `true`, 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 to false, the
+    The end of line character used by array output. When set to `false`, the
     default `PHP_EOL` will be used instead.
 
   * **object.method** : <boolean> (true)  
-    When set to true, any encoded object will be checked for methods `toPHP()`
+    When set to `true`, any encoded object will be checked for methods `toPHP()`
     and `toPHPValue()`. If the method `toPHP()` exists, the returned string will
     be used as the PHP code representation of the object. If the method
     `toPHPValue()` exists instead, the returned value will be encoded as PHP and
@@ -206,19 +219,19 @@ apply to following calls.
 
   * **object.cast** : <boolean> (true)  
     Whether to add an `(object)` cast in front of arrays generated from objects
-    when using `vars`, `array` or `iterate` formats.
+    or not when using the object encoding formats `vars`, `array` or `iterate`.
 
   * **recursion.detect** : <boolean> (true)  
-    When set to true, the encoder will attempt to detect circular references in
-    arrays and objects to avoid infinite loops.
+    When set to `true`, the encoder will attempt to detect circular references
+    in arrays and objects to avoid infinite loops.
 
   * **recursion.ignore** : <boolean> (false)  
-    When set to true, any circular reference will be replaced with null instead
-    of throwing an exception.
+    When set to `true`, any circular reference will be replaced with `null`
+    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 to false to have no limit.
+    thrown when the maximum is exceeded. Set to `false` to have no limit.
 
 ## Credits ##
 

apigen.neon

@@ -7,5 +7,6 @@ charset:
 
 main: Riimu\Kit\PHPEncoder
 title: PHPEncoder
-php: false
+php: true
 tree: true
+templateTheme: bootstrap

src/Encoder/ArrayEncoder.php

@@ -50,7 +50,7 @@ public function encode($value, $depth, array $options, callable $encode)
     /**
      * Returns the PHP code for aligned array accounting for omitted keys and inlined arrays.
      * @param array $array Array to encode
-     * @param integer $depth Current indentation depth of the output
+     * @param int $depth Current indentation depth of the output
      * @param array $options List of encoder options
      * @param callable $encode Callback used to encode values
      * @return string The PHP code representation for the array
@@ -75,7 +75,7 @@ private function getAlignedArray(array $array, $depth, array $options, callable
     /**
      * Returns the PHP code for the array as inline or multi line array.
      * @param array $array Array to encode
-     * @param integer $depth Current indentation depth of the output
+     * @param int $depth Current indentation depth of the output
      * @param array $options List of encoder options
      * @param callable $encode Callback used to encode values
      * @return string The PHP code representation for the array
@@ -117,7 +117,7 @@ private function getInlineArray(array $lines, array $options)
     /**
      * Builds the complete array from the encoded key and value pairs.
      * @param string[] $lines Encoded key and value pairs
-     * @param integer $depth Current indentation depth of the output
+     * @param int $depth Current indentation depth of the output
      * @param array $options List of encoder options
      * @return string Array encoded as PHP code
      */
@@ -136,7 +136,7 @@ private function buildArray(array $lines, $depth, array $options)
     /**
      * Wraps the array code using short or long array notation.
      * @param string $string Array string representation to wrap
-     * @param boolean $short True to use short notation, false to use long notation
+     * @param bool $short True to use short notation, false to use long notation
      * @return string The array wrapped appropriately
      */
     private function wrap($string, $short)
@@ -148,7 +148,7 @@ private function wrap($string, $short)
      * Builds the indentation based on the options.
      * @param string|integer $base The base indentation
      * @param string|integer $indent A single indentation level
-     * @param integer $depth The level of indentation
+     * @param int $depth The level of indentation
      * @return string The indentation for the current depth
      */
     private function buildIndent($base, $indent, $depth)
@@ -191,9 +191,9 @@ private function getAlignedPairs(array $array, callable $encode)
      * Returns each key and value pair encoded as array assignment.
      * @param array $array Array to convert into code
      * @param string $space Whitespace between array assignment operator
-     * @param boolean $omit True to omit unnecessary keys, false to not
+     * @param bool $omit True to omit unnecessary keys, false to not
      * @param callable $encode Callback used to encode values
-     * @param boolean $omitted Set to true, if all the keys were omitted, false otherwise
+     * @param bool $omitted Set to true, if all the keys were omitted, false otherwise
      * @return string[] Each of key and value pair encoded as php
      */
     private function getPairs(array $array, $space, $omit, callable $encode, & $omitted = true)
@@ -217,8 +217,8 @@ private function getPairs(array $array, $space, $omit, callable $encode, & $omit
 
     /**
      * Tells if the key can be omitted from array output based on expected index.
-     * @param integer|string $key Current array key
-     * @param integer $nextIndex Next expected key that can be omitted
+     * @param int|string $key Current array key
+     * @param int $nextIndex Next expected key that can be omitted
      * @return bool True if the key can be omitted, false if not
      */
     private function canOmitKey($key, & $nextIndex)

src/Encoder/Encoder.php

@@ -11,7 +11,7 @@
 interface Encoder
 {
     /**
-     * Returns a list of options and their default values as associative array.
+     * Returns a list of options and their default values as an associative array.
      * @return array List of options and their default values
      */
     public function getDefaultOptions();
@@ -24,9 +24,9 @@ public function getDefaultOptions();
     public function supports($value);
 
     /**
-     * Generates to code for the given value.
+     * Generates the PHP code representation for the given value.
      * @param mixed $value Value to encode
-     * @param integer $depth Current indentation depth of the output
+     * @param int $depth Current indentation depth of the output
      * @param array $options List of encoder options
      * @param callable $encode Callback used to encode values
      * @return string The PHP code that represents the given value