Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
96.88% covered (success)
96.88%
31 / 32
83.33% covered (warning)
83.33%
5 / 6
 CRAP
0.00% covered (danger)
0.00%
0 / 1
MemoizedCallable
96.88% covered (success)
96.88%
31 / 32
83.33% covered (warning)
83.33%
5 / 6
 14
0.00% covered (danger)
0.00%
0 / 1
 __construct
100.00% covered (success)
100.00%
9 / 9
100.00% covered (success)
100.00%
1 / 1
 3
 fetchResult
75.00% covered (warning)
75.00%
3 / 4
0.00% covered (danger)
0.00%
0 / 1
 2.06
 storeResult
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 2
 invokeArgs
100.00% covered (success)
100.00%
14 / 14
100.00% covered (success)
100.00%
1 / 1
 5
 invoke
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 call
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
1<?php
2/**
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
17 *
18 * @file
19 * @author Ori Livneh
20 */
21
22/**
23 * APCu-backed function memoization
24 *
25 * This class provides memoization for pure functions. A function is pure
26 * if its result value depends on nothing other than its input parameters
27 * and if invoking it does not cause any side-effects.
28 *
29 * The first invocation of the memoized callable with a particular set of
30 * arguments will be delegated to the underlying callable. Repeat invocations
31 * with the same input parameters will be served from APCu.
32 *
33 * @par Example:
34 * @code
35 * $memoizedStrrev = new MemoizedCallable( 'range' );
36 * $memoizedStrrev->invoke( 5, 8 );  // result: array( 5, 6, 7, 8 )
37 * $memoizedStrrev->invokeArgs( array( 5, 8 ) );  // same
38 * MemoizedCallable::call( 'range', array( 5, 8 ) );  // same
39 * @endcode
40 *
41 * @since 1.27
42 */
43class MemoizedCallable {
44
45    /** @var callable */
46    private $callable;
47
48    /** @var string Unique name of callable; used for cache keys. */
49    private $callableName;
50
51    /** @var int */
52    private $ttl;
53
54    /**
55     * @param callable $callable Function or method to memoize.
56     * @param int $ttl TTL in seconds. Defaults to 3600 (1hr). Capped at 86400 (24h).
57     */
58    public function __construct( $callable, $ttl = 3600 ) {
59        if ( !is_callable( $callable, false, $this->callableName ) ) {
60            throw new InvalidArgumentException(
61                'Argument 1 passed to MemoizedCallable::__construct() must ' .
62                'be an instance of callable; ' . get_debug_type( $callable ) . ' given'
63            );
64        }
65
66        if ( $this->callableName === 'Closure::__invoke' ) {
67            throw new InvalidArgumentException( 'Cannot memoize unnamed closure' );
68        }
69
70        $this->callable = $callable;
71        $this->ttl = min( max( $ttl, 1 ), 86400 );
72    }
73
74    /**
75     * Fetch the result of a previous invocation.
76     *
77     * @param string $key
78     * @param bool &$success
79     * @return bool
80     */
81    protected function fetchResult( $key, &$success ) {
82        $success = false;
83        if ( function_exists( 'apcu_fetch' ) ) {
84            return apcu_fetch( $key, $success );
85        }
86        return false;
87    }
88
89    /**
90     * Store the result of an invocation.
91     *
92     * @param string $key
93     * @param mixed $result
94     */
95    protected function storeResult( $key, $result ) {
96        if ( function_exists( 'apcu_store' ) ) {
97            apcu_store( $key, $result, $this->ttl );
98        }
99    }
100
101    /**
102     * Invoke the memoized function or method.
103     *
104     * @throws InvalidArgumentException If parameters list contains non-scalar items.
105     * @param array $args Parameters for memoized function or method.
106     * @return mixed The memoized callable's return value.
107     */
108    public function invokeArgs( array $args = [] ) {
109        foreach ( $args as $arg ) {
110            if ( $arg !== null && !is_scalar( $arg ) ) {
111                throw new InvalidArgumentException(
112                    'MemoizedCallable::invoke() called with non-scalar ' .
113                    'argument'
114                );
115            }
116        }
117
118        $hash = md5( serialize( $args ) );
119        $key = __CLASS__ . ':' . $this->callableName . ':' . $hash;
120        $success = false;
121        $result = $this->fetchResult( $key, $success );
122        if ( !$success ) {
123            $result = ( $this->callable )( ...$args );
124            $this->storeResult( $key, $result );
125        }
126
127        return $result;
128    }
129
130    /**
131     * Invoke the memoized function or method.
132     *
133     * Like MemoizedCallable::invokeArgs(), but variadic.
134     *
135     * @param mixed ...$params Parameters for memoized function or method.
136     * @return mixed The memoized callable's return value.
137     */
138    public function invoke( ...$params ) {
139        return $this->invokeArgs( $params );
140    }
141
142    /**
143     * Shortcut method for creating a MemoizedCallable and invoking it
144     * with the specified arguments.
145     *
146     * @param callable $callable
147     * @param array $args
148     * @param int $ttl
149     * @return mixed
150     */
151    public static function call( $callable, array $args = [], $ttl = 3600 ) {
152        $instance = new self( $callable, $ttl );
153        return $instance->invokeArgs( $args );
154    }
155}