├── config
    └── config.php
├── .github
    ├── FUNDING.yml
    ├── dependabot.yml
    └── workflows
    │   └── php.yml
├── LICENSE.md
├── phpunit.xml
├── src
    ├── RememberableQueryServiceProvider.php
    └── RememberableQuery.php
├── composer.json
└── README.md


/config/config.php:
--------------------------------------------------------------------------------
1 | <?php
2 | 
3 | /*
4 |  * You can place your custom package configuration in here.
5 |  */
6 | return [
7 | 
8 | ];


--------------------------------------------------------------------------------
/.github/FUNDING.yml:
--------------------------------------------------------------------------------
1 | # Help me support this package
2 | 
3 | ko_fi: DarkGhostHunter
4 | custom: ['https://paypal.me/darkghosthunter']
5 | 


--------------------------------------------------------------------------------
/.github/dependabot.yml:
--------------------------------------------------------------------------------
1 | version: 2
2 | updates:
3 | - package-ecosystem: composer
4 |   directory: "/"
5 |   schedule:
6 |     interval: daily
7 |     time: "09:00"
8 |   open-pull-requests-limit: 10
9 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) Italo Israel Baeza Cabrera
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.


--------------------------------------------------------------------------------
/phpunit.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8"?>
 2 | <phpunit bootstrap="vendor/autoload.php"
 3 |          backupGlobals="false"
 4 |          backupStaticAttributes="false"
 5 |          colors="true"
 6 |          verbose="true"
 7 |          convertErrorsToExceptions="true"
 8 |          convertNoticesToExceptions="true"
 9 |          convertWarningsToExceptions="true"
10 |          processIsolation="false"
11 |          stopOnFailure="false">
12 |     <testsuites>
13 |         <testsuite name="Test Suite">
14 |             <directory>tests</directory>
15 |         </testsuite>
16 |     </testsuites>
17 |     <filter>
18 |         <whitelist>
19 |             <directory suffix=".php">src/</directory>
20 |         </whitelist>
21 |     </filter>
22 |     <logging>
23 |         <log type="coverage-clover" target="build/logs/clover.xml"/>
24 |     </logging>
25 |     <php>
26 |         <env name="APP_ENV" value="testing"/>
27 |         <env name="APP_KEY" value="AckfSECXIvnK5r28GVIWUAxmbBSjTsmF"/>
28 |         <env name="DB_CONNECTION" value="sqlite"/>
29 |         <env name="DB_DATABASE" value=":memory:"/>
30 |         <env name="CACHE_DRIVER" value="array"/>
31 |     </php>
32 | </phpunit>
33 | 


--------------------------------------------------------------------------------
/src/RememberableQueryServiceProvider.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace DarkGhostHunter\RememberableQuery;
 4 | 
 5 | use DateInterval;
 6 | use DateTimeInterface;
 7 | use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
 8 | use Illuminate\Database\Query\Builder as QueryBuilder;
 9 | use Illuminate\Support\ServiceProvider;
10 | 
11 | class RememberableQueryServiceProvider extends ServiceProvider
12 | {
13 |     /**
14 |      * Bootstrap the application services.
15 |      *
16 |      * @return void
17 |      */
18 |     public function boot(): void
19 |     {
20 |         $function = function (
21 |             int|DateTimeInterface|DateInterval $ttl = 60,
22 |             string $key = null,
23 |             string $store = null,
24 |             int $wait = 0,
25 |         ): RememberableQuery {
26 |             return new RememberableQuery(resolve('cache'), $this, $ttl, $key, $store, $wait);
27 |         };
28 | 
29 |         if (!QueryBuilder::hasMacro('remember')) {
30 |             QueryBuilder::macro('remember', $function);
31 |         }
32 | 
33 |         if (!EloquentBuilder::hasGlobalMacro('remember')) {
34 |             EloquentBuilder::macro('remember', $function);
35 |         }
36 |     }
37 | }
38 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "darkghosthunter/rememberable-query",
 3 |     "description": "Remember a Query results in one expressive line",
 4 |     "keywords": [
 5 |         "darkghosthunter",
 6 |         "sql",
 7 |         "database",
 8 |         "cache",
 9 |         "laravel"
10 |     ],
11 |     "homepage": "https://github.com/darkghosthunter/rememberablequery",
12 |     "license": "MIT",
13 |     "type": "library",
14 |     "authors": [
15 |         {
16 |             "name": "Italo Israel Baeza Cabrera",
17 |             "email": "darkghosthunter@gmail.com",
18 |             "role": "Developer"
19 |         }
20 |     ],
21 |     "require": {
22 |         "php": "^8.0",
23 |         "illuminate/database": "^8.0|^9.0",
24 |         "illuminate/support": "^8.0|^9.0"
25 |     },
26 |     "require-dev": {
27 |         "orchestra/testbench": "^6.19|^7.0",
28 |         "phpunit/phpunit": "^9.5.8",
29 |         "mockery/mockery": "^1.4"
30 |     },
31 |     "autoload": {
32 |         "psr-4": {
33 |             "DarkGhostHunter\\RememberableQuery\\": "src/"
34 |         }
35 |     },
36 |     "autoload-dev": {
37 |         "psr-4": {
38 |             "Tests\\": "tests/"
39 |         }
40 |     },
41 |     "scripts": {
42 |         "test": "vendor/bin/phpunit"
43 |     },
44 |     "config": {
45 |         "sort-packages": true
46 |     },
47 |     "extra": {
48 |         "laravel": {
49 |             "providers": [
50 |                 "DarkGhostHunter\\RememberableQuery\\RememberableQueryServiceProvider"
51 |             ]
52 |         }
53 |     }
54 | }
55 | 


--------------------------------------------------------------------------------
/.github/workflows/php.yml:
--------------------------------------------------------------------------------
 1 | name: Tests
 2 | 
 3 | on:
 4 |   push:
 5 |   pull_request:
 6 | 
 7 | jobs:
 8 |   test:
 9 | 
10 |     runs-on: ubuntu-latest
11 |     strategy:
12 |       fail-fast: true
13 |       matrix:
14 |         php: [8.0, 8.1]
15 |         laravel: [^8.71, 9.*]
16 |         dependency-version: [prefer-lowest, prefer-stable]
17 |         include:
18 |           - laravel: 9.*
19 |             testbench: 7.*
20 |           - laravel: ^8.71
21 |             testbench: ^6.16
22 | 
23 |     name: PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }} - ${{ matrix.dependency-version }}
24 | 
25 |     steps:
26 |     - name: Checkout
27 |       uses: actions/checkout@v2
28 | 
29 |     - name: Setup PHP
30 |       uses: shivammathur/setup-php@v2
31 |       with:
32 |         php-version: ${{ matrix.php }}
33 |         extensions: mbstring, intl
34 |         coverage: xdebug
35 | 
36 |     - name: Cache dependencies
37 |       uses: actions/cache@v2
38 |       with:
39 |         path: ~/.composer/cache/files
40 |         key: ${{ runner.os }}-laravel-${{ matrix.laravel }}-php-${{ matrix.php }}-composer-${{ hashFiles('composer.json') }}
41 |         restore-keys: ${{ runner.os }}-laravel-${{ matrix.laravel }}-php-${{ matrix.php }}-composer-
42 | 
43 |     - name: Install dependencies
44 |       run: |
45 |           composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-progress --no-update
46 |           composer update --${{ matrix.dependency-version }} --prefer-dist --no-progress --no-suggest
47 | 
48 |     - name: Run Tests
49 |       run: composer run-script test
50 | 
51 |     - name: Upload Coverage to Coveralls
52 |       env:
53 |         COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
54 |         COVERALLS_SERVICE_NAME: github
55 |       run: |
56 |         rm -rf composer.* vendor/
57 |         composer require php-coveralls/php-coveralls
58 |         vendor/bin/php-coveralls
59 | 


--------------------------------------------------------------------------------
/src/RememberableQuery.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | namespace DarkGhostHunter\RememberableQuery;
  4 | 
  5 | use DateInterval;
  6 | use DateTimeInterface;
  7 | use Illuminate\Contracts\Cache\Factory;
  8 | use Illuminate\Contracts\Cache\LockProvider as LockProviderAlias;
  9 | use Illuminate\Contracts\Cache\Repository;
 10 | use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
 11 | use Illuminate\Database\Query\Builder;
 12 | use Illuminate\Support\Traits\ForwardsCalls;
 13 | use RuntimeException;
 14 | 
 15 | class RememberableQuery
 16 | {
 17 |     use ForwardsCalls;
 18 | 
 19 |     /**
 20 |      * The Application Cache repository
 21 |      *
 22 |      * @var \Illuminate\Contracts\Cache\Repository
 23 |      */
 24 |     protected Repository $cache;
 25 | 
 26 |     /**
 27 |      * The cache key to use to remember.
 28 |      *
 29 |      * @var string
 30 |      */
 31 |     protected string $cacheKey;
 32 | 
 33 |     /**
 34 |      * RememberableQuery constructor.
 35 |      *
 36 |      * @param  \Illuminate\Contracts\Cache\Factory  $cache
 37 |      * @param  \Illuminate\Database\Eloquent\Builder|\Illuminate\Database\Query\Builder
 38 |      * @param  int|\DateTimeInterface|\DateInterval  $ttl
 39 |      * @param  string|null  $cacheKey
 40 |      * @param  string|null  $store
 41 |      * @param  int  $wait
 42 |      */
 43 |     public function __construct(
 44 |         Factory $cache,
 45 |         protected Builder|EloquentBuilder $builder,
 46 |         protected int|DateTimeInterface|DateInterval $ttl,
 47 |         ?string $cacheKey = null,
 48 |         ?string $store = null,
 49 |         protected int $wait = 0
 50 |     ) {
 51 |         $this->cacheKey = $cacheKey ?? $this->cacheKeyHash();
 52 |         $this->cache = $cache->store($store);
 53 |     }
 54 | 
 55 |     /**
 56 |      * Returns the auto-generated cache key
 57 |      *
 58 |      * @return string
 59 |      */
 60 |     public function cacheKeyHash(): string
 61 |     {
 62 |         return 'query|'.base64_encode(
 63 |             md5($this->builder->toSql().implode('', $this->builder->getBindings()), true)
 64 |         );
 65 |     }
 66 | 
 67 |     /**
 68 |      * Dynamically call the query builder until a result is expected
 69 |      *
 70 |      * @param  string  $method
 71 |      * @param  array  $arguments
 72 |      *
 73 |      * @return mixed
 74 |      */
 75 |     public function __call(string $method, array $arguments): mixed
 76 |     {
 77 |         return $this->cache->remember($this->cacheKey, $this->ttl, function () use ($method, $arguments) {
 78 |             return $this->wait
 79 |                 ? $this->getLockResult($method, $arguments)
 80 |                 : $this->getResult($method, $arguments);
 81 |         });
 82 |     }
 83 | 
 84 |     /**
 85 |      * Returns the results from a lock callback.
 86 |      *
 87 |      * @param  string  $method
 88 |      * @param  array  $arguments
 89 |      *
 90 |      * @return mixed
 91 |      */
 92 |     protected function getLockResult(string $method, array $arguments): mixed
 93 |     {
 94 |         return $this->cache
 95 |             ->lock($this->cacheKey, $this->wait)
 96 |             ->block($this->wait, fn() => $this->getResult($method, $arguments));
 97 |     }
 98 | 
 99 |     /**
100 |      * Forwards the call to the builder and retrieves the result.
101 |      *
102 |      * @param  string  $method
103 |      * @param  array  $arguments
104 |      *
105 |      * @return mixed
106 |      */
107 |     protected function getResult(string $method, array $arguments): mixed
108 |     {
109 |         $result = $this->forwardCallTo($this->builder, $method, $arguments);
110 | 
111 |         // Force the developer to use this as before-last method in the query builder.
112 |         if ($result instanceof Builder || $result instanceof EloquentBuilder) {
113 |             throw new RuntimeException("The `remember()` method call is not before query execution: [$method] called.");
114 |         }
115 | 
116 |         return $result;
117 |     }
118 | }
119 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Package superseeded by [Laragear/CacheQuery](https://github.com/Laragear/CacheQuery)
  2 | 
  3 | ---
  4 | 
  5 | # Rememberable Queries
  6 | 
  7 | Remember your Query results using only one method. Yes, only one.
  8 | 
  9 | ```php
 10 | Articles::latest('published_at')->take(10)->remember()->get();
 11 | ```
 12 | 
 13 | ## Requirements
 14 | 
 15 | * PHP 8.0
 16 | * Laravel 8.x
 17 | 
 18 | ## Installation
 19 | 
 20 | You can install the package via composer:
 21 | 
 22 | ```bash
 23 | composer require darkghosthunter/rememberable-query
 24 | ```
 25 | 
 26 | ## Usage
 27 | 
 28 | Just use the `remember()` method to remember a Query result **before the execution**. That's it. The method automatically remembers the result for 60 seconds.
 29 | 
 30 | ```php
 31 | use Illuminate\Support\Facades\DB;
 32 | use App\Models\Article;
 33 | 
 34 | $database = DB::table('articles')->latest('published_at')->take(10)->remember()->get();
 35 | 
 36 | $eloquent = Article::latest('published_at')->take(10)->remember()->get();
 37 | ```
 38 | 
 39 | The next time you call the **same** query, the result will be retrieved from the cache instead of running the SQL statement in the database, even if the result is `null` or `false`.
 40 | 
 41 | > The `remember()` will throw an error if you build a query instead of executing it.
 42 | 
 43 | ### Time-to-live
 44 | 
 45 | By default, queries are remembered by 60 seconds, but you're free to use any length, `Datetime`, `DateInterval` or Carbon instance.
 46 | 
 47 | ```php
 48 | DB::table('articles')->latest('published_at')->take(10)->remember(60 * 60)->get();
 49 | 
 50 | Article::latest('published_at')->take(10)->remember(now()->addHour())->get();
 51 | ```
 52 | 
 53 | ### Custom Cache Key
 54 | 
 55 | The auto-generated cache key is an BASE64-MD5 hash of the SQL query and its bindings, which avoids any collision with other queries while keeping the cache key short. 
 56 | 
 57 | You can use any string as you want, but is recommended to append `query|` to avoid conflicts with other cache keys in your application.
 58 | 
 59 | ```php
 60 | Article::latest('published_at')->take(10)->remember(30, 'query|latest_articles')->get();
 61 | ```
 62 | 
 63 | Alternatively, you can use an [custom Cache Store](#custom-cache-store) for remembering queries.
 64 | 
 65 | ### Custom Cache Store
 66 | 
 67 | In some scenarios, using the default cache of your application may be detrimental compared to the database performance, or may conflict with other keys. You can use any other Cache Store by setting a third parameter, or a named parameter.
 68 | 
 69 | ```php
 70 | Article::latest('published_at')->take(10)->remember(store: 'redis')->get();
 71 | ```
 72 | 
 73 | ### Cache Lock (data races)
 74 | 
 75 | On multiple processes, the Query may be executed multiple times until the first process is able to store the result in the cache, specially when these take more than 1 second. To avoid this, set the `wait` parameter with the number of seconds to hold the lock acquired.
 76 | 
 77 | ```php
 78 | Article::latest('published_at')->take(200)->remember(wait: 5)->get();
 79 | ```
 80 | 
 81 | The first process will acquire the lock for the given seconds, execute the query and store the result. The next processes will wait until the cache data is available to retrieve the result from there.
 82 | 
 83 | > If you need to use this across multiple processes, use the [cache lock](https://laravel.com/docs/cache#managing-locks-across-processes) directly.
 84 | 
 85 | ### Idempotent queries
 86 | 
 87 | While the reason behind remembering a Query is to cache the data retrieved from a database, you can use this to your advantage to create [idempotent](https://en.wikipedia.org/wiki/Idempotence) queries.
 88 | 
 89 | For example, you can make this query only execute once every day for a given user ID.
 90 | 
 91 | ```php
 92 | $key = auth()->user()->getAuthIdentifier();
 93 | 
 94 | Article::whereKey(54)->remember(now()->addHour(), "query|user:$key")->increment('unique_views');
 95 | ```
 96 | 
 97 | Subsequent executions of this query won't be executed at all until the cache expires, so in the above example we have surprisingly created a "unique views" mechanic.
 98 | 
 99 | ## Operations are **NOT** commutative
100 | 
101 | Altering the Builder methods order will change the auto-generated cache key hash. Even if they are _visually_ the same, the order of statements makes the hash completely different.
102 | 
103 | For example, given two similar queries in different parts of the application, these both will **not** share the same cached result:
104 | 
105 | ```php
106 | User::whereName('Joe')->whereAge(20)->remember()->first();
107 | // Cache key: "query|/XreUO1yaZ4BzH2W6LtBSA=="
108 | 
109 | User::whereAge(20)->whereName('Joe')->remember()->first();
110 | // Cache key: "query|muDJevbVppCsTFcdeZBxsA=="
111 | ```
112 | 
113 | To ensure you're hitting the same cache on similar queries, use a [custom cache key](#custom-cache-key). With this, all queries using the same key will share the same cached result:
114 | 
115 | ```php
116 | User::whereName('Joe')->whereAge(20)->remember(60, 'query|find_joe')->first();
117 | User::whereAge(20)->whereName('Joe')->remember(60, 'query|find_joe')->first();
118 | ```
119 | 
120 | This will allow you to even retrieve the data outside the query, by just asking directly to the cache.
121 | 
122 | ```php
123 | $joe = Cache::get('query|find_joe');
124 | ```
125 | 
126 | ## License
127 | 
128 | The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
129 | 


--------------------------------------------------------------------------------