Fix query string hydration

Author: afonic

config/config.php

@@ -16,7 +16,7 @@
     // The addon will calculate the number of entries for each filter value (can be slow for a large number of entries)
     'enable_filter_values_count' => false,
 
-    // Enable custom query string
+    // Enable custom query string (ignored when enable_query_string is true)
     'custom_query_string' => false,
 
     // Set the aliases for each custom query string parameter

src/Http/Livewire/LivewireCollection.php

@@ -5,6 +5,7 @@
 use Livewire\Attributes\Locked;
 use Livewire\Attributes\On;
 use Livewire\Component;
+use Reach\StatamicLivewireFilters\Support\CustomQueryString;
 use Reach\StatamicLivewireFilters\Support\Nocache;
 use Statamic\Support\Traits\Hookable;
 use Statamic\Tags\Collection\Entries;
@@ -145,7 +146,7 @@ public function sortUpdated($sort)
 
     protected function queryString()
     {
-        if (config('statamic-livewire-filters.enable_query_string')) {
+        if (CustomQueryString::livewireQueryStringEnabled()) {
             return [
                 'params' => ['except' => []],
             ];
@@ -154,7 +155,7 @@ protected function queryString()
         // When using custom query string, disable Livewire's pagination URL handling
         // to prevent a double pushState (which causes an extra render).
         // We handle pagination URL ourselves in updateCustomQueryStringUrl().
-        if (config('statamic-livewire-filters.custom_query_string') !== false) {
+        if (CustomQueryString::enabled()) {
             return [
                 'paginators.page' => ['except' => '', 'history' => false],
             ];

src/Http/Livewire/Traits/HandleParams.php

@@ -6,6 +6,7 @@
 use Livewire\Attributes\On;
 use Livewire\Attributes\Renderless;
 use Reach\StatamicLivewireFilters\Http\Livewire\LfTags;
+use Reach\StatamicLivewireFilters\Support\CustomQueryString;
 
 trait HandleParams
 {
@@ -28,11 +29,7 @@ public function setParameters($params)
 
     protected function handleCustomQueryStringParams(): array|bool
     {
-        if (
-            config('statamic-livewire-filters.custom_query_string') !== false &&
-            config('statamic-livewire-filters.enable_query_string') === false &&
-            request()->has('params')
-        ) {
+        if (CustomQueryString::enabled() && request()->has('params')) {
             // Get and validate params
             $params = request()->validate([
                 'params' => 'array',
@@ -253,14 +250,14 @@ protected function handlePresetParams()
     #[Renderless, On('preset-params')]
     public function updateCustomQueryStringUrl(): void
     {
-        if (config('statamic-livewire-filters.custom_query_string') === false) {
+        $prefix = CustomQueryString::prefix();
+
+        if ($prefix === false) {
             return;
         }
 
         $aliases = $this->getConfigAliases();
 
-        $prefix = config('statamic-livewire-filters.custom_query_string', 'filters');
-
         // Only include params that have aliases configured
         $segments = collect($this->params)
             ->filter(fn ($value, $key) => isset($aliases[$key]))
@@ -338,10 +335,10 @@ protected function getConfigAliases(): array
 
     protected function stripCustomQueryStringPrefix(string $path): string
     {
-        $prefix = config('statamic-livewire-filters.custom_query_string', 'filters');
+        $prefix = CustomQueryString::prefix();
         $segments = array_values(array_filter(explode('/', trim($path, '/')), fn ($segment) => $segment !== ''));
 
-        if (! $prefix) {
+        if ($prefix === false) {
             return implode('/', $segments);
         }
 

src/Http/Middleware/HandleFiltersQueryString.php

@@ -5,15 +5,18 @@
 use Closure;
 use Illuminate\Http\Request;
 use Illuminate\Support\Str;
+use Reach\StatamicLivewireFilters\Support\CustomQueryString;
 use Reach\StatamicLivewireFilters\Support\Nocache;
 
 class HandleFiltersQueryString
 {
     /**
      * Keys we must never overwrite when hydrating the request from the target URL's
      * query string, since Statamic's nocache controller and Livewire rely on them.
+     * Note that `params` is intentionally not reserved: it is the query key Livewire
+     * uses to restore filter state when `enable_query_string` is on.
      */
-    protected const RESERVED_INPUT_KEYS = ['url', 'params', '_token', '_method', 'fingerprint', 'serialized', 'effects'];
+    protected const RESERVED_INPUT_KEYS = ['url', '_token', '_method', 'fingerprint', 'serialized', 'effects'];
 
     public function handle(Request $request, Closure $next): mixed
     {
@@ -42,10 +45,10 @@ public function handle(Request $request, Closure $next): mixed
         } else {
             $path = $request->path();
         }
-        $prefix = config('statamic-livewire-filters.custom_query_string', 'filters');
+        $prefix = CustomQueryString::prefix();
 
         $segments = explode('/', $path);
-        $filterIndex = array_search($prefix, $segments);
+        $filterIndex = array_search($prefix, $segments, true);
 
         if ($filterIndex !== false) {
             // Extract and parse filter segments
@@ -92,15 +95,15 @@ protected function hydrateNocacheRequestFromUrl(Request $request): void
             return;
         }
 
-        if (config('statamic-livewire-filters.enable_query_string') === true) {
+        if (CustomQueryString::livewireQueryStringEnabled()) {
             $this->hydrateFromOriginalQueryString($request, $parsed);
 
             return;
         }
 
-        $prefix = config('statamic-livewire-filters.custom_query_string', 'filters');
+        $prefix = CustomQueryString::prefix();
 
-        if (! $prefix) {
+        if ($prefix === false) {
             return;
         }
 
@@ -130,7 +133,7 @@ protected function hydrateNocacheRequestFromUrl(Request $request): void
             $normalized .= ':'.$parsed['port'];
         }
 
-        $normalized .= $basePath === '/' ? '' : $basePath;
+        $normalized .= $basePath === '/' ? '/' : $basePath;
 
         if (! empty($parsed['query'])) {
             $normalized .= '?'.$parsed['query'];
@@ -166,7 +169,7 @@ protected function hydrateFromOriginalQueryString(Request $request, array $parse
 
     protected function shouldSkip(): bool
     {
-        return config('statamic-livewire-filters.custom_query_string') === false || config('statamic-livewire-filters.enable_query_string') === true;
+        return ! CustomQueryString::enabled();
     }
 
     protected function shouldProcessRequest(Request $request): bool

src/Support/CustomQueryString.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Reach\StatamicLivewireFilters\Support;
+
+class CustomQueryString
+{
+    public static function livewireQueryStringEnabled(): bool
+    {
+        return (bool) config('statamic-livewire-filters.enable_query_string');
+    }
+
+    /**
+     * The active custom query string prefix, or false when the feature is off.
+     *
+     * Only one URL mode may be active at a time: when `enable_query_string`
+     * is on, Livewire's own query string handling wins and the custom
+     * prefix is treated as disabled.
+     */
+    public static function prefix(): string|false
+    {
+        if (static::livewireQueryStringEnabled()) {
+            return false;
+        }
+
+        $prefix = config('statamic-livewire-filters.custom_query_string', 'filters');
+
+        return is_string($prefix) && $prefix !== '' ? $prefix : false;
+    }
+
+    public static function enabled(): bool
+    {
+        return static::prefix() !== false;
+    }
+}