Filament PWA

https://github.com/tomatophp/filament-pwa
Admin
Filament PWA is a Laravel plugin that adds Progressive Web App support to FilamentPHP panels, with...
Tokens:10,477
Snippets:113
Trust Score:10
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Filament PWA Assets

Source: https://github.com/tomatophp/filament-pwa/blob/master/README.md

Run the installation command for the Filament PWA package after initial setup.

```bash
php artisan filament-pwa:install
```

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

### Install Filament PWA Package

Source: https://github.com/tomatophp/filament-pwa/blob/master/README.md

Install the Filament PWA package using Composer.

```bash
composer require tomatophp/filament-pwa
```

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

### Verify Git Setup

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Confirms that both the 'origin' and 'fork' remotes are correctly configured and that you are on the feature branch.

```bash
git remote -v
git branch
```

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

### Publish Migrations and Install Settings Hub

Source: https://github.com/tomatophp/filament-pwa/blob/master/README.md

Publish the necessary migrations for Laravel Settings and install the Filament Settings Hub.

```bash
php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"
php artisan filament-settings-hub:install
```

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

### Pest Test Case Setup

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Set up Pest tests to use the TestCase class for Feature and Unit tests.

```php
<?php

use Tests\TestCase;

uses(TestCase::class)->in('Feature', 'Unit');
```

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

### Composer Dependency Update

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade-design.md

Example command to update composer dependencies for the Filament v4 upgrade.

```bash
composer update filament/filament --with-dependencies
```

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

### Update Composer Dependencies for Filament PWA v2

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade-design.md

Update your composer.json to require PHP 8.2+ and Filament PWA v2. Then run composer update to install the necessary packages.

```bash
# 1. Update composer.json
"require": {
    "php": "^8.2",
    "tomatophp/filament-pwa": "^2.0"
}

# 2. Update dependencies
composer update

# 3. Clear caches
php artisan optimize:clear

# 4. Republish assets if customized
php artisan vendor:publish --tag="filament-pwa-views" --force
```

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

### Run Full Test Suite

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Execute the complete test suite to ensure all tests pass before proceeding with the upgrade.

```bash
composer test
```

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

### Test PWASettingsPage Header Actions

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Write a failing test to verify that the settings page has a back action in the header before the migration.

```php
test('settings page has back action in header', function () {
    $page = new PWASettingsPage();

    $actions = $page->getHeaderActions();

    expect($actions)->toHaveCount(1);
    expect($actions[0]->getName())->toBe('back');
});
```

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

### Git Add and Commit

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Stage and commit the newly created testing infrastructure files.

```bash
git add phpunit.xml tests/Pest.php tests/TestCase.php testbench.yaml
git commit -m "test: add Pest 4 testing infrastructure"
```

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

### Stage and Commit Documentation Changes

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Stage the modified README.md, UPGRADE.md, and CHANGELOG.md files and commit them with a descriptive message.

```bash
git add README.md UPGRADE.md CHANGELOG.md
git commit -m "docs: update documentation for Filament v4"
```

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

### Configure PWA Shortcuts Repeater

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Sets up a repeater field for defining PWA shortcuts, including name, description, URL, and an icon. This allows for dynamic addition of shortcut links to the PWA.

```php
Repeater::make('pwa_shortcuts')
                        ->schema([
                            TextInput::make('name')
                                ->label(trans('filament-pwa::messages.form.pwa_shortcuts_name')),
                            Textarea::make('description')
                                ->label(trans('filament-pwa::messages.form.pwa_shortcuts_description')),
                            TextInput::make('url')
                                ->url()
                                ->label(trans('filament-pwa::messages.form.pwa_shortcuts_url')),
                            FileUpload::make('icon')
                                ->image()
                                ->visibility('public')
                                ->label(trans('filament-pwa::messages.form.pwa_shortcuts_icon'))
                        ])
```

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

### Add Changelog Entry for v2.0.0

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Prepend the provided markdown to the CHANGELOG.md file to document the v2.0.0 release.

```markdown
# Changelog

## v2.0.0 - 2025-11-20

### Added
- Filament v4 support
- Comprehensive Pest 4 test suite
- Explicit public visibility for all file uploads

### Changed
- **Breaking:** Minimum PHP version is now 8.2
- **Breaking:** Minimum Laravel version is now 11.28
- **Breaking:** Minimum Filament version is now 4.0
- **Breaking:** Migrated from `getFormSchema()` to `form()` method
- **Breaking:** Migrated from `getActions()` to `getHeaderActions()` method
- Updated action namespace from `Filament\Pages\Actions` to `Filament\Actions`

### Removed
- **Breaking:** Dropped support for PHP 8.1
- **Breaking:** Dropped support for Filament v3.x

---

```

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

### Publish Filament PWA Views

Source: https://github.com/tomatophp/filament-pwa/blob/master/README.md

Publish the view files for the Filament PWA package.

```bash
php artisan vendor:publish --tag="filament-pwa-views"
```

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

### Publish Filament PWA Configuration

Source: https://github.com/tomatophp/filament-pwa/blob/master/README.md

Publish the configuration file for the Filament PWA package.

```bash
php artisan vendor:publish --tag="filament-pwa-config"
```

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

### Migrate PWASettingsPage Actions from v3 to v4

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade-design.md

Adapt the action definitions in PWASettingsPage.php for Filament v4. Actions previously defined in getActions() should now be defined in getHeaderActions() or other relevant action methods.

```php
// OLD (v3)
use Filament\Pages\Actions\Action;

protected function getActions(): array
{
    return [Action::make('back')...];
}

// NEW (v4)
use Filament\Actions\Action;

protected function getHeaderActions(): array
{
    return [Action::make('back')...];
}
```

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

### Test PWASettingsPage Form Schema

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Tests that the settings page form has the required fields and that file upload components have public visibility.

```php
<?php

use Filament\Forms\Components\FileUpload;
use TomatoPHP\FilamentPWA\Filament\Pages\PWASettingsPage;

test('settings page has form with required fields', function () {
    $page = new PWASettingsPage();

    $form = $page->form(
        \Filament\Forms\Form::make()->model(\TomatoPHP\FilamentPWA\Settings\PWASettings::class)
    );

    $schema = $form->getComponents();

    expect($schema)->not->toBeEmpty();
});

test('file upload fields have public visibility', function () {
    $page = new PWASettingsPage();

    $form = $page->form(
        \Filament\Forms\Form::make()->model(\TomatoPHP\FilamentPWA\Settings\PWASettings::class)
    );

    $fileUploads = collect($form->getFlatComponents())
        ->filter(fn ($component) => $component instanceof FileUpload);

    expect($fileUploads)->not->toBeEmpty();

    $fileUploads->each(function ($upload) {
        expect($upload->getVisibility())->toBe('public');
    });
});

```

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

### Update Imports in PWASettingsPage.php

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Replaces old imports with new ones and removes a deprecated import for Filament v4 compatibility.

```php
use Filament\Actions\Action;
use Filament\Forms\Components\ColorPicker;
use Filament\Forms\Components\Section;
use Filament\Forms\Form;
use Filament\Notifications\Notification;

```

```php
// DELETE: use Filament\Pages\Actions\Action;

```

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

### Push to Fork

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Push the feature branch containing the upgrade changes to your fork of the repository.

```bash
git push fork feature/filament-v4-upgrade
```

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

### Publish Filament PWA Languages

Source: https://github.com/tomatophp/filament-pwa/blob/master/README.md

Publish the language files for the Filament PWA package.

```bash
php artisan vendor:publish --tag="filament-pwa-lang"
```

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

### Upgrade Command

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Run this command to upgrade the package to version 2.0, which includes Filament v4 compatibility, and clear the optimization cache.

```bash
composer require tomatophp/filament-pwa:^2.0
php artisan optimize:clear
```

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

### PHPUnit Configuration

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Configure PHPUnit for testing, including test suites, source inclusion, and environment variables for database and application environment.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
    bootstrap="vendor/autoload.php"
    colors="true"
    processIsolation="false"
    stopOnFailure="false"
    cacheDirectory=".phpunit.cache"
>
    <testsuites>
        <testsuite name="Unit">
            <directory>tests/Unit</directory>
        </testsuite>
        <testsuite name="Feature">
            <directory>tests/Feature</directory>
        </testsuite>
    </testsuites>
    <source>
        <include>
            <directory>src</directory>
        </include>
    </source>
    <php>
        <env name="APP_ENV" value="testing"/>
        <env name="DB_CONNECTION" value="sqlite"/>
        <env name="DB_DATABASE" value=":memory:"/>
    </php>
</phpunit>
```

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

### Testbench YAML Configuration

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Configure Testbench for package development, specifying service providers and workbench settings.

```yaml
providers:
  - TomatoPHP\FilamentPWA\FilamentPwaServiceProvider

workbench:
  start: '/'
  install: true
```

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

### Republish Filament PWA Views

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/UPGRADE.md

If you have customized views, use this command to republish the Filament PWA assets. The --force flag overwrites existing files.

```bash
php artisan vendor:publish --tag="filament-pwa-views" --force
```

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

### Filament PWA Settings Page API Changes (Before v2.x)

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/UPGRADE.md

Illustrates the v1.x method signatures for customizing the PWA Settings Page schema and actions.

```php
protected function getFormSchema(): array
{
    return [/* fields */];
}

protected function getActions(): array
{
    return [Action::make('custom')];
}
```

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

### Add Fork as Remote

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Adds your forked repository as a remote named 'fork' to your local clone. Fetch updates from the fork before proceeding.

```bash
cd /Users/marindelija/Documents/Development/filament-pwa-upgrade/filament-pwa-upgrade
git remote add fork git@github.com:YOUR_USERNAME/filament-pwa.git
git fetch fork
```

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

### PWA Settings Form Schema - Basic Configuration

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Defines form fields for basic PWA settings such as status bar, theme color, display mode, and orientation. Use this schema to configure core PWA appearance and behavior.

```php
->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_status_bar")' : null),
                    ColorPicker::make('pwa_theme_color')
                        ->default('#000000')
                        ->label(trans('filament-pwa::messages.form.pwa_theme_color'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_theme_color")' : null),
                    TextInput::make('pwa_display')
                        ->label(trans('filament-pwa::messages.form.pwa_display'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_display")' : null),
                    TextInput::make('pwa_orientation')
                        ->label(trans('filament-pwa::messages.form.pwa_orientation'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_orientation")' : null)
```

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

### Commit PWASettingsPage Action Changes

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Commit the changes made to the PWASettingsPage actions migration.

```bash
git add src/Filament/Pages/PWASettingsPage.php tests/Feature/PWASettingsPageTest.php
git commit -m "feat: migrate PWASettingsPage actions to Filament v4"
```

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

### Add Pest Functions to Autoload-Dev in composer.json

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Configures autoload-dev to include Pest's functions.php, making Pest helper functions available in tests.

```json
"autoload-dev": {
    "psr-4": {
        "Tests\": "tests/"
    },
    "files": [
        "vendor/pestphp/pest/src/Functions.php"
    ]
}
```

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

### Update README Requirements

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Update the requirements section in README.md to reflect the new minimum versions for PHP, Laravel, and Filament.

```markdown
get a PWA feature on your FilamentPHP app with settings from panel

## Requirements

- PHP 8.2+
- Laravel 11.28+
- Filament v4.0+

## Installation
```

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

### ManifestService Unit Tests

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Write failing unit tests for the ManifestService to verify JSON structure, icon inclusion, and fallback values.

```php
<?php

use TomatoPHP\FilamentPWA\Services\ManifestService;

test('manifest service generates valid JSON structure', function () {
    $manifest = ManifestService::generate();

    expect($manifest)->toBeArray()
        ->and($manifest)->toHaveKeys(['name', 'short_name', 'start_url', 'display', 'theme_color', 'background_color', 'icons']);
});

test('manifest includes all icon sizes', function () {
    $manifest = ManifestService::generate();

    $iconSizes = collect($manifest['icons'])->pluck('sizes')->toArray();

    expect($iconSizes)->toContain('72x72', '96x96', '128x128', '144x144', '152x152', '192x192', '384x384', '512x512');
});

test('manifest uses fallback values when settings are empty', function () {
    $manifest = ManifestService::generate();

    expect($manifest['name'])->not->toBeEmpty()
        ->and($manifest['short_name'])->not->toBeEmpty()
        ->and($manifest['start_url'])->not->toBeEmpty();
});

```

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

### Migrate Form Schema to Filament v4

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Update the form schema definition in PWASettingsPage.php to be compatible with Filament v4. This involves adjusting how columns and hints are applied.

```php
->label(trans('filament-pwa::messages.form.pwa_shortcuts'))
->columnSpan(2)
->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_shortcuts")' : null),
```

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

### Configure PWA Splash Screen Upload Fields

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Defines FileUpload components for various PWA splash screen resolutions. Use this to allow users to upload appropriately sized splash screen images for different devices.

```php
FileUpload::make('pwa_splash_640x1136')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_640x1136'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_640x1136")' : null),
                    FileUpload::make('pwa_splash_750x1334')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_750x1334'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_750x1334")' : null),
                    FileUpload::make('pwa_splash_828x1792')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_828x1792'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_828x1792")' : null),
                    FileUpload::make('pwa_splash_1125x2436')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_1125x2436'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_1125x2436")' : null),
                    FileUpload::make('pwa_splash_1242x2208')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_1242x2208'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_1242x2208")' : null),
                    FileUpload::make('pwa_splash_1242x2688')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_1242x2688'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_1242x2688")' : null),
                    FileUpload::make('pwa_splash_1536x2048')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_1536x2048'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_1536x2048")' : null),
                    FileUpload::make('pwa_splash_1668x2224')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_1668x2224'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_1668x2224")' : null),
                    FileUpload::make('pwa_splash_1668x2388')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_1668x2388'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_1668x2388")' : null),
                    FileUpload::make('pwa_splash_2048x2732')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_2048x2732'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_splash_2048x2732")' : null)
```

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

### Filament PWA Settings Page API Changes (After v2.x)

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/UPGRADE.md

Shows the v2.x method signatures for customizing the PWA Settings Page schema and header actions. Note the use of the `Form` schema and `getHeaderActions` method.

```php
use Filament\Forms\Form;

public function form(Schema $schema): Schema
{
    return $form->schema([/* fields */]);
}

protected function getHeaderActions(): array
{
    return [Action::make('custom')];
}
```

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

### Register Filament PWA Plugin

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Tests the registration of the FilamentPWA plugin on a panel and verifies that the PWA settings page is added to the panel's pages.

```php
<?php

use Filament\Panel;
use TomatoPHP\FilamentPWA\FilamentPWAPlugin;

test('plugin can be registered on panel', function () {
    $panel = Panel::make()->id('admin');

    $plugin = FilamentPWAPlugin::make();

    expect($plugin->getId())->toBe('filament-pwa');

    $plugin->register($panel);

    expect($panel->getPages())->toContain(\TomatoPHP\FilamentPWA\Filament\Pages\PWASettingsPage::class);
});

test('plugin can disable PWA settings', function () {
    $panel = Panel::make()->id('admin');

    $plugin = FilamentPWAPlugin::make()
        ->allowPWASettings(false);

    $plugin->register($panel);

    expect($panel->getPages())->not->toContain(\TomatoPHP\FilamentPWA\Filament\Pages\PWASettingsPage::class);
});

```

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

### Pest Test Suite Structure

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade-design.md

Defines the directory structure for the Pest test suite, organizing unit and feature tests for the PWA plugin.

```bash
tests/
├── Pest.php
├── TestCase.php
├── Feature/
│   ├── PWAPluginTest.php
│   ├── PWASettingsPageTest.php
│   └── PWAControllerTest.php
└── Unit/
    └── ManifestServiceTest.php
```

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

### Migrate PWASettingsPage Form Schema from v3 to v4

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade-design.md

Update the form schema definition in PWASettingsPage.php to align with Filament v4's new schema API. This involves changing the method signature and return type.

```php
// OLD (v3)
protected function getFormSchema(): array
{
    return [/* fields */];
}

// NEW (v4)
public function form(Schema $schema): Schema
{
    return $form->schema([/* fields */]);
}
```

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

### Clear Application Caches

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/UPGRADE.md

Execute this Artisan command to clear various application caches after updating dependencies.

```bash
php artisan optimize:clear
```

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

### Create Feature Branch

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Creates a new Git branch named 'feature/filament-v4-upgrade' to isolate the upgrade work.

```bash
git checkout -b feature/filament-v4-upgrade
```

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

### Commit Failing Test for Plugin Registration

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Stages and commits the failing test file for plugin registration.

```bash
git add tests/Feature/PWAPluginTest.php
git commit -m "test: add failing test for plugin registration"

```

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

### Validate Composer.json

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Verify that the composer.json file is valid and contains no errors.

```bash
composer validate
```

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

### Commit ManifestService Unit Tests

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Commit the newly created unit tests for the ManifestService.

```bash
git add tests/Unit/ManifestServiceTest.php
git commit -m "test: add unit tests for ManifestService"
```

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

### Update Composer Dependencies

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/UPGRADE.md

Run this command to update your project's dependencies based on the composer.json changes.

```bash
composer update
```

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

### PWAController Feature Tests

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Write feature tests for the PWAController to ensure the manifest and service worker endpoints return the correct responses.

```php
<?php

test('manifest endpoint returns valid JSON', function () {
    $response = $this->get('/manifest.json');

    $response->assertStatus(200)
        ->assertHeader('Content-Type', 'application/json')
        ->assertJsonStructure([
            'name',
            'short_name',
            'start_url',
            'display',
            'theme_color',
            'background_color',
            'icons',
        ]);
});

test('service worker endpoint returns JavaScript', function () {
    $response = $this->get('/serviceworker.js');

    $response->assertStatus(200)
        ->assertHeader('Content-Type', 'application/javascript');
});

```

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

### Register Filament PWA Plugin

Source: https://github.com/tomatophp/filament-pwa/blob/master/README.md

Register the Filament PWA plugin in your Filament AdminPanelProvider.

```php
->plugin("TomatoPHP\FilamentPWA\FilamentPWAPlugin::make()")
```

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

### Replace getFormSchema with form Method in PWASettingsPage

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Replaces the deprecated `getFormSchema` method with the new `form` method for defining the form schema in Filament v4.

```php
public function form(Schema $schema): Schema
{
    return $form->schema([
        Grid::make(['default' => 2])->schema([
            Section::make(trans('filament-pwa::messages.sections.general'))
                ->collapsible()
                ->schema([
                    TextInput::make('pwa_app_name')
                        ->label(trans('filament-pwa::messages.form.pwa_app_name'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_app_name")' : null),
                    TextInput::make('pwa_short_name')
                        ->label(trans('filament-pwa::messages.form.pwa_short_name'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_short_name")' : null),
                    TextInput::make('pwa_start_url')
                        ->label(trans('filament-pwa::messages.form.pwa_start_url'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_start_url")' : null),
                ]),
            Section::make(trans('filament-pwa::messages.sections.style'))
                ->collapsible()
                ->collapsed()
                ->schema([
                    ColorPicker::make('pwa_background_color')
                        ->default('#ffffff')
                        ->label(trans('filament-pwa::messages.form.pwa_background_color'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_background_color")' : null),
                    ColorPicker::make('pwa_status_bar')
                        ->default('#000000')
                        ->label(trans('filament-pwa::messages.form.pwa_status_bar'))

```

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

### Laravel Test Case Configuration

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Extend Orchestra's TestCase for Laravel applications, enabling database refresh and service provider registration for FilamentPWA.

```php
<?php

namespace Tests;

use Illuminate\Foundation\Testing\RefreshDatabase;
use Orchestra\Testbench\TestCase as Orchestra;
use TomatoPHP\FilamentPWA\FilamentPwaServiceProvider;

class TestCase extends Orchestra
{
    use RefreshDatabase;

    protected function getPackageProviders($app): array
    {
        return [
            FilamentPwaServiceProvider::class,
        ];
    }

    protected function getEnvironmentSetUp($app): void
    {
        config()->set('database.default', 'testing');
        config()->set('filesystems.default', 'local');
    }
}
```

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

### Update composer.json for Filament PWA v2.x

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/UPGRADE.md

Specify the required PHP, Filament, and Filament PWA versions in your composer.json file.

```json
{
    "require": {
        "php": "^8.2",
        "filament/filament": "^4.0",
        "tomatophp/filament-pwa": "^2.0"
    }
}
```

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

### Git Worktree Command

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade-design.md

Command to create a separate git worktree for isolating the Filament v4 upgrade work.

```bash
git worktree add ../filament-v4-upgrade feature/filament-v4-upgrade
```

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

### Add Pest 4 Dev Dependencies and Scripts to composer.json

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Adds Pest 4 testing dependencies and defines a 'test' script for running Pest tests in composer.json.

```json
"require-dev": {
    "orchestra/testbench": "^10.0",
    "pestphp/pest": "^4.0",
    "pestphp/pest-plugin-laravel": "^4.0",
    "pestphp/pest-plugin-livewire": "^4.0"
},
"scripts": {
    "test": "vendor/bin/pest"
}
```

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

### Commit Form Schema Changes

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Commit the changes made to the form schema migration.

```bash
git add src/Filament/Pages/PWASettingsPage.php tests/Feature/PWASettingsPageTest.php
git commit -m "feat: migrate PWASettingsPage form schema to Filament v4"
```

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

### PWA Settings Form Schema - Icon Uploads

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Defines form fields for uploading various PWA icon sizes (72x72 to 512x512). Ensure all icons are in PNG format. Use this section to manage app icon assets.

```php
FileUpload::make('pwa_icons_72x72')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_icons_72x72'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_icons_72x72")' : null),
                    FileUpload::make('pwa_icons_96x96')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_icons_96x96'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_icons_96x96")' : null),
                    FileUpload::make('pwa_icons_128x128')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_icons_128x128'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_icons_128x128")' : null),
                    FileUpload::make('pwa_icons_144x144')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_icons_144x144'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_icons_144x144")' : null),
                    FileUpload::make('pwa_icons_152x152')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_icons_152x152'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_icons_152x152")' : null),
                    FileUpload::make('pwa_icons_192x192')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_icons_192x192'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_icons_192x192")' : null),
                    FileUpload::make('pwa_icons_384x384')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_icons_384x384'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_icons_384x384")' : null),
                    FileUpload::make('pwa_icons_512x512')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_icons_512x512'))
                        ->columnSpan(2)
                        ->hint(config('filament-settings-hub.show_hint') ? 'setting("pwa_icons_512x512")' : null)
```

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

### PWA Settings Form Schema - Splash Screen Upload

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Defines the form field for uploading the PWA splash screen image. Ensure the image is in PNG format. This is used for the initial loading experience.

```php
FileUpload::make('pwa_splash_640x1136')
                        ->acceptedFileTypes(['image/png'])
                        ->visibility('public')
                        ->label(trans('filament-pwa::messages.form.pwa_splash_640x1136'))
```

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

### Commit composer.json Changes

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Stages and commits the modified composer.json file with a descriptive message indicating the dependency updates.

```bash
git add composer.json
git commit -m "chore: update dependencies for Filament v4 and add Pest 4"
```

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

### Commit PWAController Feature Tests

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Commit the newly created feature tests for the PWAController.

```bash
git add tests/Feature/PWAControllerTest.php
git commit -m "test: add tests for PWA controller endpoints"
```

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

### PR Title for Filament v4 Upgrade

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade-design.md

Suggested title for the Pull Request, indicating a breaking change and the addition of a comprehensive test suite.

```markdown
[Breaking] Add Filament v4 support with comprehensive tests
```

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

### Update Filament Dependencies in composer.json

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Updates the core Filament packages and related plugins to version '^4.0' in composer.json.

```json
"filament/filament": "^4.0",
"filament/notifications": "^4.0",
"filament/spatie-laravel-settings-plugin": "^4.0"
```

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

### Set Public Visibility for FileUpload Components in v4

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade-design.md

Explicitly set the visibility to 'public' for all FileUpload components in Filament v4. This is required for assets like PWA icons and splash screens that need to be publicly accessible.

```php
// Apply to ALL icon and splash screen uploads
FileUpload::make('pwa_icons_72x72')
    ->acceptedFileTypes(['image/png'])
    ->visibility('public')  // NEW - required for v4
    ->label(...)
```

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

### Use Filament PWA Directive in Blade

Source: https://github.com/tomatophp/filament-pwa/blob/master/README.md

Include the @filamentPWA directive in your Blade files to enable PWA on non-FilamentPHP pages, typically placed before the closing </head> tag.

```html
@filamentPWA
```

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

### Update PHP Requirement in composer.json

Source: https://github.com/tomatophp/filament-pwa/blob/master/filament-pwa-upgrade/docs/plans/2025-11-20-filament-v4-upgrade.md

Modifies the PHP version requirement in composer.json to '^8.2' for compatibility with newer packages.

```json
"php": "^8.2"
```
Tokens:
Raw