Merging develop to master in preparation for 3.1.0 release.

Author: weierophinney

.travis.yml

@@ -24,15 +24,14 @@ env:
 matrix:
   fast_finish: true
   include:
-    - php: 5.5
-      env:
-        - EXECUTE_CS_CHECK=true
     - php: 5.6
       env:
-        - EXECUTE_TEST_COVERALLS=true
+        - TEST_COVERAGE=true
         - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
         - PATH="$HOME/.local/bin:$PATH"
     - php: 7
+      env:
+        - CS_CHECK=true
     - php: hhvm 
   allow_failures:
     - php: hhvm
@@ -42,21 +41,21 @@ notifications:
   email: false
 
 before_install:
-  - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then phpenv config-rm xdebug.ini || return 0 ; fi
+  - if [[ $TEST_COVERAGE != 'true' ]]; then phpenv config-rm xdebug.ini || return 0 ; fi
   - composer self-update
-  - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then composer require --dev --no-update satooshi/php-coveralls ; fi
+  - if [[ $TEST_COVERAGE == 'true' ]]; then composer require --dev --no-update satooshi/php-coveralls ; fi
 
 install:
   - travis_retry composer install --no-interaction --ignore-platform-reqs
 
 script:
-  - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/phpunit --coverage-clover clover.xml ; fi
-  - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then ./vendor/bin/phpunit ; fi
-  - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then ./vendor/bin/php-cs-fixer fix -v --diff --dry-run ; fi
+  - if [[ $TEST_COVERAGE == 'true' ]]; then composer test-coverage ; fi
+  - if [[ $TEST_COVERAGE != 'true' ]]; then composer test ; fi
+  - if [[ $CS_CHECK == 'true' ]]; then composer cs-check ; fi
   - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi
 
 after_success:
   - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi
 
 after_script:
-  - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/coveralls ; fi
+  - if [[ $TEST_COVERAGE == 'true' ]]; then composer upload-coverage ; fi

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
+## 3.1.0 - TBD
+
+### Added
+
+- [#63](https://github.com/zendframework/zend-stdlib/pull/63) adds a new
+  `Zend\Stdlib\ConsoleHelper` class, providing minimal support for writing
+  output to `STDOUT` and `STDERR`, with optional colorization, when the console
+  supports that feature.
+
+### Deprecated
+
+- [#38](https://github.com/zendframework/zend-stdlib/pull/38) deprecates
+  `Zend\Stdlib\JsonSerializable`, as all supported version of PHP now support
+  it.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 3.0.2 - TBD
 
 ### Added

README.md

@@ -7,12 +7,11 @@
 class for different scopes like:
 
 - array utilities functions;
-- json serializable interfaces;
 - general messaging systems;
 - string wrappers;
 - etc.
 
 ---
 
 - File issues at https://github.com/zendframework/zend-stdlib/issues
-- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-stdlib
+- Documentation is at https://docs.zendframework.com/zend-stdlib/

composer.json

@@ -13,12 +13,12 @@
         }
     },
     "require": {
-        "php": "^5.5 || ^7.0"
+        "php": "^5.6 || ^7.0"
     },
     "require-dev": {
-        "fabpot/php-cs-fixer": "1.7.*",
+        "athletic/athletic": "~0.1",
         "phpunit/PHPUnit": "~4.0",
-        "athletic/athletic": "~0.1"
+        "squizlabs/php_codesniffer": "^2.6.2"
     },
     "extra": {
         "branch-alias": {
@@ -31,5 +31,12 @@
             "ZendTest\\Stdlib\\": "test/",
             "ZendBench\\Stdlib\\": "benchmark/"
         }
+    },
+    "scripts": {
+        "cs-check": "phpcs --colors",
+        "cs-fix": "phpcbf --colors",
+        "test": "phpunit --colors=always",
+        "test-coverage": "phpunit --colors=always --coverage-clover clover.xml",
+        "upload-coverage": "coveralls -v"
     }
 }

doc/book/console-helper.md

@@ -0,0 +1,126 @@
+# Console Helper
+
+Writing one-off scripts or vendor binaries for a package is often problematic:
+
+- You need to parse arguments manually.
+- You need to send output to the console in a meaningful fashion:
+    - Using `STDOUT` for meaningful, expected output
+    - Using `STDERR` for error messages
+    - Ensuring any line breaks are converted to `PHP_EOL`
+    - Optionally, using console colors to provide context, which means:
+        - Detecting whether or not the console supports colors in the first place
+        - Providing appropriate escape sequences to produce color
+
+`Zend\Stdlib\ConsoleHelper` helps to address the second major bullet point and
+all beneath it in a minimal fashion.
+
+## Usage
+
+Typical usage is to instantiate a `ConsoleHelper`, and call one of its methods:
+
+```php
+use Zend\Stdlib\ConsoleHelper;
+
+$helper = new ConsoleHelper();
+$helper->writeLine('This is output');
+```
+
+You can optionally pass a PHP stream resource to the constructor, which will be
+used to determine whether or not color support is available:
+
+```php
+$helper = new ConsoleHelper($stream);
+```
+
+By default, it assumes `STDOUT`, and tests against that.
+
+## Available methods
+
+`ConsoleHelper` provides the following methods.
+
+### colorize
+
+- `colorize(string $string) : string`
+
+`colorize()` accepts a formatted string, and will then apply ANSI color
+sequences to them, if color support is detected.
+
+The following sequences are currently supported:
+
+- `<info>...</info>` will apply a green color sequence around the provided text.
+- `<error>...</error>` will apply a red color sequence around the provided text.
+
+You may mix multiple sequences within the same stream.
+
+### write
+
+- `write(string $string, bool $colorize = true, resource $stream = STDOUT) : void`
+
+Emits the provided `$string` to the provided `$stream` (which defaults to
+`STDOUT` if not provided). Any EOL sequences are convered to `PHP_EOL`. If
+`$colorize` is `true`, the string is first passed to `colorize()` as well.
+
+### writeline
+
+- `writeLine(string $string, bool $colorize = true, resource $stream = STDOUT) : void`
+
+Same as `write()`, except it also appends a `PHP_EOL` sequence to the `$string`.
+
+### writeErrorMessage
+
+- `writeErrorMessage(string $message)`
+
+Wraps `$message` in an `<error></error>` sequence, and passes it to
+`writeLine()`, using `STDERR` as the `$stream`.
+
+## Example
+
+Below is an example class that accepts an argument list, and determines how and
+what to emit.
+
+```php
+namespace Foo;
+
+use Zend\Stdlib\ConsoleHelper;
+
+class HelloWorld
+{
+    private $helper;
+
+    public function __construct(ConsoleHelper $helper = null)
+    {
+        $this->helper = $helper ?: new ConsoleHelper();
+    }
+
+    public function __invoke(array $args)
+    {
+        if (! count($args)) {
+            $this->helper->writeErrorMessage('Missing arguments!');
+            return;
+        }
+
+        if (count($args) > 1) {
+            $this->helper->writeErrorMessage('Too many arguments!');
+            return;
+        }
+
+        $target = array_shift($args);
+
+        $this->helper->writeLine(sprintf(
+            '<info>Hello</info> %s',
+            $target
+        ));
+    }
+}
+```
+
+## When to upgrade
+
+`ConsoleHelper` is deliberately simple, and assumes that your primary need for
+console tooling is for output considerations.
+
+If you need to parse complex argument strings, we recommend using
+[zend-console](https://docs.zendframework.com/zend-console/)/[zf-console](https://github.com/zfcampus/zf-console)
+or [symfony/console](http://symfony.com/doc/current/components/console.html),
+as these packages provide those capabilities, as well as far more colorization
+and console feature detection facilities.

mkdocs.yml

@@ -2,6 +2,8 @@ docs_dir: doc/book
 site_dir: doc/html
 pages:
     - index.md
+    - Reference:
+      - "Console Helper": console-helper.md
     - Migration: migration.md
 site_name: zend-stdlib
 site_description: Zend\Stdlib

phpcs.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+<ruleset name="Zend Framework coding standard">
+    <description>Zend Framework coding standard</description>
+
+    <!-- display progress -->
+    <arg value="p"/>
+    <arg name="colors"/>
+
+    <!-- inherit rules from: -->
+    <rule ref="PSR2"/>
+    <rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
+    <rule ref="Generic.Formatting.SpaceAfterNot"/>
+    <rule ref="Squiz.WhiteSpace.OperatorSpacing">
+        <properties>
+            <property name="ignoreNewlines" value="true"/>
+        </properties>
+    </rule>
+    <rule ref="Squiz.WhiteSpace.SuperfluousWhitespace">
+        <properties>
+            <property name="ignoreBlankLines" value="false"/>
+        </properties>
+    </rule>
+
+    <!-- Paths to check -->
+    <file>src</file>
+    <file>test</file>
+</ruleset>

src/AbstractOptions.php

@@ -13,13 +13,15 @@
 
 abstract class AbstractOptions implements ParameterObjectInterface
 {
+    // @codingStandardsIgnoreStart
     /**
      * We use the __ prefix to avoid collisions with properties in
      * user-implementations.
      *
      * @var bool
      */
     protected $__strictMode__ = true;
+    // @codingStandardsIgnoreEnd
 
     /**
      * Constructor
@@ -46,7 +48,7 @@ public function setFromArray($options)
             $options = $options->toArray();
         }
 
-        if (!is_array($options) && !$options instanceof Traversable) {
+        if (! is_array($options) && ! $options instanceof Traversable) {
             throw new Exception\InvalidArgumentException(
                 sprintf(
                     'Parameter provided to %s must be an %s, %s or %s',

src/ArrayObject.php

@@ -180,14 +180,16 @@ public function count()
      */
     public function exchangeArray($data)
     {
-        if (!is_array($data) && !is_object($data)) {
-            throw new Exception\InvalidArgumentException('Passed variable is not an array or object, using empty array instead');
+        if (! is_array($data) && ! is_object($data)) {
+            throw new Exception\InvalidArgumentException(
+                'Passed variable is not an array or object, using empty array instead'
+            );
         }
 
         if (is_object($data) && ($data instanceof self || $data instanceof \ArrayObject)) {
             $data = $data->getArrayCopy();
         }
-        if (!is_array($data)) {
+        if (! is_array($data)) {
             $data = (array) $data;
         }
 
@@ -290,7 +292,7 @@ public function offsetExists($key)
     public function &offsetGet($key)
     {
         $ret = null;
-        if (!$this->offsetExists($key)) {
+        if (! $this->offsetExists($key)) {
             return $ret;
         }
         $ret =& $this->storage[$key];