### Install with Composer

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Install the package via Composer.

```bash
composer require jeffersongoncalves/laravel-metrics-matomo
```

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

### Install and configure laravel-metrics-matomo

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Install the package, publish the settings migrations, and run migrations. Requires PHP ^8.2 and Laravel ^11.0|^12.0.

```bash
composer require jeffersongoncalves/laravel-metrics-matomo
php artisan vendor:publish --tag=metrics-matomo-settings-migrations
php artisan migrate
```

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

### Get Live Visitors

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Get real-time visitor counters and details.

```php
// Counters for last 30 minutes
$counters = Matomo::liveCounters();
echo $counters->visits;          // 42
echo $counters->actions;         // 156
echo $counters->visitors;        // 38
echo $counters->visitsConverted; // 5

// Counters for last 60 minutes
$counters = Matomo::liveCounters(lastMinutes: 60);

// Last visitors details
$visitors = Matomo::liveVisitors(count: 10);
```

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

### Import Facade and Period Enum

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Import the Matomo facade and Period enum for usage examples.

```php
use JeffersonGoncalves\MetricsMatomo\Facades\Matomo;
use JeffersonGoncalves\MetricsMatomo\Enums\Period;
```

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

### Get Visits Summary

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Retrieve visit summaries for today, a month, or a specific date.

```php
// Today's summary
$summary = Matomo::visitsSummary();
echo $summary->nbVisits;         // 1234
echo $summary->nbUniqVisitors;   // 567
echo $summary->nbActions;        // 3456
echo $summary->bounceRate;       // 16.0
echo $summary->avgTimeOnSite;    // 120.5

// Monthly summary
$summary = Matomo::visitsSummary(Period::Month, 'today');

// Specific date
$summary = Matomo::visitsSummary(Period::Day, '2026-02-15');
```

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

### Get Goals

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Retrieve all goals or a specific goal by ID.

```php
// All goals summary
$goals = Matomo::goals(Period::Month, 'today');

// Specific goal
$goal = Matomo::goal(goalId: 1, period: Period::Month, date: 'today');
```

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

### Get Top Pages

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Fetch top page URLs, page titles, and entry/exit pages.

```php
// Top 10 page URLs
$pages = Matomo::pageUrls(limit: 10);
foreach ($pages as $page) {
    echo $page->label . ': ' . $page->nbVisits . ' visits';
}

// Page titles
$titles = Matomo::pageTitles(Period::Month, 'today', limit: 20);

// Entry and exit pages
$entry = Matomo::entryPages(limit: 10);
$exit = Matomo::exitPages(limit: 10);
```

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

### Get Device and Technology Data

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Retrieve device types, browsers, operating systems, and screen resolutions.

```php
// Device types (Desktop, Mobile, Tablet)
$devices = Matomo::deviceTypes();

// Browsers
$browsers = Matomo::browsers(limit: 10);

// Operating systems
$os = Matomo::osFamilies();

// Screen resolutions
$resolutions = Matomo::resolutions(limit: 10);
```

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

### Get Event Data

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Fetch event categories, actions, and names.

```php
// Event categories
$categories = Matomo::eventCategories(Period::Month, 'today');

// Event actions
$actions = Matomo::eventActions();

// Event names
$names = Matomo::eventNames(limit: 20);
```

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

### Get Geographic Data

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Fetch geographic data: countries, cities, regions, and continents.

```php
// Countries
$countries = Matomo::countries(Period::Month, 'today');
foreach ($countries as $country) {
    echo $country->label . ': ' . $country->nbVisits;
    echo ' (' . $country->extra['code'] . ')';  // Country code
}

// Cities
$cities = Matomo::cities(limit: 10);

// Regions
$regions = Matomo::regions();

// Continents
$continents = Matomo::continents();
```

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

### Get Referrer Data

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Retrieve referrer types, search engines, keywords, websites, social networks, and campaigns.

```php
// Referrer types (Direct, Search, Social, etc.)
$types = Matomo::referrerTypes();

// Search engines
$engines = Matomo::searchEngines(Period::Month, 'today');

// Keywords
$keywords = Matomo::keywords(limit: 20);

// Referring websites
$sites = Matomo::websites(limit: 10);

// Social networks
$socials = Matomo::socials();

// Campaigns
$campaigns = Matomo::campaigns(Period::Month, 'today');
```

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

### Run Migrations

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Run migrations to create the settings table.

```bash
php artisan migrate
```

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

### Run test suite with Pest, PHPStan, and Pint

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Use these commands to run the test suite, static analysis, and code style checks for the package.

```bash
vendor/bin/pest
vendor/bin/phpstan analyse
vendor/bin/pint
```

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

### Format code with composer format

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Formats the codebase according to the project's code style rules. Run this command to ensure consistent formatting.

```bash
composer format
```

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

### Adding a new summary method with call()

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Template for adding a new summary method that returns raw arrays. Use call() with the module name, method name, period, date, and site ID.

```php
public function newSummary(Period $period = Period::Day, string $date = 'today', ?int $siteId = null): array
{
    return $this->call('ModuleName', 'get', $period, $date, $siteId);
}
```

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

### Run static analysis with composer analyse

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Runs static analysis on the codebase. Use this command to detect potential issues without executing the code.

```bash
composer analyse
```

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

### Run tests with composer test

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Runs the test suite for the package. Use this command to execute all tests defined in the project.

```bash
composer test
```

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

### Mock Matomo facade with shouldReceive

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Use this snippet to mock the Matomo facade in tests, returning a VisitSummary object with sample data. This is useful for unit testing code that calls Matomo methods without making real HTTP requests.

```php
// Mock facade
Matomo::shouldReceive('visitsSummary')
    ->andReturn(VisitSummary::fromArray([
        'nb_visits' => 100, 'nb_uniq_visitors' => 80, 'nb_actions' => 250,
        'nb_users' => 0, 'bounce_count' => 30, 'bounce_rate' => '30%',
        'sum_visit_length' => 5000, 'max_actions' => 15,
        'nb_actions_per_visit' => 2.5, 'avg_time_on_site' => 50,
    ]));
```

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

### Configure Environment Variables

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Environment variables used to seed the settings after migration.

```env
MATOMO_API_TOKEN=your-token-auth
MATOMO_SITE_ID=1
MATOMO_BASE_URL=https://your-matomo-instance.com
MATOMO_TIMEZONE=UTC
```

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

### Update Settings Programmatically

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Update settings programmatically using the MatomoSettings class.

```php
use JeffersonGoncalves\MetricsMatomo\Settings\MatomoSettings;

$settings = app(MatomoSettings::class);
$settings->api_token = 'new-token';
$settings->site_id = 2;
$settings->base_url = 'https://matomo.example.com';
$settings->timezone = 'America/Sao_Paulo';
$settings->save();
```

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

### Custom Reports with Query Builder

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Build flexible reports using the fluent query builder with segments, date ranges, column selection, and extra parameters.

```php
use JeffersonGoncalves\MetricsMatomo\Enums\Period;

// Custom query with segment
$query = Matomo::query('VisitsSummary', 'get')
    ->period(Period::Month)
    ->date('2026-02-01')
    ->segment('referrerName==twitter.com')
    ->limit(50);

$result = Matomo::report($query);

// Date range query
$query = Matomo::query('Actions', 'getPageUrls')
    ->dateRange('2026-01-01', '2026-01-31')
    ->sortBy('nb_visits', 'desc')
    ->limit(20)
    ->flat();

$result = Matomo::report($query);

// Show/hide specific columns
$query = Matomo::query('VisitsSummary', 'get')
    ->period(Period::Day)
    ->date('today')
    ->showColumns('nb_visits', 'nb_uniq_visitors', 'bounce_rate');

$result = Matomo::report($query);

// With extra parameters
$query = Matomo::query('Goals', 'get')
    ->period(Period::Month)
    ->date('today')
    ->param('idGoal', 1);

$result = Matomo::report($query);
```

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

### Test query builder with ReportQuery

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Use this snippet to test the query builder. It creates a ReportQuery for 'Actions.getPageUrls', sets period to month, limit to 10, and flat to true, then verifies the generated query parameters.

```php
// Test query builder
$query = ReportQuery::make('Actions', 'getPageUrls')->period(Period::Month)->limit(10)->flat();
$params = $query->toQueryParams();
expect($params['method'])->toBe('Actions.getPageUrls');
expect($params['period'])->toBe('month');
expect($params['flat'])->toBe(1);
```

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

### Call Matomo API reports via Matomo facade

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Use the Matomo facade to call report methods. All report methods share the signature (Period $period, string $date, ?int $limit, ?int $siteId) and default siteId from MatomoSettings. VisitsSummary returns a VisitSummary DTO, most reports return list<ReportRow>, Goals return raw arrays, liveCounters returns a LiveCounter DTO, and liveVisitors returns a raw array.

```php
use JeffersonGoncalves\MetricsMatomo\Facades\Matomo;
use JeffersonGoncalves\MetricsMatomo\Enums\Period;

// VisitsSummary - returns VisitSummary DTO
$summary = Matomo::visitsSummary(Period::Day, 'today', siteId: 1);

// Actions - all return list<ReportRow>
$pages = Matomo::pageUrls(Period::Month, 'today', limit: 10);
$titles = Matomo::pageTitles();
$entries = Matomo::entryPages();
$exits = Matomo::exitPages();
$downloads = Matomo::downloads();
$outlinks = Matomo::outlinks();
$search = Matomo::siteSearchKeywords();

// Referrers - all return list<ReportRow>
$types = Matomo::referrerTypes();
$engines = Matomo::searchEngines();
$keywords = Matomo::keywords();
$websites = Matomo::websites();
$socials = Matomo::socials();
$campaigns = Matomo::campaigns();

// UserCountry - all return list<ReportRow>
$countries = Matomo::countries(Period::Month, 'today', limit: 20);
$cities = Matomo::cities();
$regions = Matomo::regions();
$continents = Matomo::continents();

// DevicesDetection / Resolution - all return list<ReportRow>
$devices = Matomo::deviceTypes();
$browsers = Matomo::browsers();
$os = Matomo::osFamilies();
$resolutions = Matomo::resolutions();

// Events - all return list<ReportRow>
$categories = Matomo::eventCategories();
$actions = Matomo::eventActions();
$names = Matomo::eventNames();

// Goals - return raw arrays
$goals = Matomo::goals(Period::Day, 'today');
$goal = Matomo::goal(1, Period::Day, 'today');

// Live
$counters = Matomo::liveCounters(lastMinutes: 30);  // LiveCounter DTO
$visitors = Matomo::liveVisitors(count: 10);         // raw array
```

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

### Adding a new report method with callReport()

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Template for adding a new report method that returns a list of ReportRow objects. Use callReport() with the module name, method name, period, date, limit, and site ID.

```php
public function newReport(Period $period = Period::Day, string $date = 'today', ?int $limit = null, ?int $siteId = null): array
{
    return $this->callReport('ModuleName', 'getMethodName', $period, $date, $limit, $siteId);
}
```

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

### Using DateTime Objects

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/README.md

Use Carbon DateTime objects for dynamic date parameters.

```php
use Carbon\Carbon;

$summary = Matomo::visitsSummary(
    period: Period::Day,
    date: Carbon::yesterday()->format('Y-m-d'),
);

$query = Matomo::query('Actions', 'getPageUrls')
    ->dateRange(Carbon::now()->subDays(30), Carbon::now());

$result = Matomo::report($query);
```

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

### Mock HTTP responses for Matomo API

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Use this snippet to fake HTTP responses for Matomo API requests in tests. It intercepts requests to 'matomo.example.com/index.php*' and returns a sample response array.

```php
// Mock HTTP
Http::fake([
    'matomo.example.com/index.php*' => Http::response([
        ['label' => '/home', 'nb_visits' => 100, 'nb_uniq_visitors' => 80, 'nb_actions' => 150],
    ]),
]);
```

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

### Period and Format enum values

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Available enum values for Period and Format in the package. Use these constants when configuring queries or responses.

```php
Period::Day, Period::Week, Period::Month, Period::Year, Period::Range
Format::Json, Format::Xml, Format::Csv, Format::Tsv, Format::Html, Format::Rss
```

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

### ReportQuery builder for Matomo Reporting API

Source: https://github.com/jeffersongoncalves/laravel-metrics-matomo/blob/main/resources/boost/skills/metrics-matomo-development/SKILL.md

Build a Matomo Reporting API query using the ReportQuery builder. Use dateRange() to set period=range with a from,to date; default idSite comes from settings; param() adds arbitrary extra parameters.

```php
$query = Matomo::query('Actions', 'getPageUrls')
    ->site(1)
    ->period(Period::Month)
    ->date('2024-01-01')
    ->dateRange('2024-01-01', '2024-01-31')  // sets period=range
    ->segment('browserCode==FF')
    ->limit(50)
    ->sortBy('nb_visits', 'desc')
    ->expanded()
    ->flat()
    ->label('/blog')
    ->showColumns('nb_visits', 'nb_uniq_visitors')
    ->hideColumns('bounce_rate')
    ->language('pt')
    ->param('idGoal', 1);  // arbitrary extra param
$results = Matomo::report($query);
```

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