Add filterable caching system with auto-invalidation.

config/filterable.php

@@ -729,4 +729,136 @@
         */
         'enabled' => env('FILTERABLE_EVENTS_ENABLED', true),
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Caching System
+    |--------------------------------------------------------------------------
+    |
+    | Configure the filterable caching system, which intelligently caches
+    | filtered query results to improve performance for frequently-used filters.
+    |
+    */
+    'cache' => [
+
+        /*
+        |--------------------------------------------------------------------------
+        | Enable or Disable Caching
+        |--------------------------------------------------------------------------
+        |
+        | This option allows you to enable or disable the caching system globally.
+        | When disabled, no caching will occur even if explicitly requested in code.
+        |
+        */
+        'enabled' => env('FILTERABLE_CACHE_ENABLED', true),
+
+        /*
+        |--------------------------------------------------------------------------
+        | Default Cache Driver
+        |--------------------------------------------------------------------------
+        |
+        | The cache driver to use for storing filterable results.
+        | You can use any Laravel cache driver: redis, memcached, file, etc.
+        | Defaults to the application's default cache driver if not specified.
+        |
+        */
+        'driver' => env('FILTERABLE_CACHE_DRIVER', null),
+
+        /*
+        |--------------------------------------------------------------------------
+        | Default Cache TTL (Time To Live)
+        |--------------------------------------------------------------------------
+        |
+        | The default time in seconds that cached results will be stored.
+        | This can be overridden on a per-filter basis using cache($ttl).
+        |
+        */
+        'default_ttl' => env('FILTERABLE_CACHE_TTL', 3600), // 1 hour
+
+        /*
+        |--------------------------------------------------------------------------
+        | Cache Key Prefix
+        |--------------------------------------------------------------------------
+        |
+        | A prefix prepended to all cache keys generated by the filterable system.
+        | This helps organize cache entries and avoid key collisions.
+        |
+        */
+        'prefix' => env('FILTERABLE_CACHE_PREFIX', 'filterable'),
+
+        /*
+        |--------------------------------------------------------------------------
+        | Cache Key Version
+        |--------------------------------------------------------------------------
+        |
+        | A version string included in cache keys. Increment this to invalidate
+        | all existing cached entries after deploying breaking changes to filters.
+        |
+        */
+        'version' => env('FILTERABLE_CACHE_VERSION', 'v1'),
+
+        /*
+        |--------------------------------------------------------------------------
+        | Cache Profiles
+        |--------------------------------------------------------------------------
+        |
+        | Define reusable cache profiles with predefined TTL and tags.
+        | These can be used via cacheProfile('profile_name') for consistency.
+        |
+        | Example:
+        | 'profiles' => [
+        |     'heavy_reports' => [
+        |         'ttl' => 7200,
+        |         'tags' => ['reports', 'analytics'],
+        |     ],
+        |     'quick_filters' => [
+        |         'ttl' => 300,
+        |         'tags' => ['filters'],
+        |     ],
+        | ],
+        |
+        */
+        'profiles' => [
+            // Define your cache profiles here
+        ],
+
+        /*
+        |--------------------------------------------------------------------------
+        | Auto-Invalidation
+        |--------------------------------------------------------------------------
+        |
+        | Automatically invalidate cached results when related models are modified.
+        | Maps model classes to cache tags that should be flushed on changes.
+        |
+        | Example:
+        | 'auto_invalidate' => [
+        |     'enabled' => true,
+        |     'models' => [
+        |         App\Models\Post::class => ['posts', 'content'],
+        |         App\Models\User::class => ['users'],
+        |     ],
+        | ],
+        |
+        */
+        'auto_invalidate' => [
+            'enabled' => env('FILTERABLE_AUTO_INVALIDATE', false),
+            'models' => [
+                // Define model-to-tags mappings here
+            ],
+        ],
+
+        /*
+        |--------------------------------------------------------------------------
+        | Cache Tracking
+        |--------------------------------------------------------------------------
+        |
+        | Enable tracking of cache hit/miss statistics for monitoring and
+        | performance optimization. Requires profiler to be enabled.
+        |
+        */
+        'tracking' => [
+            'enabled' => env('FILTERABLE_CACHE_TRACKING', false),
+            'log_channel' => env('FILTERABLE_CACHE_LOG_CHANNEL', 'daily'),
+        ],
+    ],
 ];

docs/.vuepress/config.js

@@ -43,6 +43,10 @@ export default defineUserConfig({
                     "/cli/inspect.md",
                 ],
             },
+            {
+                text: "Advanced",
+                children: ["/caching/overview"],
+            },
         ],
         sidebar: [
             {
@@ -136,7 +140,7 @@ export default defineUserConfig({
                 ],
             },
             {
-                text: "API",
+                text: "API Reference",
                 collapsible: true,
                 children: [
                     {
@@ -157,6 +161,48 @@ export default defineUserConfig({
                     },
                 ],
             },
+            {
+                text: "Caching",
+                collapsible: true,
+                children: [
+                    {
+                        text: "Overview",
+                        link: "caching/overview",
+                    },
+                    {
+                        text: "Getting Started",
+                        link: "caching/getting-started",
+                    },
+                    {
+                        text: "Strategies",
+                        link: "caching/strategies",
+                    },
+                    {
+                        text: "Auto Invalidation",
+                        link: "caching/auto-invalidation",
+                    },
+                    {
+                        text: "Cache Profiles",
+                        link: "caching/profiles",
+                    },
+                    {
+                        text: "Scoping Cache",
+                        link: "caching/scoping",
+                    },
+                    {
+                        text: "Monitoring Cached Items",
+                        link: "caching/monitoring",
+                    },
+                    {
+                        text: "API Reference",
+                        link: "caching/api-reference",
+                    },
+                    {
+                        text: "Examples",
+                        link: "caching/examples",
+                    },
+                ],
+            },
             {
                 text: "CLI",
                 collapsible: true,