Microsoft Clarity for Laravel

https://github.com/abr4xas/clarity-laravel
Admin
This package provides easy integration of Microsoft Clarity analytics into your Laravel application,...
Tokens:26,416
Snippets:182
Trust Score:8.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Usage example of ClarityCommand

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Example usage of the ClarityCommand class, including how to get arguments and how the emitter view uses them.

```php
use Abr4xas\ClarityLaravel\ClarityCommand;

// Render the command's script whenever you need the raw arguments
$command = ClarityCommand::tag('user_role', 'admin');
$arguments = $command->arguments(); // ['set', 'user_role', ['admin']]

// The emitter view (resources/views/command.blade.php) does exactly this:
// <script type="text/javascript">
//     window.clarity = window.clarity || function () { (window.clarity.q = window.clarity.q || []).push(arguments); };
//     window.clarity.apply(null, {{ \Illuminate\Support\Js::from($arguments) }});
// </script>

```

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

### ClarityCommand::consent usage examples

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Examples demonstrating how to generate consent arguments for both v2 (recommended) and v1 (deprecated) versions.

```php
use Abr4xas\ClarityLaravel\ClarityCommand;

// V2 granted → ['consentv2', ['ad_Storage' => 'granted', 'analytics_Storage' => 'granted']]
$args = ClarityCommand::consent(true)->arguments();

// V2 denied → ['consentv2', ['ad_Storage' => 'denied', 'analytics_Storage' => 'denied']]
$args = ClarityCommand::consent(false)->arguments();

// V1 boolean form → ['consent', true]
$args = ClarityCommand::consent($userConsented, 'v1')->arguments();
```

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

### HTML usage examples for <x-clarity::tag>

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

Three example usages of the tag component with different keys and values, including a dynamic value from auth()->user()->role.

```html
<x-clarity::tag key="plan" :values="['premium']" />
<x-clarity::tag key="features" :values="['chat', 'video', 'notifications']" />
<x-clarity::tag key="user_role" :values="[auth()->user()->role]" />
```

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

### ClarityCommand::identify usage examples

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Usage examples for ClarityCommand::identify. Shows how to pass a user object with email and name, a user without a name, and a null user. The resulting arguments array is shown in comments; missing properties or null user produce null slots without exceptions.

```php
use Abr4xas\ClarityLaravel\ClarityCommand;

$user = (object) ['email' => 'a@b.com', 'name' => 'Ana'];

// → ['identify', 'a@b.com', 's1', 'p1', 'Ana']
$args = ClarityCommand::identify($user, 's1', 'p1')->arguments();

// User without a name → ['identify', 'a@b.com', null, null, null]
$args = ClarityCommand::identify((object) ['email' => 'a@b.com'])->arguments();

// Null user → ['identify', null, null, null, null] (safe, no exception)
$args = ClarityCommand::identify(null)->arguments();
```

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

### HTML usage examples for <x-clarity::consent>

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

Two example usages of the consent component: one to grant consent (V2 recommended) and one to deny consent (V2).

```html
<!-- Grant consent (V2 - recommended) -->
<x-clarity::consent :granted="true" />

<!-- Deny consent (V2) -->
<x-clarity::consent :granted="false" />
```

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

### Custom ID Components Usage Example

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

Example usage of the custom user ID, custom session ID, and custom page ID components.

```html
<x-clarity::custom-user-id user_id="user-123" />
<x-clarity::custom-session-id session_id="session-456" />
<x-clarity::custom-page-id page_id="page-789" />
```

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

### Install package via Composer

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Use this command to add the clarity-laravel package to your project dependencies.

```bash
composer require abr4xas/clarity-laravel
```

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

### Full Clarity configuration in config/clarity.php

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-middleware.md

Provides the full-clarity configuration example with all available options, including enabling Clarity, the identification API, auto-tagging of environment and routes, and auto-identification of users. The flags are driven by environment variables with these defaults: enabled (CLARITY_ENABLED, true), enabled_identify_api (CLARITY_IDENTIFICATION_ENABLED, false), auto_tag_environment (CLARITY_AUTO_TAG_ENV, true), auto_tag_routes (CLARITY_AUTO_TAG_ROUTES, false), and auto_identify_users (CLARITY_AUTO_IDENTIFY, false). The comment '// ...' indicates additional configuration options not shown.

```php
// config/clarity.php
return [
    'enabled'             => env('CLARITY_ENABLED', true),
    'enabled_identify_api'=> env('CLARITY_IDENTIFICATION_ENABLED', false),
    'auto_tag_environment'=> env('CLARITY_AUTO_TAG_ENV', true),
    'auto_tag_routes'     => env('CLARITY_AUTO_TAG_ROUTES', false),
    'auto_identify_users' => env('CLARITY_AUTO_IDENTIFY', false),
    // ...
];
```

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

### ClarityCommand::tag() usage examples

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Shows how to use the tag() constructor with scalar values, explicit arrays, and empty values that are dropped and re-indexed.

```php
use Abr4xas\ClarityLaravel\ClarityCommand;

// Scalar value → ['set', 'plan', ['premium']]
$args = ClarityCommand::tag('plan', 'premium')->arguments();

// Explicit array → ['set', 'features', ['chat', 'video', 'notifications']]
$args = ClarityCommand::tag('features', ['chat', 'video', 'notifications'])->arguments();

// Empty values are dropped and the list re-indexed
// → ['set', 'flight', ['a', 'b']]
$args = ClarityCommand::tag('flight', ['a', '', 'b'])->arguments();
```

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

### Example usage of clarity_render

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Shows how clarity_render is used internally, equivalent to clarity_consent(true). Returns a rendered script or null when clarity.enabled is false.

```php
// Equivalent of clarity_consent(true):
$html = clarity_render('consent', ['granted' => true]);
// → rendered <script> or null when clarity.enabled is false
```

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

### Identify Component Usage Example

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

Example usage of the identify component inside an auth blade directive.

```html
@auth
    <x-clarity::identify :user="request()->user()"/>
@endauth
```

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

### clarity_consent usage examples

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Shows how to use clarity_consent to grant consent (default V2 object form), deny consent, and conditionally handle consent based on user preference.

```php
// Grant consent (V2 object form by default)
echo clarity_consent(true);

// Deny consent
echo clarity_consent(false);

// Conditional consent handler
if ($userConsented) {
    echo clarity_consent(true);
} else {
    echo clarity_consent(false);
}
```

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

### Middleware alias usage in bootstrap/app.php

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-laravel-service-provider.md

Example of appending the 'clarity' middleware alias to the web group in Laravel 11+ bootstrap/app.php.

```php
// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        'clarity', // alias registered by ClarityLaravelServiceProvider::boot()
    ]);
})
```

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

### Clarity custom session and page ID helpers

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

These PHP function declarations and usage example are part of the Clarity helper API. The functions set custom session and page IDs, requiring the identify API to be enabled. The example shows how to call them, with the environment variable CLARITY_IDENTIFICATION_ENABLED=true required.

```php
/**
 * Set a custom session ID for the current Clarity session.
 * Requires identify API to be enabled.
 *
 * @param  string  $sessionId  The custom session ID
 * @return string|null The rendered script tag or null
 */
function clarity_set_custom_session_id(string $sessionId): ?string
```

```php
/**
 * Set a custom page ID for the current Clarity session.
 * Requires identify API to be enabled.
 *
 * @param  string  $pageId  The custom page ID
 * @return string|null The rendered script tag or null
 */
function clarity_set_custom_page_id(string $pageId): ?string
```

```php
// Requires CLARITY_IDENTIFICATION_ENABLED=true in the environment
echo clarity_set_custom_user_id('user-123');
echo clarity_set_custom_session_id('session-456');
echo clarity_set_custom_page_id('page-789');
```

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

### ClarityCommand customSessionId usage example

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Demonstrates creating a command with a custom session ID, producing an arguments array with the session ID in the third position.

```PHP
use Abr4xas\ClarityLaravel\ClarityCommand;

// → ['identify', null, 'session-456', null, null]
$args = ClarityCommand::customSessionId('session-456')->arguments();
```

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

### Tag User Actions Dynamically

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Example of using clarity_tag in a controller to record specific user actions for analysis.

```php
// In a controller after user action
public function upgradePlan(Request $request)
{
    // ... upgrade logic ...

    // Tag the session for analysis
    clarity_tag('plan_upgrade', [
        'from' => $request->user()->plan,
        'to' => $request->input('new_plan'),
        'timestamp' => now()->toIso8601String(),
    ]);

    return redirect()->route('dashboard');
}
```

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

### clarity_identify

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Documentation for the clarity_identify helper function, including parameters, return value, and usage examples.

```APIDOC
## clarity_identify(object $user, ?string $customSessionId = null, ?string $customPageId = null): ?string

### Description
Identifies a user for the current Clarity session by rendering a script tag that calls `window.clarity("identify", email, sessionId, pageId, name)`. Returns `null` when Clarity is disabled or when the Identify API is not enabled.

### Method
Function

### Signature
`clarity_identify(object $user, ?string $customSessionId = null, ?string $customPageId = null): ?string`

### Parameters
- `$user` (object) - Required - User object exposing nullable `email` and `name` properties (e.g. the authenticated User model)
- `$customSessionId` (?string) - Optional - Custom session ID (default: `null`)
- `$customPageId` (?string) - Optional - Custom page ID (default: `null`)

### Return Value
`?string` - The rendered `<script>` tag for `window.clarity("identify", email, sessionId, pageId, name)`, or `null` when Clarity is disabled or when `config('clarity.enabled_identify_api', false)` is falsy.

### Example
```php
// Basic usage
echo clarity_identify(auth()->user());

// With custom session and page IDs
echo clarity_identify(
    user: auth()->user(),
    customSessionId: 'custom-session-123',
    customPageId: 'checkout-page'
);

// Handles null return when the Identify API is disabled
$script = clarity_identify($user);
if ($script === null) {
    // Identify API not enabled (CLARITY_IDENTIFICATION_ENABLED=false) — no-op
}
```
```

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

### Identify Component Compiled Output

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

Compiled JavaScript output from the identify component example.

```js
window.clarity("identify", "user@example.com", null, null, "Username")
```

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

### Handle Conditional Consent

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Example of using clarity_consent within a cookie consent handler to toggle tracking based on user preference.

```php
// In your cookie consent handler
if ($userConsented) {
    echo clarity_consent(true);
} else {
    echo clarity_consent(false);
}
```

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

### ClarityCommand customPageId usage example

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Shows how to set a custom page ID, resulting in an array where the page ID is the fourth element after 'identify'.

```PHP
use Abr4xas\ClarityLaravel\ClarityCommand;

// → ['identify', null, null, 'page-789', null]
$args = ClarityCommand::customPageId('page-789')->arguments();
```

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

### ClarityCommand customUserId usage example

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Creates a ClarityCommand with a custom user ID using the static method, resulting in an arguments array containing 'identify' and the user ID.

```PHP
use Abr4xas\ClarityLaravel\ClarityCommand;

// → ['identify', 'user-123', null, null, null]
$args = ClarityCommand::customUserId('user-123')->arguments();
```

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

### Use <x-clarity::script> in layout head

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

Example usage of the `<x-clarity::script>` component in a layout head. The `:enabled` prop is bound from a layout-level variable to control whether the tag is rendered.

```html
<!-- Should be placed in the head -->
<x-clarity::script :enabled="$enabled" />
```

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

### clarity_tag() usage examples

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Shows usage of clarity_tag() in a controller: rendering a single value, mixing strings and arrays, and guarding against null when Clarity is disabled.

```php
// In a controller
$html = clarity_tag('subscription', 'pro');
echo $html; // <script>…window.clarity("set","subscription",["pro"])…</script>

// Multiple values (strings and arrays may be mixed)
clarity_tag('permissions', 'read', 'write', 'admin');
clarity_tag('features', ['feature_a', 'feature_b']);

// Guard the null case when Clarity is disabled
if (($tag = clarity_tag('user_segment', auth()->user()->segment)) !== null) {
    echo $tag;
}

```

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

### boot method implementation

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-laravel-service-provider.md

Calls parent::boot() and registers the 'clarity' middleware alias if the router is bound.

```php
public function boot(): void
{
    parent::boot();

    // Register middleware alias for manual registration by the user
    if ($this->app->bound('router')) {
        $this->app['router']->aliasMiddleware('clarity', ClarityMiddleware::class);
    }
}
```

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

### configurePackage method implementation

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-laravel-service-provider.md

Implements the abstract configurePackage method to set the package name to 'clarity', enable config file publishing, and enable view publishing.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('clarity')
        ->hasConfigFile()
        ->hasViews();
}
```

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

### handle() method signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-middleware.md

The handle() method is the entry point for the middleware. It takes a Request and a Closure, and returns a Response. If the 'clarity.enabled' config is falsy, it passes the request through without sharing view data.

```php
/**
 * Handle an incoming request.
 *
 * @param  Closure(Request): (Response)  $next
 */
public function handle(Request $request, Closure $next): Response
```

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

### Configure Clarity Middleware

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Configure the middleware behavior in config/clarity.php.

```php
'auto_tag_environment' => env('CLARITY_AUTO_TAG_ENV', true),
'auto_tag_routes' => env('CLARITY_AUTO_TAG_ROUTES', false),
'auto_identify_users' => env('CLARITY_AUTO_IDENTIFY', false),
```

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

### Publish config and views commands

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-laravel-service-provider.md

Commands to publish the package's config file and Blade views using the 'clarity-config' and 'clarity-views' tags.

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

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

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

### Run tests with Composer

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Execute the project's test suite using the Composer package manager.

```bash
composer test
```

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

### Publish package views

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Use this command to publish the package's blade views if you need to customize the Clarity tracking code output.

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

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

### Publish clarity config

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/configuration.md

Publishes the package configuration file to config/clarity.php using the tag 'clarity-config'.

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

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

### Configuration file contents

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

The default configuration file allows you to set your Clarity ID, enable/disable the service, and configure identification and tagging features.

```php
<?php

return [
    'id' => env('CLARITY_ID', 'XXXXXX'),
    'enabled' => env('CLARITY_ENABLED', true),
    'enabled_identify_api' => env('CLARITY_IDENTIFICATION_ENABLED', false),
    'global_tags' => [],
    'consent_version' => env('CLARITY_CONSENT_VERSION', 'v2'),
    'consent_required' => env('CLARITY_CONSENT_REQUIRED', false),
    'auto_tag_environment' => env('CLARITY_AUTO_TAG_ENV', true),
    'auto_tag_routes' => env('CLARITY_AUTO_TAG_ROUTES', false),
    'auto_identify_users' => env('CLARITY_AUTO_IDENTIFY', false),
];
```

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

### Identify API Component and Output

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Use the identify component to implement the Identify API, which compiles into a window.clarity call.

```html
@auth
    <x-clarity::identify :user="request()->user()"/>
@endauth
```

```js
window.clarity("identify", "user@example.com", null, null, "Username")
```

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

### ClarityCommand::consent(bool $granted, string $version = 'v2'): self

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Static method that creates a ClarityCommand instance for consent tracking. Accepts a boolean grant state and an optional version string, returning a self instance whose arguments() method yields the appropriate consent payload.

```APIDOC
## ClarityCommand::consent(bool $granted, string $version = 'v2'): self

### Description
Static factory method that generates consent command arguments for Microsoft Clarity. It accepts a boolean indicating whether consent is granted and an optional version string, returning a self instance. The resulting arguments() method returns the consent payload in either the v2 object form or the deprecated v1 boolean form.

### Method
Static method (PHP)

### Signature
`public static function consent(bool $granted, string $version = 'v2'): self`

### Parameters
- **$granted** (bool) - Required - `true` grants consent, `false` denies it.
- **$version** (string) - Optional, default `'v2'` - `'v2'` (recommended) emits the `consentv2` object form; `'v1'` emits the deprecated boolean form. Any value other than the exact string `'v1'` falls through to the v2 form.

### Return Value
- **self** - For `'v1'`: `['consent', $granted]` (boolean form, deprecated). For any other version (including the default `'v2'`): `['consentv2', ['ad_Storage' => $state, 'analytics_Storage' => $state]]` where `$state` is the string `'granted'` or `'denied'`. A single grant maps both storage signals (`ad_Storage`, `analytics_Storage`) to the same state.

### Examples
```php
use Abr4xas\ClarityLaravel\ClarityCommand;

// V2 granted → ['consentv2', ['ad_Storage' => 'granted', 'analytics_Storage' => 'granted']]
$args = ClarityCommand::consent(true)->arguments();

// V2 denied → ['consentv2', ['ad_Storage' => 'denied', 'analytics_Storage' => 'denied']]
$args = ClarityCommand::consent(false)->arguments();

// V1 boolean form → ['consent', true]
$args = ClarityCommand::consent($userConsented, 'v1')->arguments();
```
```

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

### Define Global Tags

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Configure global tags in config/clarity.php to automatically apply them to all sessions.

```php
'global_tags' => [
    'environment' => [env('APP_ENV', 'production')],
    'version' => ['1.0.0'],
    'region' => ['us-east'],
],
```

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

### Configure Consent API

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Set the consent version and requirement status in your configuration file or .env.

```php
// In config/clarity.php or .env
'consent_version' => env('CLARITY_CONSENT_VERSION', 'v2'), // 'v1' or 'v2'
'consent_required' => env('CLARITY_CONSENT_REQUIRED', false),
```

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

### Middleware view sharing with auto tags and user

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-middleware.md

Shows the view data shared by the middleware when all three auto-tag flags are enabled. The tags include environment, route name, and route prefix, and the authenticated user is shared for auto-identification. This block is commented out and demonstrates the data structure. The route and prefix accesses are null-safe, silently producing no tags for un-named routes. Every tag is a one-element array of strings, matching the shape expected by ClarityCommand::tag(). The user is shared, but actual emission of the identify command is deferred to the script component and requires both auto_identify_users and enabled_identify_api to be true.

```php
// View::share('clarity_auto_tags', [
//     'environment' => [app()->environment()],
//     'route'       => [$request->route()?->getName()],
//     'route_prefix'=> [$request->route()?->getPrefix()],
// ]);
// View::share('clarity_auto_identify_user', $request->user());
```

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

### ClarityCommand::tag() static constructor

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Creates a command for a custom tag, shaping arguments as ['set', $key, $values]. Empty values are dropped and the list re-indexed. Throws TypeError on wrong argument types with strict_types=1.

```php
/**
 * Custom tag: `window.clarity("set", key, values)`.
 * Empty values are dropped and the list re-indexed.
 *
 * @param  string|array<int, mixed>  $values
 */
public static function tag(string $key, string|array $values): self
```

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

### arguments() method signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

The method signature and docblock for the arguments() method, showing its return type and purpose.

```php
/**
 * The argument list to spread into `window.clarity(...)`.
 *
 * @return array<int, mixed>
 */
public function arguments(): array

```

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

### Advanced Clarity configuration (config/clarity.php)

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/configuration.md

Advanced configuration for the Clarity Laravel package. Sets the Clarity ID from the CLARITY_ID environment variable, enables the identify API, auto-tagging for environment and routes, and auto-identification of users. Global tags include app_version and deployment, which are emitted by the <x-clarity::script /> component along with any auto tags shared by the middleware.

```php
// config/clarity.php
return [
    'id' => env('CLARITY_ID'),
    'enabled' => env('CLARITY_ENABLED', true),
    'enabled_identify_api' => true,
    'auto_tag_environment' => true,
    'auto_tag_routes' => true,
    'auto_identify_users' => true,
    'global_tags' => [
        'app_version' => [config('app.version')],
        'deployment' => [env('DEPLOYMENT_ID')],
    ],
];
```

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

### Manage Consent via Helper Function

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Use the clarity_consent helper to programmatically update consent status.

```php
// Grant consent
clarity_consent(true);

// Deny consent
clarity_consent(false);
```

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

### Register Middleware in Laravel 11+

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Manually register the ClarityMiddleware in bootstrap/app.php by adding it to the web middleware group.

```php
// bootstrap/app.php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(append: [
            \Abr4xas\ClarityLaravel\Middleware\ClarityMiddleware::class,
            // or use the alias:
            // 'clarity',
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();
```

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

### Apply Middleware to Route Group

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-middleware.md

Apply the 'clarity' middleware alias to a specific group of routes.

```php
Route::middleware('clarity')->group(function () {
    // Your routes
});
```

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

### ClarityCommand::tag(string $key, string|array $values): self

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Creates a new ClarityCommand for a custom tag, which will be dispatched as window.clarity('set', key, values). Empty values are filtered out and the list is re-indexed.

```APIDOC
## ClarityCommand::tag(string $key, string|array $values): self

### Description
Creates a new ClarityCommand for a custom tag, which will be dispatched as `window.clarity('set', key, values)`. Empty values are filtered out and the list is re-indexed.

### Method
Static named constructor

### Signature
`public static function tag(string $key, string|array $values): self`

### Parameters
- **$key** (string) - Required - The custom tag key used for session filtering in the Clarity dashboard.
- **$values** (string|array<int, mixed>) - Required - A single value or a list of values. Scalar input is wrapped into a one-element array. Empty values (empty strings, 0, empty arrays, null, false) are dropped and the list re-indexed.

### Return
- **self** - A new ClarityCommand instance with arguments `['set', $key, $values]`.

### Throws
None. With `declare(strict_types=1)`, a wrong argument type raises PHP's native `TypeError`.

### Examples
```php
use Abr4xas\ClarityLaravel\ClarityCommand;

// Scalar value → ['set', 'plan', ['premium']]
$args = ClarityCommand::tag('plan', 'premium')->arguments();

// Explicit array → ['set', 'features', ['chat', 'video', 'notifications']]
$args = ClarityCommand::tag('features', ['chat', 'video', 'notifications'])->arguments();

// Empty values are dropped and the list re-indexed
// → ['set', 'flight', ['a', 'b']]
$args = ClarityCommand::tag('flight', ['a', '', 'b'])->arguments();
```
```

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

### Set Custom IDs via Helpers

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Set custom user, session, or page IDs independently using dedicated helper functions.

```php
// Set custom user ID
clarity_set_custom_user_id('user-123');

// Set custom session ID
clarity_set_custom_session_id('session-456');

// Set custom page ID
clarity_set_custom_page_id('page-789');
```

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

### clarity_consent(bool $granted = true): ?string

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Sets consent for the current Clarity session. Returns the rendered script tag or null when Clarity is disabled.

```APIDOC
## clarity_consent(bool $granted = true): ?string

### Description
Sets consent for the current Clarity session. Returns the rendered script tag or null when Clarity is disabled.

### Method
Function

### Signature
`clarity_consent(bool $granted = true): ?string`

### Parameters
- **$granted** (bool) - Optional, default `true` - `true` grants consent, `false` denies it

### Return Value
- **?string** - The rendered `<script>` tag for the consent command, or `null` when Clarity is disabled. The emitted wire form depends on `config('clarity.consent_version', 'v2')`: `'v1'` produces `window.clarity("consent", bool)`; anything else produces `window.clarity("consentv2", {ad_Storage, analytics_Storage})`.

### Examples
```php
// Grant consent (V2 object form by default)
echo clarity_consent(true);

// Deny consent
echo clarity_consent(false);

// Conditional consent handler
if ($userConsented) {
    echo clarity_consent(true);
} else {
    echo clarity_consent(false);
}
```
```

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

### Register Middleware in Laravel 10 and below

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Manually register the ClarityMiddleware in app/Http/Kernel.php by adding it to the web middleware group.

```php
// app/Http/Kernel.php

protected $middlewareGroups = [
    'web' => [
        // ... other middleware
        \Abr4xas\ClarityLaravel\Middleware\ClarityMiddleware::class,
        // or use the alias:
        // 'clarity',
    ],
];
```

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

### Register Middleware in Laravel 11+

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-middleware.md

Register the middleware in the bootstrap/app.php file using the withMiddleware method.

```php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(append: [
            \Abr4xas\ClarityLaravel\Middleware\ClarityMiddleware::class,
            // or use the alias:
            // 'clarity',
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();
```

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

### clarity::command emitter partial (internal) - Blade

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

Use this partial to emit a single Clarity command. It ensures the buffering stub exists so calls made before the tag loads are queued natively by Clarity (clarity.q), then dispatches. Argument values are encoded with Illuminate\Support\Js::from(), which hex-escapes quotes to prevent breaking out of the script block.

```blade
{{-- Emits a single Clarity command. Ensures the buffering stub exists so calls
     made before the tag loads are queued natively by Clarity (clarity.q), then
     dispatches. $arguments is the list produced by ClarityCommand::arguments(). --}}
<script type="text/javascript">
    window.clarity = window.clarity || function () { (window.clarity.q = window.clarity.q || []).push(arguments); };
    window.clarity.apply(null, {{ \Illuminate\Support\Js::from($arguments) }});
</script>
```

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

### Basic usage of clarity_identify()

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Echoes the identify script tag for the authenticated user.

```php
// Basic usage
echo clarity_identify(auth()->user());
```

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

### clarity_render function definition

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Internal shared implementation for the clarity_* helpers. It checks the clarity.enabled config and optionally the enabled_identify_api config, then renders a component view. Returns null if disabled.

```php
/**
 * Guard on Clarity being enabled, then render a Clarity component view.
 *
 * Centralizes the `clarity.enabled` (and optional identify-API) checks so
 * every helper shares a single source of truth for when a script is emitted.
 *
 * @internal Shared implementation for the clarity_* helpers.
 *
 * @param  array<string, mixed>  $data
 */
function clarity_render(string $component, array $data, bool $requiresIdentifyApi = false): ?string
```

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

### ClarityCommand::identify method signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Static method signature for the ClarityCommand::identify method. It accepts an optional user object and optional session and page IDs, returning self. The user's email and name are extracted via data_get, so nested attributes are supported.

```php
/**
 * Identify: `window.clarity("identify", custom-id, session-id, page-id, friendly-name)`.
 * The user's `email` maps to custom-id and `name` to friendly-name.
 */
public static function identify(?object $user, ?string $sessionId = null, ?string $pageId = null): self
```

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

### ClarityCommand::consent method definition

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

The method signature for setting user consent, with a default version of 'v2'.

```php
/**
 * Consent. Version 'v2' (recommended) emits the `consentv2` object form;
 * 'v1' emits the deprecated boolean form. A single grant maps both storage
 * signals to the same state, per Microsoft's documented behavior.
 */
public static function consent(bool $granted, string $version = 'v2'): self
```

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

### Render Microsoft Clarity script with tags and identify command

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

Blade component that renders the Microsoft Clarity loader and optional commands. It respects the `enabled` prop and `config('clarity.enabled')`, and outputs `clarity::command` partials for global tags, auto tags, and an optional identify command.

```blade
@props([
    'enabled' => true,
])

@if ($enabled && config('clarity.enabled'))
    <script type="text/javascript">
        (function(c,l,a,r,i,t,y){
            c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
            t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
            y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
        })(window, document, "clarity", "script", "{{ config('clarity.id') }}");
    </script>

    @php
        $commands = [];

        foreach (config('clarity.global_tags', []) as $key => $values) {
            $commands[] = \Abr4xas\ClarityLaravel\ClarityCommand::tag($key, $values)->arguments();
        }

        foreach (($clarity_auto_tags ?? []) as $key => $values) {
            $commands[] = \Abr4xas\ClarityLaravel\ClarityCommand::tag($key, $values)->arguments();
        }

        $autoIdentifyUser = $clarity_auto_identify_user ?? null;
        if ($autoIdentifyUser && config('clarity.auto_identify_users', false) && config('clarity.enabled_identify_api', false)) {
            $commands[] = \Abr4xas\ClarityLaravel\ClarityCommand::identify($autoIdentifyUser)->arguments();
        }
    @endphp

    @foreach ($commands as $arguments)
        @include('clarity::command', ['arguments' => $arguments])
    @endforeach
@endif
```

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

### ClarityCommand::identify

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Static method to identify a user for Microsoft Clarity, mapping email to custom ID and name to friendly name.

```APIDOC
## ClarityCommand::identify(?object $user, ?string $sessionId = null, ?string $pageId = null): self

### Description
Identifies a user to Microsoft Clarity by mapping the user's `email` to the custom ID and `name` to the friendly name. This method is a static factory that returns a `ClarityCommand` instance with the arguments prepared for the `window.clarity("identify", ...)` call.

### Method
Static method (PHP)

### Signature
`public static function identify(?object $user, ?string $sessionId = null, ?string $pageId = null): self`

### Parameters
- **$user** (?object) - Required - Any object with nullable `email` and `name` properties (e.g., an Eloquent User model). Read via `data_get($user, 'email')` / `data_get($user, 'name')`, so dot-notation nested attributes are also resolved. `null` is allowed.
- **$sessionId** (?string) - Optional - Custom session ID, passed through as-is. Default: `null`.
- **$pageId** (?string) - Optional - Custom page ID, passed through as-is. Default: `null`.

### Return Value
- **self** - Returns a `ClarityCommand` instance with arguments set to `['identify', data_get($user, 'email'), $sessionId, $pageId, data_get($user, 'name')]`. Missing properties and a `null` user produce `null` in the corresponding slots; no exception is raised.

### Example
```php
use Abr4xas\ClarityLaravel\ClarityCommand;

$user = (object) ['email' => 'a@b.com', 'name' => 'Ana'];

// → ['identify', 'a@b.com', 's1', 'p1', 'Ana']
$args = ClarityCommand::identify($user, 's1', 'p1')->arguments();

// User without a name → ['identify', 'a@b.com', null, null, null]
$args = ClarityCommand::identify((object) ['email' => 'a@b.com'])->arguments();

// Null user → ['identify', null, null, null, null] (safe, no exception)
$args = ClarityCommand::identify(null)->arguments();
```
```

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

### clarity_identify() with custom session and page IDs

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Passes custom session and page IDs to the helper using named arguments.

```php
// With custom session and page IDs
echo clarity_identify(
    user: auth()->user(),
    customSessionId: 'custom-session-123',
    customPageId: 'checkout-page'
);
```

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

### clarity_tag() function signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Defines the clarity_tag() helper function. It accepts a string key and variadic values, returning a rendered script tag or null when Clarity is disabled.

```php
/**
 * Set a custom tag for the current Clarity session.
 *
 * @param  string  $key  The key for the custom tag
 * @param  mixed  ...$values  The value(s) for the custom tag (strings or arrays)
 * @return string|null The rendered script tag or null
 */
function clarity_tag(string $key, mixed ...$values): ?string

```

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

### Handling null return from clarity_identify()

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Checks if the returned script is null, indicating the Identify API is not enabled (CLARITY_IDENTIFICATION_ENABLED=false).

```php
// Handles null return when the Identify API is disabled
$script = clarity_identify($user);
if ($script === null) {
    // Identify API not enabled (CLARITY_IDENTIFICATION_ENABLED=false) — no-op
}
```

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

### ClarityCommand class declaration

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

The final readonly class with a private constructor and a promoted property for the normalized argument list. Instances are created only through static named constructors.

```php
final readonly class ClarityCommand
{
    /**
     * @param  array<int, mixed>  $arguments
     */
    private function __construct(private array $arguments) {}
}
```

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

### Identify API Helper Function

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Use the clarity_identify helper for programmatic identification, optionally including custom session and page IDs.

```php
// Basic usage
clarity_identify(auth()->user());

// With custom session and page IDs
clarity_identify(
    user: auth()->user(),
    customSessionId: 'custom-session-123',
    customPageId: 'checkout-page'
);
```

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

### Set Custom Tags via Helper Function

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Use the clarity_tag helper in controllers or middleware for programmatic tagging.

```php
// In a controller
clarity_tag('subscription', 'pro');

// Multiple values
clarity_tag('permissions', 'read', 'write', 'admin');

// Array of values
clarity_tag('features', ['feature_a', 'feature_b']);

// In middleware
class TrackUserSegment
{
    public function handle($request, Closure $next)
    {
        if (auth()->check()) {
            clarity_tag('user_segment', auth()->user()->segment);
        }
        return $next($request);
    }
}
```

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

### shareClarityData() method signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-middleware.md

The private shareClarityData() method shares Clarity data with views. It adds environment and route tags based on config, and shares the authenticated user if auto-identification is enabled.

```php
/**
 * Share Clarity data with views.
 */
private function shareClarityData(Request $request): void
```

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

### Blade template for <x-clarity::tag> component

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

The tag component's Blade template. It includes the clarity command with arguments from ClarityCommand::tag($key, $values) when enabled, config('clarity.enabled') is true, and a key is provided.

```blade
@props([
    'enabled' => true,
    'key' => null,
    'values' => [],
])

@if ($enabled && config('clarity.enabled') && $key)
    @include('clarity::command', [
        'arguments' => \Abr4xas\ClarityLaravel\ClarityCommand::tag($key, $values)->arguments(),
    ])
@endif
```

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

### Auto-discovery provider registration in composer.json

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-laravel-service-provider.md

Registers the service provider for Laravel auto-discovery via the extra.laravel.providers entry in composer.json.

```json
"extra": {
    "laravel": {
        "providers": [
            "Abr4xas\\ClarityLaravel\\ClarityLaravelServiceProvider"
        ]
    }
}
```

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

### clarity_identify() function definition

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

The function signature with docblock, showing parameters and return type. It returns a script tag or null when Clarity is disabled or the Identify API is not enabled.

```php
/**
 * Identify a user for the current Clarity session.
 *
 * @param  object  $user  User object exposing nullable `email` and `name` properties
 * @param  string|null  $customSessionId  Optional custom session ID
 * @param  string|null  $customPageId  Optional custom page ID
 * @return string|null The rendered script tag or null
 */
function clarity_identify(object $user, ?string $customSessionId = null, ?string $customPageId = null): ?string
```

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

### Set Custom Tags via Blade Component

Source: https://github.com/abr4xas/clarity-laravel/blob/master/README.md

Use the clarity::tag component to send metadata to Clarity. Supports single, multiple, or dynamic values.

```html
<!-- Set a single value -->
<x-clarity::tag key="plan" :values="['premium']" />

<!-- Set multiple values -->
<x-clarity::tag key="features" :values="['chat', 'video', 'notifications']" />

<!-- Dynamic values -->
<x-clarity::tag key="user_role" :values="[auth()->user()->role]" />
```

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

### Blade template for <x-clarity::consent> component

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

The consent component's Blade template. It includes the clarity command with arguments from ClarityCommand::consent($granted, config('clarity.consent_version', 'v2')) when enabled and config('clarity.enabled') is true.

```blade
@props([
    'enabled' => true,
    'granted' => true,
])

@if ($enabled && config('clarity.enabled'))
    @include('clarity::command', [
        'arguments' => \Abr4xas\ClarityLaravel\ClarityCommand::consent($granted, config('clarity.consent_version', 'v2'))->arguments(),
    ])
@endif
```

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

### clarity_consent function signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Defines the clarity_consent helper function. It accepts a boolean $granted parameter (default true) and returns a string or null. The function sets consent for the current Clarity session.

```php
/**
 * Set consent for the current Clarity session.
 *
 * @param  bool  $granted  Whether consent is granted (true) or denied (false)
 * @return string|null The rendered script tag or null
 */
function clarity_consent(bool $granted = true): ?string
```

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

### clarity_set_custom_user_id function signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Defines the clarity_set_custom_user_id helper function. It accepts a required string $userId and returns a string or null. This function sets a custom user ID for the current Clarity session and requires the Identify API to be enabled.

```php
/**
 * Set a custom user ID for the current Clarity session.
 * Requires identify API to be enabled.
 *
 * @param  string  $userId  The custom user ID
 * @return string|null The rendered script tag or null
 */
function clarity_set_custom_user_id(string $userId): ?string
```

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

### ClarityCommand::customUserId signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Defines the static method that sets a custom user ID. It returns $this and builds arguments ['identify', $userId, null, null, null].

```PHP
/**
 * Custom user ID: `window.clarity("identify", user-id, null, null, null)`.
 */
public static function customUserId(string $userId): self
```

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

### Identify Component Blade Template

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/blade-components.md

Blade component template for the identify component, which includes the command partial when enabled and configuration allows.

```blade
@props([
    'enabled' => true,
    'user' => null,
    'custom_session_id' => null,
    'custom_page_id' => null,
])

@if ($enabled && config('clarity.enabled') && config('clarity.enabled_identify_api'))
    @include('clarity::command', [
        'arguments' => \Abr4xas\ClarityLaravel\ClarityCommand::identify($user, $custom_session_id, $custom_page_id)->arguments(),
    ])
@endif
```

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

### ClarityCommand::customPageId signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Defines the static method for setting the custom page ID, returning $this and producing arguments ['identify', null, null, $pageId, null].

```PHP
/**
 * Custom page ID: `window.clarity("identify", null, null, page-id, null)`.
 */
public static function customPageId(string $pageId): self
```

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

### Register Middleware in Laravel 10 and below

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-middleware.md

Register the middleware within the middlewareGroups array in the app/Http/Kernel.php file.

```php
protected $middlewareGroups = [
    'web' => [
        // ... other middleware
        \Abr4xas\ClarityLaravel\Middleware\ClarityMiddleware::class,
    ],
];
```

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

### clarity_set_custom_user_id(string $userId): ?string

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/helpers.md

Sets a custom user ID for the current Clarity session. Requires the identify API to be enabled.

```APIDOC
## clarity_set_custom_user_id(string $userId): ?string

### Description
Sets a custom user ID for the current Clarity session. Requires the identify API to be enabled.

### Method
Function

### Signature
`clarity_set_custom_user_id(string $userId): ?string`

### Parameters
- **$userId** (string) - Required - The custom user ID

### Return Value
- **?string** - Rendered `<script>` for `window.clarity("identify", $userId, null, null, null)`, or `null` when Clarity is disabled or the Identify API is disabled.

### Examples
```php
// Set a custom user ID
echo clarity_set_custom_user_id('user-123');
```
```

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

### ClarityCommand::customSessionId signature

Source: https://github.com/abr4xas/clarity-laravel/blob/master/_autodocs/api-reference/clarity-command.md

Defines the static method to set the custom session ID. It returns $this and builds the arguments array ['identify', null, $sessionId, null, null].

```PHP
/**
 * Custom session ID: `window.clarity("identify", null, session-id, null, null)`.
 */
public static function customSessionId(string $sessionId): self
```
Tokens:
Raw