From 0a4d67b6fcb65ae1ec2eab98de15fec283667cd6 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Mon, 24 Jun 2024 19:05:48 +0100 Subject: [PATCH] rename page filters prop --- packages/panels/docs/05-dashboard.md | 8 +-- .../resources/views/pages/dashboard.blade.php | 2 +- .../Concerns/InteractsWithPageFilters.php | 13 ++++- packages/widgets/docs/06-upgrade-guide.md | 55 +++++++++++++++++++ 4 files changed, 72 insertions(+), 6 deletions(-) create mode 100644 packages/widgets/docs/06-upgrade-guide.md diff --git a/packages/panels/docs/05-dashboard.md b/packages/panels/docs/05-dashboard.md index 5cf8c5ce64..1efec631b4 100644 --- a/packages/panels/docs/05-dashboard.md +++ b/packages/panels/docs/05-dashboard.md @@ -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 diff --git a/packages/panels/resources/views/pages/dashboard.blade.php b/packages/panels/resources/views/pages/dashboard.blade.php index d6614ba391..a6c07128d0 100644 --- a/packages/panels/resources/views/pages/dashboard.blade.php +++ b/packages/panels/resources/views/pages/dashboard.blade.php @@ -7,7 +7,7 @@ :columns="$this->getColumns()" :data=" [ - ...(property_exists($this, 'filters') ? ['filters' => $this->filters] : []), + ...(property_exists($this, 'filters') ? ['pageFilters' => $this->filters] : []), ...$this->getWidgetData(), ] " diff --git a/packages/panels/src/Widgets/Concerns/InteractsWithPageFilters.php b/packages/panels/src/Widgets/Concerns/InteractsWithPageFilters.php index 6976d17058..242ba2ed32 100644 --- a/packages/panels/src/Widgets/Concerns/InteractsWithPageFilters.php +++ b/packages/panels/src/Widgets/Concerns/InteractsWithPageFilters.php @@ -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 | 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); + } } diff --git a/packages/widgets/docs/06-upgrade-guide.md b/packages/widgets/docs/06-upgrade-guide.md new file mode 100644 index 0000000000..70b38563a6 --- /dev/null +++ b/packages/widgets/docs/06-upgrade-guide.md @@ -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 [ + // ... + ]; +} +```