Laravel Umami

https://github.com/jeffersongoncalves/laravel-umami
Admin
Laravel Umami is a package that integrates Umami Analytics into Laravel Blade templates with...
Tokens:3,539
Snippets:32
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install laravel-umami package

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/resources/boost/skills/umami-development/SKILL.md

Commands to install the package via Composer, publish the settings migrations, and run the database migrations.

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

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

### Install Laravel Umami via Composer

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/README.md

Install the package via Composer. Requires PHP 8.2+ and Laravel 11+.

```bash
composer require jeffersongoncalves/laravel-umami
```

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

### Pest Tests for Umami Script Rendering

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/resources/boost/skills/umami-development/SKILL.md

Example Pest tests verifying the tracking script renders correctly based on settings, including optional attributes and default values.

```php
use JeffersonGoncalves\Umami\Settings\UmamiSettings;

it('renders the tracking script when website_id is set', function () {
    $settings = app(UmamiSettings::class);
    $settings->website_id = 'test-website-id';
    $settings->save();

    $view = $this->blade('@include("umami::script")');
    $view->assertSee('data-website-id="test-website-id"');
    $view->assertSee('src="https://cloud.umami.is/script.js"');
});

it('does not render the script when website_id is null', function () {
    $settings = app(UmamiSettings::class);
    $settings->website_id = null;
    $settings->save();

    $view = $this->blade('@include("umami::script")');
    $view->assertDontSee('<script');
});

it('renders optional data attributes only when set', function () {
    $settings = app(UmamiSettings::class);
    $settings->website_id = 'test-id';
    $settings->host_url = 'https://collect.example.com';
    $settings->domains = 'example.com';
    $settings->tag = 'test-tag';
    $settings->save();

    $view = $this->blade('@include("umami::script")');
    $view->assertSee('data-host-url="https://collect.example.com"');
    $view->assertSee('data-domains="example.com"');
    $view->assertSee('data-tag="test-tag"');
});

it('renders boolean attributes correctly', function () {
    $settings = app(UmamiSettings::class);
    $settings->website_id = 'test-id';
    $settings->auto_track = false;
    $settings->exclude_search = true;
    $settings->exclude_hash = true;
    $settings->save();

    $view = $this->blade('@include("umami::script")');
    $view->assertSee('data-auto-track="false"');
    $view->assertSee('data-exclude-search="true"');
    $view->assertSee('data-exclude-hash="true"');
});

it('has the correct default values', function () {
    $settings = app(UmamiSettings::class);
    expect($settings->website_id)->toBeNull();
    expect($settings->host_analytics)->toBe('https://cloud.umami.is');
    expect($settings->auto_track)->toBeTrue();
    expect($settings->exclude_search)->toBeFalse();
    expect($settings->exclude_hash)->toBeFalse();
});

it('belongs to the umami group', function () {
    expect(UmamiSettings::group())->toBe('umami');
});
```

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

### Disable Auto-Track for Manual Tracking

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/resources/boost/skills/umami-development/SKILL.md

Set auto_track to false to disable automatic tracking, then use the Umami JavaScript API manually. The JavaScript call is shown as an inline example.

```php
$settings = app(UmamiSettings::class);
$settings->auto_track = false;
$settings->save();
```

```javascript
umami.track('button-click', { label: 'signup' });
```

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

### Publish and Run Umami Settings Migration

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/README.md

Publish and run the Umami settings migration. Run after publishing the spatie/laravel-settings migration.

```bash
php artisan vendor:publish --tag=umami-settings-migrations
php artisan migrate
```

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

### Run Tests with Composer

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/README.md

Run the package test suite.

```bash
composer test
```

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

### Configure Umami Settings via PHP

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/README.md

Configure Umami settings programmatically. Set the website ID and analytics host, then save. Settings are stored in the database.

```php
use JeffersonGoncalves\Umami\Settings\UmamiSettings;

$settings = app(UmamiSettings::class);
$settings->website_id = 'your-website-id';
$settings->host_analytics = 'https://your-umami-instance.com';
$settings->save();
```

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

### Publish spatie/laravel-settings Migration

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/README.md

Publish the spatie/laravel-settings migration to create the settings table if not already done.

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

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

### Composer Test Commands

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/resources/boost/skills/umami-development/SKILL.md

Run the package's test suite, coverage, static analysis, and formatting using Composer scripts.

```bash
composer test           # Run Pest tests
composer test-coverage  # Run with coverage
composer analyse        # PHPStan static analysis
composer format         # Laravel Pint formatting
```

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

### Define UmamiSettings class

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/resources/boost/skills/umami-development/SKILL.md

The UmamiSettings class extends Spatie's Settings and defines the configuration properties for the Umami integration.

```php
class UmamiSettings extends Settings
{
    public ?string $website_id;
    public string $host_analytics;
    public ?string $host_url;
    public bool $auto_track;
    public ?string $domains;
    public ?string $tag;
    public bool $exclude_search;
    public bool $exclude_hash;

    public static function group(): string { return 'umami'; }
}
```

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

### Read and Update Umami Settings

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/resources/boost/skills/umami-development/SKILL.md

Use the UmamiSettings class to set and save configuration values such as website ID, analytics host, and tracking options. All settings are stored in the database via spatie/laravel-settings.

```php
use JeffersonGoncalves\Umami\Settings\UmamiSettings;

$settings = app(UmamiSettings::class);
$settings->website_id = 'your-website-id';
$settings->host_analytics = 'https://umami.yourdomain.com';
$settings->host_url = 'https://collect.yourdomain.com';
$settings->auto_track = true;
$settings->domains = 'example.com,blog.example.com';
$settings->tag = 'production';
$settings->exclude_search = true;
$settings->exclude_hash = false;
$settings->save();
```

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

### Include Umami Script in Blade Layout

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/README.md

Add the Umami tracking script to your Blade layout, typically in the <head> section.

```blade
@include('umami::script')
```

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

### Render Umami tracking script

Source: https://github.com/jeffersongoncalves/laravel-umami/blob/master/resources/boost/skills/umami-development/SKILL.md

The Blade view implementation that renders the script tag with data attributes based on the UmamiSettings configuration.

```blade
@php($settings = app(\JeffersonGoncalves\Umami\Settings\UmamiSettings::class))

@if(!empty($settings->website_id))
    <script async defer data-website-id="{{ $settings->website_id }}"
            src="{{ $settings->host_analytics }}/script.js"
            @if($settings->host_url) data-host-url="{{ $settings->host_url }}" @endif
            @if($settings->domains) data-domains="{{ $settings->domains }}" @endif
            @if($settings->tag) data-tag="{{ $settings->tag }}" @endif
            data-auto-track="{{ $settings->auto_track ? 'true' : 'false' }}"
            data-exclude-search="{{ $settings->exclude_search ? 'true' : 'false' }}"
            data-exclude-hash="{{ $settings->exclude_hash ? 'true' : 'false' }}">
    </script>
@endif
```
Tokens:
Raw