diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e578285..5a4f47e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,15 @@ All notable changes to this project will be documented in this file, in reverse ### Added -- Nothing. +- [#168](https://github.com/zendframework/zend-view/pull/168) adds two new methods to `Zend\View\Helper\Placeholder` (and thus any + helper extending it): + + - `deleteContainer(string $name)` can be used to delete a placeholder container. + - `clearContainers()` can be used to clear all placeholder containers. + + These new features are particularly useful when in long-running server + environments, such as Swoole, where you may need to clear the contents on each + request. ### Changed diff --git a/doc/book/helpers/placeholder.md b/doc/book/helpers/placeholder.md index ad38cb30..4a95bc92 100644 --- a/doc/book/helpers/placeholder.md +++ b/doc/book/helpers/placeholder.md @@ -63,7 +63,7 @@ $this->placeholder('foo') placeholder('foo') ?> ``` -The above results in an unodered list with pretty indentation. +The above results in an unordered list with pretty indentation. Because the `Placeholder` container objects extend `ArrayObject`, you can also assign content to a specific key in the container easily, instead of simply @@ -131,6 +131,24 @@ foreach ($this->data as $datum): ?> placeholder('foo')->data ?> ``` +## Clearing Content + +In certain situations it is desirable to remove or clear containers and +aggregated content. The placeholder view helper provides two methods to either +delete a specific container or clear all containers at once: + +### Delete a single container + +```php +$this->plugin('placeholder')->deleteContainer('myNamedContainer'); +``` + +### Clear all containers + +```php +$this->plugin('placeholder')->clearContainers(); +``` + ## Concrete Implementations zend-view ships with a number of "concrete" placeholder implementations. These diff --git a/src/Helper/Placeholder.php b/src/Helper/Placeholder.php index aad16d4c..8d42e07f 100644 --- a/src/Helper/Placeholder.php +++ b/src/Helper/Placeholder.php @@ -23,7 +23,7 @@ class Placeholder extends AbstractHelper /** * Placeholder items * - * @var array + * @var Container\AbstractContainer[] */ protected $items = []; @@ -97,4 +97,26 @@ public function containerExists($key) $return = array_key_exists($key, $this->items); return $return; } + + /** + * Delete a specific container by name + * + * @param string $key + * @return void + */ + public function deleteContainer($key) + { + $key = (string) $key; + unset($this->items[$key]); + } + + /** + * Remove all containers + * + * @return void + */ + public function clearContainers() + { + $this->items = []; + } } diff --git a/test/Helper/PlaceholderTest.php b/test/Helper/PlaceholderTest.php index 4d7ac5d6..2064c373 100644 --- a/test/Helper/PlaceholderTest.php +++ b/test/Helper/PlaceholderTest.php @@ -77,4 +77,29 @@ public function testPlaceholderRetrievesSameContainerOnSubsequentCalls() $container2 = $this->placeholder->__invoke('foo'); $this->assertSame($container1, $container2); } + + public function testContainersCanBeDeleted() + { + $container = $this->placeholder->__invoke('foo'); + $container->set('Value'); + $this->assertTrue($this->placeholder->containerExists('foo')); + $this->assertSame('Value', (string) $this->placeholder->__invoke('foo')); + $this->placeholder->deleteContainer('foo'); + $this->assertFalse($this->placeholder->containerExists('foo')); + $this->assertSame('', (string) $this->placeholder->__invoke('foo')); + } + + public function testClearContainersRemovesAllContainers() + { + $this->placeholder->__invoke('foo'); + $this->placeholder->__invoke('bar'); + + $this->assertTrue($this->placeholder->containerExists('foo')); + $this->assertTrue($this->placeholder->containerExists('bar')); + + $this->placeholder->clearContainers(); + + $this->assertFalse($this->placeholder->containerExists('foo')); + $this->assertFalse($this->placeholder->containerExists('bar')); + } }