Merge branch 'release/4.1.0'

.travis.yml

@@ -1,6 +1,10 @@
 language: php
 
-php: ["5.3", "5.4", "5.5"]
+php: ["5.3", "5.4", "5.5", "hhvm"]
+
+matrix:
+  allow_failures:
+    - php: hhvm
 
 env:
   global:

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Pops changelog
 
+## 4.1.0 (2014-02-09)
+
+- **[FIXED]** Added accessor methods for important private class members
+  required by subclasses (value, isRecursive etc.) - in version 3 these were
+  protected and so 'just worked'.
+- **[FIXED]** Proxies now actually implement `ProxyInterface` (lol).
+- **[NEW]** Added formal interfaces for each proxy type.
+- **[NEW]** Added `ProxyInterface::setPopsValue()` and
+    `ProxyInterface::popsValue()`.
+- **[IMPROVED]** Deprecated methods in favour of `ProxyInterface::popsValue()`:
+    - `ProxyArray::popsArray()`
+    - `ProxyClass::popsClass()`
+    - `ProxyObject::popsObject()`
+    - `ProxyPrimitive::popsPrimitive()`
+- **[IMPROVED]** Refactored some common code into abstract base classes.
+- **[MAINTENANCE]** Minor repo maintenance
+
 ## 4.0.1 (2014-01-30)
 
 - **[MAINTENANCE]** General repository maintanance

README.md

@@ -2,7 +2,7 @@
 
 *PHP Object Proxy System.*
 
-[![The most recent stable version is 4.0.1][version-image]][Semantic versioning]
+[![The most recent stable version is 4.1.0][version-image]][Semantic versioning]
 [![Current build status image][build-image]][Current build status]
 [![Current coverage status image][coverage-image]][Current coverage status]
 
@@ -216,7 +216,7 @@ class OutputEscaperProxyPrimitive extends ProxyPrimitive
     public function __toString()
     {
         return htmlspecialchars(
-            strval($this->popsPrimitive()),
+            strval($this->popsValue()),
             ENT_QUOTES,
             'UTF-8'
         );
@@ -320,4 +320,4 @@ directly as a value. The arguments must also contain a **reference** to
 [Current coverage status]: https://coveralls.io/r/eloquent/pops
 [eloquent/pops]: https://packagist.org/packages/eloquent/pops
 [Semantic versioning]: http://semver.org/
-[version-image]: http://img.shields.io/:semver-4.0.1-brightgreen.svg "This project uses semantic versioning"
+[version-image]: http://img.shields.io/:semver-4.1.0-brightgreen.svg "This project uses semantic versioning"

src/AbstractProxy.php

@@ -0,0 +1,66 @@
+<?php
+
+/*
+ * This file is part of the Pops package.
+ *
+ * Copyright © 2014 Erin Millard
+ *
+ * For the full copyright and license information, please view the LICENSE file
+ * that was distributed with this source code.
+ */
+
+namespace Eloquent\Pops;
+
+/**
+ * An abstract base class for implementing proxies.
+ */
+abstract class AbstractProxy implements ProxyInterface
+{
+    /**
+     * Construct a new proxy.
+     *
+     * @param mixed $value The value to wrap.
+     *
+     * @throws Exception\InvalidTypeException If the supplied value is not the correct type.
+     */
+    public function __construct($value)
+    {
+        $this->setPopsValue($value);
+    }
+
+    /**
+     * Set the wrapped value.
+     *
+     * @param mixed $value The value to wrap.
+     *
+     * @throws Exception\InvalidTypeException If the supplied value is not the correct type.
+     */
+    public function setPopsValue($value)
+    {
+        $this->assertPopsValue($value);
+
+        $this->value = $value;
+    }
+
+    /**
+     * Get the wrapped value.
+     *
+     * @return mixed The wrapped value.
+     */
+    public function popsValue()
+    {
+        return $this->value;
+    }
+
+    /**
+     * Throw an exception if the supplied value is an incorrect type for this
+     * proxy.
+     *
+     * @param mixed $value The value to wrap.
+     *
+     * @throws Exception\InvalidTypeException If the supplied value is not the correct type.
+     */
+    abstract protected function assertPopsValue($value);
+
+    private $value;
+}

src/AbstractTraversableProxy.php

@@ -0,0 +1,138 @@
+<?php
+
+/*
+ * This file is part of the Pops package.
+ *
+ * Copyright © 2014 Erin Millard
+ *
+ * For the full copyright and license information, please view the LICENSE file
+ * that was distributed with this source code.
+ */
+
+namespace Eloquent\Pops;
+
+use Iterator;
+
+/**
+ * An abstract base class for implementing traversable proxies.
+ */
+abstract class AbstractTraversableProxy extends AbstractProxy implements
+    TraversableProxyInterface
+{
+    /**
+     * Construct a new traversable proxy.
+     *
+     * @param mixed        $value       The value to wrap.
+     * @param boolean|null $isRecursive True if the wrapped value should be recursively proxied.
+     *
+     * @throws Exception\InvalidTypeException If the supplied value is not the correct type.
+     */
+    public function __construct($value, $isRecursive = null)
+    {
+        if (null === $isRecursive) {
+            $isRecursive = false;
+        }
+
+        parent::__construct($value);
+
+        $this->isPopsRecursive = $isRecursive;
+    }
+
+    /**
+     * Returns true if the wrapped value is recursively proxied.
+     *
+     * @return boolean True if the wrapped value is recursively proxied.
+     */
+    public function isPopsRecursive()
+    {
+        return $this->isPopsRecursive;
+    }
+
+    /**
+     * Get the current iterator value.
+     *
+     * @return mixed The current value.
+     */
+    public function current()
+    {
+        return $this->popsProxySubValue($this->popsInnerIterator()->current());
+    }
+
+    /**
+     * Get the current iterator key.
+     *
+     * @return mixed The current key.
+     */
+    public function key()
+    {
+        return $this->popsInnerIterator()->key();
+    }
+
+    /**
+     * Move to the next iterator value.
+     */
+    public function next()
+    {
+        $this->popsInnerIterator()->next();
+    }
+
+    /**
+     * Rewind to the beginning of the iterator.
+     */
+    public function rewind()
+    {
+        $this->popsInnerIterator()->rewind();
+    }
+
+    /**
+     * Returns true if the current iterator position is valid.
+     *
+     * @return boolean True if the current position is valid.
+     */
+    public function valid()
+    {
+        return $this->popsInnerIterator()->valid();
+    }
+
+    /**
+     * Wrap a sub-value in a proxy if recursive proxying is enabled.
+     *
+     * @param mixed $value The value to wrap.
+     *
+     * @return mixed The proxied value, or the untouched value.
+     */
+    protected function popsProxySubValue($value)
+    {
+        if ($this->isPopsRecursive()) {
+            $popsClass = static::popsProxyClass();
+
+            return $popsClass::proxy($value, true);
+        }
+
+        return $value;
+    }
+
+    /**
+     * Get an iterator for the wrapped object.
+     *
+     * @return Iterator An iterator for the wrapped object.
+     */
+    protected function popsInnerIterator()
+    {
+        if (null === $this->popsInnerIterator) {
+            $this->popsInnerIterator = $this->popsCreateInnerIterator();
+        }
+
+        return $this->popsInnerIterator;
+    }
+
+    /**
+     * Create an iterator for the wrapped object.
+     *
+     * @return Iterator An iterator for the wrapped object.
+     */
+    abstract protected function popsCreateInnerIterator();
+
+    private $isPopsRecursive;
+    private $popsInnerIterator;
+}

src/Exception/InvalidTypeException.php

@@ -0,0 +1,66 @@
+<?php
+
+/*
+ * This file is part of the Pops package.
+ *
+ * Copyright © 2014 Erin Millard
+ *
+ * For the full copyright and license information, please view the LICENSE file
+ * that was distributed with this source code.
+ */
+
+namespace Eloquent\Pops\Exception;
+
+use Exception;
+
+/**
+ * A value of an invalid type was supplied.
+ */
+final class InvalidTypeException extends Exception
+{
+    /**
+     * Construct a new invalid type exception.
+     *
+     * @param mixed          $value        The supplied value.
+     * @param string         $expectedType The expected type.
+     * @param Exception|null $cause        The cause, if available.
+     */
+    public function __construct($value, $expectedType, Exception $cause = null)
+    {
+        $this->value = $value;
+        $this->expectedType = $expectedType;
+
+        parent::__construct(
+            sprintf(
+                'Invalid value %s. Expected value of type %s.',
+                var_export($value, true),
+                var_export($expectedType, true)
+            ),
+            0,
+            $cause
+        );
+    }
+
+    /**
+     * Get the upplied value.
+     *
+     * @return mixed THe supplied value.
+     */
+    public function value()
+    {
+        return $this->value;
+    }
+
+    /**
+     * Get the expected type.
+     *
+     * @return string The expected type.
+     */
+    public function expectedType()
+    {
+        return $this->expectedType;
+    }
+
+    private $value;
+    private $expectedType;
+}