Merging develop to master in preparation for 2.9.0 release.

Author: weierophinney

CHANGELOG.md

@@ -2,10 +2,20 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 2.8.2 - TBD
+## 2.9.0 - 2018-05-14
 
 ### Added
 
+- [#37](https://github.com/zendframework/zend-serializer/pull/37) adds support to the `PhpSerialize` adapter to allow it to support the
+  PHP 7 `$options` parameter of `unserialize`, and, specifically, the `allowed_classes` parameter.
+  A new options class, `PhpSerializeOptions`, now allows setting the `unserialize_class_whitelist`
+  option, which may be one of `true` (any class may be unserialized; current behavior), `false`
+  (no class may be unserialized), or an `array` of class names that are explicitly allowed to
+  be unserialized. An instance of this class may now be passed to the `PhpSerialize` constructor
+  in order to set the intended/expected behavior.
+
+### Changed
+
 - Nothing.
 
 ### Deprecated
@@ -18,10 +28,7 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Fixed
 
-- [#34](https://github.com/zendframework/zend-serializer/pull/34)
-  * redundant doctrine dependency
-  * documentaion updates
-  * travis CI update
+- [#34](https://github.com/zendframework/zend-serializer/pull/34) removes a redundant dependency on a Doctrine package.
 
 ## 2.8.1 - 2017-11-20
 

composer.json

@@ -45,8 +45,8 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "2.8-dev",
-            "dev-develop": "2.9-dev"
+            "dev-master": "2.9.x-dev",
+            "dev-develop": "2.10.x-dev"
         },
         "zf": {
             "component": "Zend\\Serializer",

composer.lock

@@ -16,7 +16,12 @@ The `Zend\Serializer\Adapter\PhpSerialize` adapter uses the built-in
 [serialize()](http://php.net/serialize)/[unserialize()](http://php.net/unserialize)
 functions, and is a good default adapter choice.
 
-There are no configurable options for this adapter.
+Available options include:
+
+Option                      | Data Type         | Default Value | Description
+--------------------------- | ----------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------
+unserialize_class_whitelist | `array` or `bool` | `true`        | The allowed classes for unserialize(), see [unserialize()](http://php.net/unserialize) for more information. Only available on PHP 7.0 or higher.
+
 
 ## The IgBinary Adapter
 

docs/book/adapter.md

@@ -1,14 +1,13 @@
 <?php
 /**
- * Zend Framework (http://framework.zend.com/)
- *
- * @link      http://github.com/zendframework/zf2 for the canonical source repository
- * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
- * @license   http://framework.zend.com/license/new-bsd New BSD License
+ * @see       https://github.com/zendframework/zend-serializer for the canonical source repository
+ * @copyright Copyright (c) 2005-2018 Zend Technologies USA Inc. (https://www.zend.com)
+ * @license   https://github.com/zendframework/zend-serializer/blob/master/LICENSE.md New BSD License
  */
 
 namespace Zend\Serializer\Adapter;
 
+use Traversable;
 use Zend\Serializer\Exception;
 use Zend\Stdlib\ErrorHandler;
 
@@ -21,8 +20,15 @@ class PhpSerialize extends AbstractAdapter
      */
     private static $serializedFalse = null;
 
+    /**
+     * @var PhpSerializeOptions
+     */
+    protected $options;
+
     /**
      * Constructor
+     *
+     * @param  array|Traversable|PhpSerializeOptions|null $options
      */
     public function __construct($options = null)
     {
@@ -35,6 +41,36 @@ public function __construct($options = null)
         parent::__construct($options);
     }
 
+    /**
+     * Set options
+     *
+     * @param  array|Traversable|PhpSerializeOptions $options
+     * @return PhpSerialize
+     */
+    public function setOptions($options)
+    {
+        if (! $options instanceof PhpSerializeOptions) {
+            $options = new PhpSerializeOptions($options);
+        }
+
+        $this->options = $options;
+        return $this;
+    }
+
+    /**
+     * Get options
+     *
+     * @return PhpSerializeOptions
+     */
+    public function getOptions()
+    {
+        if ($this->options === null) {
+            $this->options = new PhpSerializeOptions();
+        }
+
+        return $this->options;
+    }
+
     /**
      * Serialize using serialize()
      *
@@ -85,7 +121,12 @@ public function unserialize($serialized)
         }
 
         ErrorHandler::start(E_NOTICE);
-        $ret = unserialize($serialized);
+
+        // The second parameter to unserialize() is only available on PHP 7.0 or higher
+        $ret = PHP_MAJOR_VERSION >= 7
+            ? unserialize($serialized, ['allowed_classes' => $this->getOptions()->getUnserializeClassWhitelist()])
+            : unserialize($serialized);
+
         $err = ErrorHandler::stop();
         if ($ret === false) {
             throw new Exception\RuntimeException('Unserialization failed', 0, $err);

src/Adapter/PhpSerialize.php

@@ -0,0 +1,50 @@
+<?php
+/**
+ * @see       https://github.com/zendframework/zend-serializer for the canonical source repository
+ * @copyright Copyright (c) 2018 Zend Technologies USA Inc. (https://www.zend.com)
+ * @license   https://github.com/zendframework/zend-serializer/blob/master/LICENSE.md New BSD License
+ */
+
+namespace Zend\Serializer\Adapter;
+
+use Zend\Json\Json as ZendJson;
+use Zend\Serializer\Exception;
+
+class PhpSerializeOptions extends AdapterOptions
+{
+    /**
+     * The list of allowed classes for unserialization (PHP 7.0+).
+     *
+     * Possible values:
+     *
+     * - `array` of class names that are allowed to be unserialized
+     * - `true` if all classes should be allowed (behavior pre-PHP 7.0)
+     * - `false` if no classes should be allowed
+     *
+     * @var string[]|bool
+     */
+    protected $unserializeClassWhitelist = true;
+
+    /**
+     * @param string[]|bool $unserializeClassWhitelist
+     * @return void
+     */
+    public function setUnserializeClassWhitelist($unserializeClassWhitelist)
+    {
+        if ($unserializeClassWhitelist !== true && PHP_MAJOR_VERSION < 7) {
+            throw new Exception\InvalidArgumentException(
+                'Class whitelist for unserialize() is only available on PHP versions 7.0 or higher.'
+            );
+        }
+
+        $this->unserializeClassWhitelist = $unserializeClassWhitelist;
+    }
+
+    /**
+     * @return string[]|bool
+     */
+    public function getUnserializeClassWhitelist()
+    {
+        return $this->unserializeClassWhitelist;
+    }
+}

src/Adapter/PhpSerializeOptions.php

@@ -1,20 +1,20 @@
 <?php
 /**
- * Zend Framework (http://framework.zend.com/)
- *
- * @link      http://github.com/zendframework/zf2 for the canonical source repository
- * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
- * @license   http://framework.zend.com/license/new-bsd New BSD License
+ * @see       https://github.com/zendframework/zend-serializer for the canonical source repository
+ * @copyright Copyright (c) 2005-2018 Zend Technologies USA Inc. (https://www.zend.com)
+ * @license   https://github.com/zendframework/zend-serializer/blob/master/LICENSE.md New BSD License
  */
 
 namespace ZendTest\Serializer\Adapter;
 
 use PHPUnit\Framework\TestCase;
+use stdClass;
 use Zend\Serializer;
+use Zend\Serializer\Exception\InvalidArgumentException;
 
 /**
- * @group      Zend_Serializer
- * @covers Zend\Serializer\Adapter\PhpSerialize
+ * @group  Zend_Serializer
+ * @covers \Zend\Serializer\Adapter\PhpSerialize
  */
 class PhpSerializeTest extends TestCase
 {
@@ -165,4 +165,60 @@ public function testUnserializingInvalidStringRaisesException($string, $expected
         $this->expectExceptionMessage($expected);
         $this->adapter->unserialize($string);
     }
+
+    /**
+     * @requires PHP 7.0
+     */
+    public function testPhp7WillNotUnserializeObjectsWhenUnserializeWhitelistedClassesIsFalse()
+    {
+        $value = 'O:8:"stdClass":0:{}';
+        $this->adapter->getOptions()->setUnserializeClassWhitelist(false);
+
+        $data = $this->adapter->unserialize($value);
+
+        $this->assertNotInstanceOf(stdClass::class, $data);
+        $this->assertInstanceOf('__PHP_Incomplete_Class', $data);
+    }
+
+    public function testWhenUnserializeClassWhiteListIsFalseButPHPIsPriorTo7AnExceptionIsRaised()
+    {
+        $value = 'O:8:"stdClass":0:{}';
+
+        if (PHP_MAJOR_VERSION >= 7) {
+            $this->markTestSkipped(sprintf('Test %s is only needed in PHP versions prior to 7.0', __FUNCTION__));
+        }
+
+        self::expectException(InvalidArgumentException::class);
+        self::expectExceptionMessage('Class whitelist for unserialize() is only available on PHP 7.0 or higher.');
+        $this->adapter->getOptions()->setUnserializeClassWhitelist(false);
+    }
+
+    /**
+     * @requires PHP 7.0
+     */
+    public function testUnserializeWillNotUnserializeClassesThatAreNotInTheWhitelist()
+    {
+        $value = 'O:8:"stdClass":0:{}';
+
+        $this->adapter->getOptions()->setUnserializeClassWhitelist([\My\Dummy::class]);
+
+        $data = $this->adapter->unserialize($value);
+
+        $this->assertNotInstanceOf(stdClass::class, $data);
+        $this->assertInstanceOf('__PHP_Incomplete_Class', $data);
+    }
+
+    /**
+     * @requires PHP 7.0
+     */
+    public function testUnserializeWillUnserializeAnyClassWhenUnserializeWhitelistedClassesIsTrue()
+    {
+        $value = 'O:8:"stdClass":0:{}';
+
+        $this->adapter->getOptions()->setUnserializeClassWhitelist([stdClass::class]);
+
+        $data = $this->adapter->unserialize($value);
+        $this->assertInstanceOf(stdClass::class, $data);
+        $this->assertNotInstanceOf('__PHP_Incomplete_Class', $data);
+    }
 }