Add documentation for string.classes

Author: Riimu

CHANGES.md

@@ -1,5 +1,15 @@
 # Changelog #
 
+## v2.4.0 (2018-07-??) ##
+
+  * Added `string.classes` option, which allows to define an array of classes or
+    namespaces to encode using the `::class` format, when encountered as strings
+  * Added `string.imports` options, which allows to define the used imports to write
+    the `::class` format strings using shorter imported notation
+  * Support for HHVM has been dropped, as HHVM no longer aims for PHP compatibility
+  * Added travis builds for PHP 7.2
+  * Change some rules in the used coding standard 
+
 ## v2.3.0 (2017-07-15) ##
 
   * Added `string.utf8` option which causes the string encoder to escape all

README.md

@@ -201,6 +201,23 @@ apply to following calls.
     multibyte UTF-8 characters in strings are encoded using the PHP7 unicode
     code point syntax. Note that this syntax does not work in PHP versions
     earlier than 7.0.
+    
+  * **string.classes** : &lt;string[]&gt; ([])<br>
+    Defines a list of classes or class namespace prefixes for classes that
+    can be encoded using the class resolution operator `::class` when 
+    encountered in strings. e.g. providing the value `['Riimu\\']` would encode
+    all strings that look like class names in the `Riimu` namespace like
+    `Riimu\Kit\PHPEncoder::class`.
+    
+  * **string.imports** : &lt;string[]&gt; ([])<br>
+    List of imports used in the resulting code file, which allows class names
+    to be written using shorter format. The list should be an associative array
+    with the namespace or class as the key and the used name as the value. Use
+    empty string to indicate the current namespace.
+    
+    For example, if the resulting file would have `namespace Riimu\Kit\PHPEncoder;`
+    and `use PHPUnit\Framework\TestCase;`, you could set up the array as
+    `['Riimu\\Kit\\PHPEncoder\\' => '', 'PHPUnit\\Framework\\TestCase' => 'TestCase']`
 
   * **array.short** : &lt;boolean&gt; (true)<br>
     When set to `true`, arrays are enclosed using square brackets `[]` instead

examples/class_resolution.php

@@ -0,0 +1,37 @@
+<?php
+
+/* Shows an example of how you can take advantage of class resolution in the
+   generated code. */
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+$encoder = new \Riimu\Kit\PHPEncoder\PHPEncoder([
+    'string.classes' => [
+        'Riimu\\',
+        'PHPUnit\\Framework\\TestCase',
+        'DateTime',
+    ],
+    'string.imports' => [
+        'Riimu\\Kit\\PHPEncoder\\' => '',
+        'PHPUnit\\Framework\\TestCase' => 'TestCase',
+    ],
+]);
+
+
+echo "<?php
+
+namespace Riimu\Kit\PHPEncoder;
+
+use PHPUnit\Framework\TestCase;
+
+var_dump(";
+
+echo $encoder->encode([
+    \PHPUnit\Framework\TestCase::class,
+    \Riimu\Kit\PHPEncoder\PHPEncoder::class,
+    \Riimu\Kit\PHPEncoder\Encoder\Encoder::class,
+    \DateTime::class,
+    \DateTimeInterface::class, // Will be encoded as plain string, since it's not allowed by string.classes
+]);
+
+echo ");\n";

src/Encoder/StringEncoder.php

@@ -44,6 +44,12 @@ public function encode($value, $depth, array $options, callable $encode)
         return $this->getSingleQuotedString($value);
     }
 
+    /**
+     * Tests if the given value is a string that could be encoded as a class name constant.
+     * @param string $value The string to test
+     * @param array $options The string encoding options
+     * @return bool True if string can be encoded as class constant, false if not
+     */
     private function isClassName($value, array $options)
     {
         if (preg_match('/^([a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*)(\\\\(?1))*$/', $value) !== 1) {
@@ -53,6 +59,12 @@ private function isClassName($value, array $options)
         return array_intersect(iterator_to_array($this->iterateNamespaces($value)), $options['string.classes']) !== [];
     }
 
+    /**
+     * Encodes the given string as a class name constant based on used imports.
+     * @param string $value The string to encode
+     * @param array $options The string encoding options
+     * @return string The class constant PHP code representation
+     */
     private function getClassName($value, array $options)
     {
         foreach ($this->iterateNamespaces($value) as $partial) {
@@ -65,6 +77,11 @@ private function getClassName($value, array $options)
         return sprintf('\\%s::class', $value);
     }
 
+    /**
+     * Iterates over the variations of the namespace for the given class name.
+     * @param string $value The class name to iterate over
+     * @return \Generator|string[] The namespace parts of the string
+     */
     private function iterateNamespaces($value)
     {
         yield $value;
@@ -77,6 +94,12 @@ private function iterateNamespaces($value)
         }
     }
 
+    /**
+     * Returns the PHP code representation for the string that is not just simple ascii characters.
+     * @param string $value The string to encode
+     * @param array $options The string encoding options
+     * @return string The PHP code representation for the complex string
+     */
     private function getComplexString($value, array $options)
     {
         if ($this->isBinaryString($value, $options)) {