Merge branch 'master' into 3.1

Makefile

@@ -6,7 +6,7 @@
 # Use the version number to figure out if the release
 # is a pre-release
 PRERELEASE=$(shell echo $(VERSION) | grep -E 'dev|rc|alpha|beta' --quiet && echo 'true' || echo 'false')
-COMPONENTS= log utility cache datasource core collection event validation database i18n ORM
+COMPONENTS= filesystem log utility cache datasource core collection event validation database i18n ORM
 CURRENT_BRANCH=$(shell git branch | grep '*' | tr -d '* ')
 
 # Github settings

composer.json

@@ -59,6 +59,7 @@
         "cakephp/datasource": "self.version",
         "cakephp/database": "self.version",
         "cakephp/event": "self.version",
+        "cakephp/filesystem": "self.version",
         "cakephp/i18n": "self.version",
         "cakephp/log": "self.version",
         "cakephp/orm": "self.version",

src/Collection/CollectionInterface.php

@@ -482,6 +482,15 @@ public function sample($size = 10);
      */
     public function take($size = 1, $from = 0);
 
+    /**
+     * Returns a new collection that will skip the specified amount of elements
+     * at the beginning of the iteration.
+     *
+     * @param int $howMany The number of elements to skip.
+     * @return \Cake\Collection\CollectionInterface
+     */
+    public function skip($howMany);
+
     /**
      * Looks through each value in the list, returning a Collection of all the
      * values that contain all of the key-value pairs listed in $conditions.
@@ -527,6 +536,14 @@ public function firstMatch(array $conditions);
      * @return mixed The first value in the collection will be returned.
      */
     public function first();
+
+    /**
+     * Returns the last result in this collection
+     *
+     * @return mixed The last value in the collection will be returned.
+     */
+    public function last();
+
     /**
      * Returns a new collection as the result of concatenating the list of elements
      * in this collection with the passed list of elements
@@ -819,7 +836,7 @@ public function unfold(callable $transformer = null);
      * ### Example:
      *
      * ```
-     * $items [1, 2, 3];
+     * $items = [1, 2, 3];
      * $decorated = (new Collection($items))->through(function ($collection) {
      *      return new MyCustomCollection($collection);
      * });
@@ -831,6 +848,44 @@ public function unfold(callable $transformer = null);
      */
     public function through(callable $handler);
 
+    /**
+     * Combines the elements of this collection with each of the elements of the
+     * passed iterables, using their positional index as a reference.
+     *
+     * ### Example:
+     *
+     * ```
+     * $collection = new Collection([1, 2]);
+     * $collection->zip([3, 4], [5, 6])->toList(); // returns [[1, 3, 5], [2, 4, 6]]
+     * ```
+     *
+     * @param array|\Traversable ...$items The collections to zip.
+     * @return \Cake\Collection\CollectionInterface
+     */
+    public function zip($items);
+
+    /**
+     * Combines the elements of this collection with each of the elements of the
+     * passed iterables, using their positional index as a reference.
+     *
+     * The resulting element will be the return value of the $callable function.
+     *
+     * ### Example:
+     *
+     * ```
+     * $collection = new Collection([1, 2]);
+     * $zipped = $collection->zipWith([3, 4], [5, 6], function () {
+     *   return array_sum(func_get_args());
+     * });
+     * $zipped->toList(); // returns [9, 12]; [(1 + 3 + 5), (2 + 4 + 6)]
+     * ```
+     *
+     * @param array|\Traversable ...$items The collections to zip.
+     * @param callable $callable The function to use for zipping the elements together.
+     * @return \Cake\Collection\CollectionInterface
+     */
+    public function zipWith($items, $callable);
+
     /**
      * Returns whether or not there are elements in this collection
      *
@@ -840,6 +895,7 @@ public function through(callable $handler);
      * $items [1, 2, 3];
      * (new Collection($items))->isEmpty(); // false
      * ```
+     *
      * ```
      * (new Collection([]))->isEmpty(); // true
      * ```

src/Collection/CollectionTrait.php

@@ -28,6 +28,7 @@
 use Cake\Collection\Iterator\StoppableIterator;
 use Cake\Collection\Iterator\TreeIterator;
 use Cake\Collection\Iterator\UnfoldIterator;
+use Cake\Collection\Iterator\ZipIterator;
 use Iterator;
 use LimitIterator;
 use RecursiveIteratorIterator;
@@ -281,6 +282,15 @@ public function take($size = 1, $from = 0)
         return new Collection(new LimitIterator($this->unwrap(), $from, $size));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     */
+    public function skip($howMany)
+    {
+        return new Collection(new LimitIterator($this->unwrap(), $howMany));
+    }
+
     /**
      * {@inheritDoc}
      *
@@ -310,6 +320,21 @@ public function first()
         }
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     */
+    public function last()
+    {
+        $iterator = $this->unwrap();
+        $count = $iterator instanceof Countable ?
+            count($iterator) :
+            iterator_count($iterator);
+        foreach ($this->take(1, $count - 1) as $last) {
+            return $last;
+        }
+    }
+
     /**
      * {@inheritDoc}
      *
@@ -530,6 +555,29 @@ public function through(callable $handler)
         return $result instanceof CollectionInterface ? $result: new Collection($result);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     */
+    public function zip($items)
+    {
+        return new ZipIterator(array_merge([$this], func_get_args()));
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     */
+    public function zipWith($items, $callable)
+    {
+        $items = [$items];
+        if (func_num_args() > 2) {
+            $items = func_get_args();
+            $callable = array_pop($items);
+        }
+        return new ZipIterator(array_merge([$this], $items), $callable);
+    }
+
     /**
      * {@inheritDoc}
      *
@@ -539,7 +587,6 @@ public function isEmpty()
         return iterator_count($this->take(1)) === 0;
     }
 
-
     /**
      * {@inheritDoc}
      *

src/Collection/Iterator/ZipIterator.php

@@ -0,0 +1,92 @@
+<?php
+/**
+ * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
+ * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
+ *
+ * Licensed under The MIT License
+ * For full copyright and license information, please see the LICENSE.txt
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @copyright     Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
+ * @link          http://cakephp.org CakePHP(tm) Project
+ * @since         3.0.5
+ * @license       http://www.opensource.org/licenses/mit-license.php MIT License
+ */
+namespace Cake\Collection\Iterator;
+
+use Cake\Collection\Collection;
+use Cake\Collection\CollectionInterface;
+use Cake\Collection\CollectionTrait;
+use MultipleIterator;
+
+/**
+ * Creates an iterator that returns elements grouped in pairs
+ *
+ * ### Example
+ *
+ * ```
+ *  $iterator = new ZipIterator([[1, 2], [3, 4]]);
+ *  $iterator->toList(); // Returns [[1, 3], [2, 4]]
+ * ```
+ *
+ * You can also chose a custom function to zip the elements together, such
+ * as doing a sum by index:
+ *
+ * ### Example
+ *
+ * ```
+ *  $iterator = new ZipIterator([[1, 2], [3, 4]], function ($a, $b) {
+ *    return $a + $b;
+ *  });
+ *  $iterator->toList(); // Returns [4, 6]
+ * ```
+ *
+ */
+class ZipIterator extends MultipleIterator implements CollectionInterface
+{
+
+    use CollectionTrait;
+
+    /**
+     * The function to use for zipping items together
+     *
+     * @var callable
+     */
+    protected $_callback;
+
+    /**
+     * Creates the iterator to merge together the values by for all the passed
+     * iterators by their corresponding index.
+     *
+     * @param array $sets The list of array or iterators to be zipped.
+     * @param callable $callable The function to use for zipping the elements of each iterator.
+     */
+    public function __construct(array $sets, $callable = null)
+    {
+        $sets = array_map(function ($items) {
+            return (new Collection($items))->unwrap();
+        }, $sets);
+
+        $this->_callback = $callable;
+        parent::__construct(MultipleIterator::MIT_NEED_ALL | MultipleIterator::MIT_KEYS_NUMERIC);
+
+        foreach ($sets as $set) {
+            $this->attachIterator($set);
+        }
+    }
+
+    /**
+     * Returns the value resulting out of zipping all the elements for all the
+     * iterators with the same positional index.
+     *
+     * @return mixed
+     */
+    public function current()
+    {
+        if ($this->_callback === null) {
+            return parent::current();
+        }
+
+        return call_user_func_array($this->_callback, parent::current());
+    }
+}

src/Console/Shell.php

@@ -731,4 +731,23 @@ protected function _stop($status = 0)
     {
         exit($status);
     }
+
+    /**
+     * Returns an array that can be used to describe the internal state of this
+     * object.
+     *
+     * @return array
+     */
+    public function __debugInfo()
+    {
+        return [
+            'name' => $this->name,
+            'plugin' => $this->plugin,
+            'command' => $this->command,
+            'tasks' => $this->tasks,
+            'params' => $this->params,
+            'args' => $this->args,
+            'interactive' => $this->interactive,
+        ];
+    }
 }

src/Controller/Component.php

@@ -180,4 +180,19 @@ public function implementedEvents()
         }
         return $events;
     }
+
+    /**
+     * Returns an array that can be used to describe the internal state of this
+     * object.
+     *
+     * @return array
+     */
+    public function __debugInfo()
+    {
+        return [
+            'components' => $this->components,
+            'implementedEvents' => $this->implementedEvents(),
+            '_config' => $this->config(),
+        ];
+    }
 }

src/Database/Expression/QueryExpression.php

@@ -16,6 +16,7 @@
 
 use Cake\Database\ExpressionInterface;
 use Cake\Database\Expression\IdentifierExpression;
+use Cake\Database\Query;
 use Cake\Database\TypeMapTrait;
 use Cake\Database\ValueBinder;
 use Countable;
@@ -406,7 +407,9 @@ public function sql(ValueBinder $generator)
         $template = ($this->count() === 1) ? '%s' : '(%s)';
         $parts = [];
         foreach ($this->_conditions as $part) {
-            if ($part instanceof ExpressionInterface) {
+            if ($part instanceof Query) {
+                $part = '(' . $part->sql($generator) . ')';
+            } elseif ($part instanceof ExpressionInterface) {
                 $part = $part->sql($generator);
             }
             $parts[] = $part;

src/Database/Query.php

@@ -1696,6 +1696,7 @@ public function __toString()
     public function __debugInfo()
     {
         return [
+            '(help)' => 'This is a Query object, to get the results execute or iterate it.',
             'sql' => $this->sql(),
             'params' => $this->valueBinder()->bindings(),
             'defaultTypes' => $this->defaultTypes(),