Initial commit with a Null, Memory, and Predis provider.

Author: Spencer Rinehart

.gitignore

@@ -0,0 +1,3 @@
+/clover.xml
+/coverage/
+/vendor/

.travis.yml

@@ -0,0 +1,7 @@
+language: php
+php:
+  - 5.6
+  - 5.5
+  - 5.4
+  - 5.3
+script: ./build.php

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Dominion Enterprises
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,113 @@
+# Memoize
+A PHP library for memoizing repeated function calls.
+
+## Requirements
+This library requires PHP 5.3, or newer.
+
+## Installation
+This package uses [composer](https://getcomposer.org) so you can just add
+`dominionenterprises/memoize` as a dependency to your `composer.json` file.
+
+## Memoization
+[Memoization](http://en.wikipedia.org/wiki/Memoization) is a way of optimizing a function that is called repeatedly by caching the results of a function call.
+
+## Memoization Providers
+This library includes several built-in providers for memoization.  Each one
+implements the `\DominionEnterprises\Memoize\Memoize` interface:
+```php
+interface Memoize
+{
+    /**
+     * Gets the value stored in the cache or uses the passed function to
+     * compute the value and save to cache.
+     *
+     * @param string $key The key to fetch
+     * @param callable $compute A function to run if the value was not cached
+     *     that will return the result.
+     * @param int $cacheTime The number of seconds to cache the response for,
+     *     or null to not expire it ever.
+     * @return mixed The data requested, optionally pulled from cache
+     */
+    public function memoizeCallable($key, $compute, $cacheTime = null);
+}
+```
+
+The `$compute` callable must not take any parameters - if you need parameters,
+consider wrapping your function in a closure that pulls the required parameters
+into scope.  For example, given the function:
+```php
+$getUser = function($database, $userId) {
+  $query = $database->select('*')->from('user')->where(['id' => $userId]);
+  return $query->fetchOne();
+};
+```
+
+You could wrap this in a closure like so:
+```php
+$getLoggedInUser = function() use($database, $loggedInUserId, $getUser) {
+    return $getUser($database, $loggedInUserId);
+};
+
+$memoize->memoizeCallable("getUser-{$loggedInUserId}", $getLoggedInUser);
+```
+
+Future versions of this library may add support for parameters, as it can be a
+common usecase (especially when it comes to recursive functions.
+
+Also worth noting, is that you need to make sure you define your cache keys
+uniquely for anything using the memoizer.
+
+### Predis
+The predis provider uses the [predis](https://github.com/nrk/predis) library to
+cache the results in Redis.  It supports the `$cacheTime` parameter so that
+results can be recomputed after the time expires.
+
+This memoizer can be used in a way that makes it persistent between processes
+rather than only caching computation for the current process.
+
+#### Example
+```php
+$predis = new \Predis\Client($redisUrl);
+$memoize = new \DominionEnterprises\Memoize\Predis($predis);
+
+$compute = function() {
+    // Perform some long operation that you want to memoize
+};
+
+// Cache he results of $compute for 1 hour.
+$result = $memoize->memoizeCallable('myLongOperation', $compute, 3600);
+```
+
+### Memory
+This is a standard in-memory memoizer.  It does not support `$cacheTime` at the
+moment and only keeps the results around as long as the memoizer is in memory.
+
+#### Example
+```php
+$memoize = new \DominionEnterprises\Memoize\Memory();
+
+$compute = function() {
+    // Perform some long operation that you want to memoize
+};
+
+$result = $memoize->memoizeCallable('myLongOperation', $compute);
+```
+
+### Null
+This memoizer does not actually memoize anything - it always calls the
+`$compute` function.  It is useful for testing and can also be used when you
+disable memoization for debugging, etc. because you can swap your real memoizer
+out for this one and everything will still work.
+
+#### Example
+```php
+$memoize = new \DominionEnterprises\Memoize\Null();
+
+$compute = function() {
+    // Perform some long operation that you want to memoize
+};
+
+// This will never actually memoize the results - they will be recomputed every
+// time.
+$result = $memoize->memoizeCallable('myLongOperation', $compute);
+```

build.php

@@ -0,0 +1,29 @@
+#!/usr/bin/env php
+<?php
+chdir(__DIR__);
+
+$returnStatus = null;
+passthru('composer install --dev', $returnStatus);
+if ($returnStatus !== 0) {
+    exit(1);
+}
+
+passthru('./vendor/bin/phpcs --standard=PSR1 -n src tests *.php', $returnStatus);
+if ($returnStatus !== 0) {
+    exit(1);
+}
+
+passthru('./vendor/bin/phpunit --coverage-html coverage --coverage-clover clover.xml --strict tests', $returnStatus);
+if ($returnStatus !== 0) {
+    exit(1);
+}
+
+$xml = new SimpleXMLElement(file_get_contents('clover.xml'));
+foreach ($xml->xpath('//file/metrics') as $metric) {
+    if ((int)$metric['elements'] !== (int)$metric['coveredelements']) {
+        file_put_contents('php://stderr', "Code coverage was NOT 100%\n");
+        exit(1);
+    }
+}
+
+echo "Code coverage was 100%\n";

composer.json

@@ -0,0 +1,28 @@
+{
+    "name": "dominionenterprises/memoize",
+    "description": "A library for memoizing repeated function calls.",
+    "keywords": ["memoization", "predis", "cache", "optimization"],
+    "authors": [
+        {
+            "name": "Spencer Rinehart",
+            "email": "anubis@overthemonkey.com",
+            "role": "Developer"
+        }
+    ],
+    "license": "MIT",
+    "require": {
+        "php": ">=5.3.2"
+    },
+    "require-dev": {
+        "predis/predis": "~0.8.4",
+        "phpunit/phpunit": "~4.0",
+        "squizlabs/php_codesniffer": "~1.5",
+        "lib-libxml": "*"
+    },
+    "suggest": {
+        "predis/predis": "Allows for Redis-based memoization."
+    },
+    "autoload": {
+        "psr-4": { "DominionEnterprises\\Memoize\\": "src/" }
+    }
+}