Replace cache_name_function with NameFilter class (#762)

* Add NameFilter and CallableNameFilter for cache names * Document rules for string returning from filter * Update CHANGELOG.md * declare strict_types in new files, fix deprecation message * remove strict_types declaration again
simplepie · Dec 13, 2022 · 93fe459 · 93fe459
1 parent 7474018
commit 93fe459
Show file tree

Hide file tree

Showing 5 changed files with 231 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,10 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - New method `SimplePie\SimplePie::set_cache()` for providing a PSR-16 cache implementation
+- New method `SimplePie\SimplePie::set_cache_namefilter()` for customize the cache key
+- New class `SimplePie\Cache\CallableNameFilter` to provide a `callable` to customize the cache key
 - New interface `SimplePie\RegistryAware` to inject the `Registry` instance into classes created by `Registry`.
 
 ### Deprecated
 
+- The method `SimplePie\SimplePie::set_cache_name_function()` is deprecated, use `SimplePie\SimplePie::set_cache_namefilter()` instead
 - The method `SimplePie\SimplePie::set_cache_location()` is deprecated, use `SimplePie\SimplePie::set_cache()` instead
 - The method `SimplePie\SimplePie::force_cache_fallback()` is deprecated, expired cache will not be used anymore
 - The class `SimplePie\Cache` is deprecated, use implementation of `SimplePie\SimplePie::set_cache()` instead

diff --git a/src/Cache/CallableNameFilter.php b/src/Cache/CallableNameFilter.php
@@ -0,0 +1,89 @@
+<?php
+/**
+ * SimplePie
+ *
+ * A PHP-Based RSS and Atom Feed Framework.
+ * Takes the hard work out of managing a complete RSS/Atom solution.
+ *
+ * Copyright (c) 2004-2022, Ryan Parman, Sam Sneddon, Ryan McCue, and contributors
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ * 	* Redistributions of source code must retain the above copyright notice, this list of
+ * 	  conditions and the following disclaimer.
+ *
+ * 	* Redistributions in binary form must reproduce the above copyright notice, this list
+ * 	  of conditions and the following disclaimer in the documentation and/or other materials
+ * 	  provided with the distribution.
+ *
+ * 	* Neither the name of the SimplePie Team nor the names of its contributors may be used
+ * 	  to endorse or promote products derived from this software without specific prior
+ * 	  written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
+ * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+ * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS
+ * AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+ * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ * @package SimplePie
+ * @copyright 2004-2022 Ryan Parman, Sam Sneddon, Ryan McCue
+ * @author Ryan Parman
+ * @author Sam Sneddon
+ * @author Ryan McCue
+ * @link http://simplepie.org/ SimplePie
+ * @license http://www.opensource.org/licenses/bsd-license.php BSD License
+ */
+
+namespace SimplePie\Cache;
+
+/**
+ * Creating a cache filename with callables
+ *
+ * @package SimplePie
+ * @subpackage Caching
+ */
+final class CallableNameFilter implements NameFilter
+{
+    /**
+     * @var callable
+     */
+    private $callable;
+
+    public function __construct(callable $callable)
+    {
+        $this->callable = $callable;
+    }
+
+    /**
+     * Method to create cache filename with.
+     *
+     * The returning name MUST follow the rules for keys in PSR-16.
+     *
+     * @link https://www.php-fig.org/psr/psr-16/
+     *
+     * The returning name MUST be a string of at least one character
+     * that uniquely identifies a cached item, MUST only contain the
+     * characters A-Z, a-z, 0-9, _, and . in any order in UTF-8 encoding
+     * and MUST not longer then 64 characters. The following characters
+     * are reserved for future extensions and MUST NOT be used: {}()/\@:
+     *
+     * A provided implementing library MAY support additional characters
+     * and encodings or longer lengths, but MUST support at least that
+     * minimum.
+     *
+     * @param string $name The name for the cache will be most likly an url with query string
+     *
+     * @return string the new cache name
+     */
+    public function filter(string $name): string
+    {
+        return call_user_func($this->callable, $name);
+    }
+}
diff --git a/src/Cache/NameFilter.php b/src/Cache/NameFilter.php
@@ -0,0 +1,76 @@
+<?php
+/**
+ * SimplePie
+ *
+ * A PHP-Based RSS and Atom Feed Framework.
+ * Takes the hard work out of managing a complete RSS/Atom solution.
+ *
+ * Copyright (c) 2004-2022, Ryan Parman, Sam Sneddon, Ryan McCue, and contributors
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ * 	* Redistributions of source code must retain the above copyright notice, this list of
+ * 	  conditions and the following disclaimer.
+ *
+ * 	* Redistributions in binary form must reproduce the above copyright notice, this list
+ * 	  of conditions and the following disclaimer in the documentation and/or other materials
+ * 	  provided with the distribution.
+ *
+ * 	* Neither the name of the SimplePie Team nor the names of its contributors may be used
+ * 	  to endorse or promote products derived from this software without specific prior
+ * 	  written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
+ * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+ * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS
+ * AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+ * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ * @package SimplePie
+ * @copyright 2004-2022 Ryan Parman, Sam Sneddon, Ryan McCue
+ * @author Ryan Parman
+ * @author Sam Sneddon
+ * @author Ryan McCue
+ * @link http://simplepie.org/ SimplePie
+ * @license http://www.opensource.org/licenses/bsd-license.php BSD License
+ */
+
+namespace SimplePie\Cache;
+
+/**
+ * Interface for creating a cache filename
+ *
+ * @package SimplePie
+ * @subpackage Caching
+ */
+interface NameFilter
+{
+    /**
+     * Method to create cache filename with.
+     *
+     * The returning name MUST follow the rules for keys in PSR-16.
+     *
+     * @link https://www.php-fig.org/psr/psr-16/
+     *
+     * The returning name MUST be a string of at least one character
+     * that uniquely identifies a cached item, MUST only contain the
+     * characters A-Z, a-z, 0-9, _, and . in any order in UTF-8 encoding
+     * and MUST not longer then 64 characters. The following characters
+     * are reserved for future extensions and MUST NOT be used: {}()/\@:
+     *
+     * A provided implementing library MAY support additional characters
+     * and encodings or longer lengths, but MUST support at least that
+     * minimum.
+     *
+     * @param string $name The name for the cache will be most likly an url with query string
+     *
+     * @return string the new cache name
+     */
+    public function filter(string $name): string;
+}
diff --git a/src/Sanitize.php b/src/Sanitize.php
@@ -43,9 +43,12 @@
 
 namespace SimplePie;
 
+use InvalidArgumentException;
 use SimplePie\Cache\Base;
 use SimplePie\Cache\BaseDataCache;
+use SimplePie\Cache\CallableNameFilter;
 use SimplePie\Cache\DataCache;
+use SimplePie\Cache\NameFilter;
 
 /**
  * Used for data cleanup and post-processing
@@ -74,6 +77,11 @@ class Sanitize implements RegistryAware
     public $enable_cache = true;
     public $cache_location = './cache';
     public $cache_name_function = 'md5';
+
+    /**
+     * @var NameFilter
+     */
+    private $cache_namefilter;
     public $timeout = 10;
     public $useragent = '';
     public $force_fsockopen = false;
@@ -133,10 +141,24 @@ public function pass_cache_data($enable_cache = true, $cache_location = './cache
             $this->cache_location = (string) $cache_location;
         }
 
-        if ($cache_name_function) {
+        if (! is_string($cache_name_function) && ! is_object($cache_name_function) && ! $cache_name_function instanceof NameFilter) {
+            throw new InvalidArgumentException(sprintf(
+                '%s(): Argument #3 ($cache_name_function) must be of type %s',
+                __METHOD__,
+                NameFilter::class
+            ), 1);
+        }
+
+        // BC: $cache_name_function could be a callable as string
+        if (is_string($cache_name_function)) {
+            // trigger_error(sprintf('Providing $cache_name_function as string in "%s()" is deprecated since SimplePie 1.8.0, provide as "%s" instead.', __METHOD__, NameFilter::class), \E_USER_DEPRECATED);
             $this->cache_name_function = (string) $cache_name_function;
+
+            $cache_name_function = new CallableNameFilter($cache_name_function);
         }
 
+        $this->cache_namefilter = $cache_name_function;
+
         if ($cache !== null) {
             $this->cache = $cache;
         }
@@ -395,7 +417,7 @@ public function sanitize($data, $type, $base = '')
 
                     foreach ($images as $img) {
                         if ($img->hasAttribute('src')) {
-                            $image_url = call_user_func($this->cache_name_function, $img->getAttribute('src'));
+                            $image_url = $this->cache_namefilter->filter($img->getAttribute('src'));
                             $cache = $this->get_cache($image_url);
 
                             if ($cache->get_data($image_url, false)) {

diff --git a/src/SimplePie.php b/src/SimplePie.php
@@ -47,7 +47,9 @@
 use Psr\SimpleCache\CacheInterface;
 use SimplePie\Cache\Base;
 use SimplePie\Cache\BaseDataCache;
+use SimplePie\Cache\CallableNameFilter;
 use SimplePie\Cache\DataCache;
+use SimplePie\Cache\NameFilter;
 use SimplePie\Cache\Psr16;
 
 /**
@@ -504,6 +506,18 @@ class SimplePie
      */
     private $enable_cache = true;
 
+    /**
+     * @var DataCache|null
+     * @see SimplePie::set_cache()
+     */
+    private $cache = null;
+
+    /**
+     * @var NameFilter
+     * @see SimplePie::set_cache_namefilter()
+     */
+    private $cache_namefilter;
+
     /**
      * @var bool Force SimplePie to fallback to expired cache, if enabled,
      * when feed is unavailable.
@@ -657,11 +671,6 @@ class SimplePie
      */
     public $enable_exceptions = false;
 
-    /**
-     * @var DataCache|null
-     */
-    private $cache = null;
-
     /**
      * The SimplePie class contains feed level data and options
      *
@@ -685,6 +694,8 @@ public function __construct()
 
         $this->set_useragent();
 
+        $this->set_cache_namefilter(new CallableNameFilter($this->cache_name_function));
+
         // Other objects, instances created here so we can set options on them
         $this->sanitize = new \SimplePie\Sanitize();
         $this->registry = new \SimplePie\Registry();
@@ -926,12 +937,13 @@ public function set_autodiscovery_cache_duration($seconds = 604800)
      */
     public function set_cache_location($location = './cache')
     {
-        // @trigger_error(sprintf('SimplePie\SimplePie::set_cache_location() is deprecated since SimplePie 1.8.0, please use "SimplePie\SimplePie::set_cache()".'), \E_USER_DEPRECATED);
+        // @trigger_error(sprintf('SimplePie\SimplePie::set_cache_location() is deprecated since SimplePie 1.8.0, please use "SimplePie\SimplePie::set_cache()" instead.'), \E_USER_DEPRECATED);
         $this->cache_location = (string) $location;
     }
 
     /**
      * Return the filename (i.e. hash, without path and without extension) of the file to cache a given URL.
+     *
      * @param string $url The URL of the feed to be cached.
      * @return string A filename (i.e. hash, without path and without extension).
      */
@@ -955,7 +967,8 @@ public function get_cache_filename($url)
             ksort($options);
             $url .= '#' . urlencode(var_export($options, true));
         }
-        return call_user_func($this->cache_name_function, $url);
+
+        return $this->cache_namefilter->filter($url);
     }
 
     /**
@@ -1168,15 +1181,33 @@ public function set_useragent($ua = null)
         $this->useragent = (string) $ua;
     }
 
+    /**
+     * Set a namefilter to modify the cache filename with
+     *
+     * @param NameFilter $filter
+     *
+     * @return void
+     */
+    public function set_cache_namefilter(NameFilter $filter): void
+    {
+        $this->cache_namefilter = $filter;
+    }
+
     /**
      * Set callback function to create cache filename with
      *
+     * @deprecated since SimplePie 1.8.0, use {@see set_cache_namefilter()} instead
+     *
      * @param mixed $function Callback function
      */
     public function set_cache_name_function($function = 'md5')
     {
+        // trigger_error(sprintf('"%s()" is deprecated since SimplePie 1.8.0, please use "SimplePie\SimplePie::set_cache_namefilter()" instead.', __METHOD__), \E_USER_DEPRECATED);
+
         if (is_callable($function)) {
             $this->cache_name_function = $function;
+
+            $this->set_cache_namefilter(new CallableNameFilter($this->cache_name_function));
         }
     }
 
@@ -1396,7 +1427,7 @@ public function init()
         $this->sanitize->pass_cache_data(
             $this->enable_cache,
             $this->cache_location,
-            $this->cache_name_function,
+            $this->cache_namefilter,
             $this->registry->get_class('Cache'),
             $this->cache
         );