### Install Filament Metrics Matomo via Composer

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/README.md

Install the package via Composer. Requires the 3.x branch for Filament v5.

```bash
composer require jeffersongoncalves/filament-metrics-matomo:"^3.0"
```

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

### Publish Plugin Configuration File

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/README.md

Optionally publish the configuration file for the plugin.

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

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

### Run Tests

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/README.md

Run the test suite.

```bash
composer test
```

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

### Run Code Quality Tools

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/README.md

Run static analysis with PHPStan and code formatting with Laravel Pint.

```bash
composer analyse   # PHPStan
composer format    # Laravel Pint
```

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

### Publish and Run Required Migrations

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/README.md

Publish and run the required migrations for the base package and the Matomo service provider.

```bash
php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"
php artisan vendor:publish --provider="JeffersonGoncalves\MetricsMatomo\MatomoServiceProvider" --tag="matomo-migrations"
php artisan migrate
```

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

### Enable Individual Widgets

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/README.md

Enable individual widgets by chaining their methods on the plugin instance.

```php
FilamentMetricsMatomoPlugin::make()
    ->settingsPage()
    ->liveCounter()
    ->visitsSummary()
    ->visitsChart()
    ->topPages()
    ->referrers()
    ->deviceTypes()
    ->browsers()
    ->countries()
```

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

### Plugin Configuration File

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/README.md

Configuration file for the plugin. Adjust default period, cache TTL, live counter polling, and table row limits.

```php
// config/filament-metrics-matomo.php

return [
    'default_period' => 'day',          // day, week, month, year
    'cache_ttl' => 300,                 // seconds (0 to disable)
    'cache_store' => null,              // null = default store
    'live_counter_poll_interval' => 30, // seconds
    'live_counter_last_minutes' => 30,  // minutes
    'table_row_limit' => 10,           // rows in table widgets
    'navigation' => [
        'group' => 'Analytics',
        'sort' => null,
    ],
];
```

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

### Test Connection Action

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/resources/boost/skills/filament-metrics-matomo-development/SKILL.md

Defines a header action that tests the Matomo API connection by creating a MatomoClient and Matomo instance, then calling visitsSummary().

```php
Action::make('test_connection')
    ->label(__('filament-metrics-matomo::pages.settings.actions.test_connection'))
    ->icon(Heroicon::OutlinedSignal)
    ->action(function (): void {
        $settings = app(MatomoSettings::class);
        $client = new MatomoClient(
            token: $settings->api_token,
            baseUrl: $settings->base_url,
        );
        $matomo = new Matomo($client);
        $matomo->visitsSummary(); // Tests the connection
    });
```

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

### Register Plugin in Filament Panel Provider

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/README.md

Register the plugin in your Filament Panel Provider to enable the settings page and all widgets.

```php
use JeffersonGoncalves\FilamentMetricsMatomo\FilamentMetricsMatomoPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentMetricsMatomoPlugin::make()
                ->settingsPage()
                ->allWidgets(),
        ]);
}
```

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

### Disable Specific Widgets

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/README.md

Enable all widgets and then disable specific ones by passing false to their methods.

```php
FilamentMetricsMatomoPlugin::make()
    ->settingsPage()
    ->allWidgets()
    ->countries(false)
    ->browsers(false)
```

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

### Check enabled features with accessor methods

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/resources/boost/skills/filament-metrics-matomo-development/SKILL.md

Accessor methods to check which features are enabled. Each returns a boolean.

```php
$plugin->hasSettingsPage();  // bool
$plugin->hasLiveCounter();   // bool
$plugin->hasVisitsSummary(); // bool
$plugin->hasVisitsChart();   // bool
$plugin->hasTopPages();      // bool
$plugin->hasReferrers();     // bool
$plugin->hasDeviceTypes();   // bool
$plugin->hasBrowsers();      // bool
$plugin->hasCountries();     // bool
```

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

### Form Fields for Connection Section

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/resources/boost/skills/filament-metrics-matomo-development/SKILL.md

Defines the form fields for the Matomo connection settings: base_url, api_token, site_id, and timezone. Each field includes validation rules as noted in comments.

```php
TextInput::make('base_url')   // Matomo instance URL (required, URL validation)
TextInput::make('api_token')  // Matomo API token (password, revealable, required)
TextInput::make('site_id')    // Matomo Site ID (numeric, min: 1, required)
Select::make('timezone')      // Timezone selector (searchable, required)
```

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

### Cache Clearing on Save

Source: https://github.com/jeffersongoncalves/filament-metrics-matomo/blob/3.x/resources/boost/skills/filament-metrics-matomo-development/SKILL.md

Clears cached Matomo data after saving settings to ensure fresh data is displayed.

```php
protected function afterSave(): void
{
    $cache->forget('filament-metrics-matomo:live-counters');
    $cache->forget('filament-metrics-matomo:visits-summary-day');
    $cache->forget('filament-metrics-matomo:visits-summary-week');
    $cache->forget('filament-metrics-matomo:visits-summary-month');
    $cache->forget('filament-metrics-matomo:visits-summary-year');
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.