rename page filters prop

2026-09-24 15:42:09 +08:00 · 2024-06-24 19:05:48 +01:00
parent 5fad9fc09f
commit 0a4d67b6fc
4 changed files with 72 additions and 6 deletions
@@ -144,7 +144,7 @@ class Dashboard extends BaseDashboard
 }
 ```

-In widget classes that require data from the filters, you need to add the `InteractsWithPageFilters` trait, which will allow you to use the `$this->filters` property to access the raw data from the filters form:
+In widget classes that require data from the filters, you need to add the `InteractsWithPageFilters` trait, which will allow you to use the `$this->pageFilters` property to access the raw data from the filters form:

 ```php
 use App\Models\BlogPost;
@@ -159,8 +159,8 @@ class BlogPostsOverview extends StatsOverviewWidget

    public function getStats(): array
    {
-        $startDate = $this->filters['startDate'] ?? null;
-        $endDate = $this->filters['endDate'] ?? null;
+        $startDate = $this->pageFilters['startDate'] ?? null;
+        $endDate = $this->pageFilters['endDate'] ?? null;

        return [
            StatsOverviewWidget\Stat::make(
@@ -176,7 +176,7 @@ class BlogPostsOverview extends StatsOverviewWidget
 }
 ```

-The `$this->filters` array will always reflect the current form data. Please note that this data is not validated, as it is available live and not intended to be used for anything other than querying the database. You must ensure that the data is valid before using it. In this example, we check if the start date is set before using it in the query.
+The `$this->pageFilters` array will always reflect the current form data. Please note that this data is not validated, as it is available live and not intended to be used for anything other than querying the database. You must ensure that the data is valid before using it. In this example, we check if the start date is set before using it in the query.

 ### Filtering widget data using an action modal

@@ -7,7 +7,7 @@
        :columns="$this->getColumns()"
        :data="
            [
-                ...(property_exists($this, 'filters') ? ['filters' => $this->filters] : []),
+                ...(property_exists($this, 'filters') ? ['pageFilters' => $this->filters] : []),
                ...$this->getWidgetData(),
            ]
        "
@@ -2,6 +2,7 @@

 namespace Filament\Widgets\Concerns;

+use Livewire\Attributes\Computed;
 use Livewire\Attributes\Reactive;

 trait InteractsWithPageFilters
@@ -10,5 +11,15 @@ trait InteractsWithPageFilters
     * @var array<string, mixed> | null
     */
    #[Reactive]
-    public ?array $filters = null;
+    public ?array $pageFilters = null;
+
+    public function __get($property)
+    {
+        // Backwards compatibility for the `$this->filters` property before it was renamed.
+        if ($property === 'filters') {
+            return $this->pageFilters;
+        }
+
+        return parent::__get($property);
+    }
 }
@@ -0,0 +1,55 @@
+---
+title: Upgrading from v4.x
+---
+
+> If you see anything missing from this guide, please do not hesitate to [make a pull request](https://github.com/filamentphp/filament/edit/4.x/packages/widgets/docs/10-upgrade-guide.md) to our repository! Any help is appreciated!
+
+## New requirements
+
+- Tailwind CSS v4.0+
+
+## Upgrading automatically
+
+The easiest way to upgrade your app is to run the automated upgrade script. This script will automatically upgrade your application to the latest version of Filament, and make changes to your code which handle most breaking changes.
+
+```bash
+composer require filament/upgrade:"^4.0" -W --dev
+vendor/bin/filament-v4
+```
+
+Make sure to carefully follow the instructions, and review the changes made by the script. You may need to make some manual changes to your code afterwards, but the script should handle most of the repetitive work for you.
+
+Finally, you must run `php artisan filament:install` to finalize the Filament v4 installation. This command must be run for all new Filament projects.
+
+You can now `composer remove filament/upgrade` as you don't need it anymore.
+
+> Some plugins you're using may not be available in v4 just yet. You could temporarily remove them from your `composer.json` file until they've been upgraded, replace them with a similar plugins that are v4-compatible, wait for the plugins to be upgraded before upgrading your app, or even write PRs to help the authors upgrade them.
+
+## Upgrading manually
+
+After upgrading the dependency via Composer, you should execute `php artisan filament:upgrade` in order to clear any Laravel caches and publish the new frontend assets.
+
+### High-impact changes
+
+### Medium-impact changes
+
+#### The `InteractsWithPageFilters` `$filters` property is now `$pageFilters`
+
+In v3, the `$this->filters` property from the `InteractsWithPageFilters` trait was used to access the raw data from the filters form. In v4, this property has been renamed to `$this->pageFilters`, to avoid conflicts with the new `$filters` property that can be used to access filter values from a chart widget's filter form.
+
+
+```diff
+use InteractsWithPageFilters;
+
+public function getStats(): array
+{
+-    $startDate = $this->filters['startDate'] ?? null;
+-    $endDate = $this->filters['endDate'] ?? null;
+    $startDate = $this->pageFilters['startDate'] ?? null;
+    $endDate = $this->pageFilters['endDate'] ?? null;
+
+    return [
+        // ...
+    ];
+}
+```