Scalar for Laravel

https://github.com/scalar/laravel
Admin
Scalar for Laravel is a Laravel package that renders modern, interactive API references from...
Tokens:20,341
Snippets:360
Trust Score:9.5
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Route List Output Example

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Example output format for the route:list command.

```text
GET|HEAD   /scalar                    Scalar\Controllers\ScalarController
```

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

### Configure Middleware

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Examples of middleware configurations for the scalar.middleware key in the configuration file.

```php
// Default configuration
'middleware' => ['web'],

// Require authentication
'middleware' => ['web', 'auth'],

// Require admin role
'middleware' => ['web', 'auth', 'role:admin'],

// Rate limiting
'middleware' => ['web', 'throttle:60,1'],

// Multiple custom middleware
'middleware' => ['web', 'auth', 'verified', 'admin-only'],
```

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

### Package Testing Scenarios

Source: https://github.com/scalar/laravel/blob/main/_autodocs/0_README.md

Provides examples for testing route registration, view rendering, authorization logic, and configuration settings using Pest.

```php
// Test route registration
it('registers scalar route', function () {
    $route = Route::getRoutes()->getByName('scalar');
    expect($route)->not->toBeNull();
});

// Test view rendering
it('returns scalar view', function () {
    $response = $this->get('/scalar');
    $response->assertViewIs('scalar::reference');
});

// Test authorization
it('respects authorization gate', function () {
    Gate::define('viewScalar', fn () => false);
    $response = $this->get('/scalar');
    $response->assertForbidden();
});

// Test configuration
it('includes OpenAPI URL', function () {
    $response = $this->get('/scalar');
    $response->assertSee(config('scalar.url'));
});
```

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

### HTTP Request Structure

Source: https://github.com/scalar/laravel/blob/main/_autodocs/6_endpoints.md

Examples of the HTTP request structure for accessing the API reference.

```http
GET /scalar HTTP/1.1
Host: example.com
```

```http
GET /scalar HTTP/1.1
Host: example.com
User-Agent: Mozilla/5.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
```

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

### Install Scalar for Laravel

Source: https://github.com/scalar/laravel/blob/main/README.md

Install the Scalar package for Laravel using Composer. This is the initial step to integrate API reference generation into your Laravel project.

```bash
composer require scalar/laravel
```

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

### Successful HTTP Response

Source: https://github.com/scalar/laravel/blob/main/_autodocs/6_endpoints.md

Example of a 200 OK response returning the Scalar API reference HTML.

```http
GET /scalar HTTP/1.1
Host: example.com
Accept: text/html

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Content-Length: 2847

<!doctype html>
<html>
<head>
    <title>My App API Reference</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
    <div id="app"></div>
    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
    <script>
       Scalar.createApiReference('#app', {
           "theme": "laravel",
           "layout": "modern",
           "showSidebar": true,
           "hideModels": false,
           "darkMode": false,
           "url": "/openapi.json",
           "_integration": "laravel"
       })
    </script>
</body>
</html>
```

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

### Install Scalar Laravel via Composer

Source: https://github.com/scalar/laravel/blob/main/_autodocs/0_README.md

Run this command in your terminal to add the package to your project dependencies.

```bash
composer require scalar/laravel
```

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

### GET /scalar

Source: https://github.com/scalar/laravel/blob/main/_autodocs/6_endpoints.md

Renders the Scalar API reference view, which displays the API documentation UI.

```APIDOC
## GET /scalar

### Description
Renders the Scalar API reference view. This endpoint serves the HTML page that loads and initializes the Scalar API reference from an OpenAPI document.

### Method
GET

### Endpoint
/scalar

### Response
#### Success Response (200)
- **Content-Type** (string) - text/html; charset=UTF-8

#### Error Response (403)
- **Description** - Access denied if authorization check fails in non-local environment
```

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

### Customizing the Base Layout

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

Example of a modified layout file located at resources/views/vendor/scalar/layout.blade.php.

```blade
<!doctype html>
<html>
<head>
    <title>{{ \Scalar\Scalar::pageTitle() }}</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    
    <!-- Add custom styles -->
    <style>
        body { font-family: 'Courier New', monospace; }
        .custom-header { background: #f0f0f0; padding: 20px; }
    </style>
</head>
<body>
    <div class="custom-header">
        <h1>My Custom API Documentation</h1>
    </div>
    @yield('content')
</body>
</html>
```

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

### HTTP Response Examples

Source: https://github.com/scalar/laravel/blob/main/_autodocs/2_scalar-controller.md

Standard HTTP response structures for successful and unauthorized requests to the Scalar endpoint.

```http
GET /scalar HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Content-Length: 2540

<!doctype html>
<html>
<head>
    <title>My App API Reference</title>
    <meta charset="utf-8" />
    ...
</head>
<body>
    <div id="app"></div>
    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
    <script>
       Scalar.createApiReference('#app', {...})
    </script>
</body>
</html>
```

```http
GET /scalar HTTP/1.1
Host: example.com

HTTP/1.1 403 Forbidden
Content-Type: text/html

Forbidden
```

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

### GET /scalar

Source: https://github.com/scalar/laravel/blob/main/_autodocs/6_endpoints.md

Retrieves the HTML page containing the Scalar API reference interface.

```APIDOC
## GET /scalar

### Description
Retrieves the HTML document that renders the Scalar API reference interface.

### Method
GET

### Endpoint
/scalar

### Response
#### Success Response (200)
- **Content-Type** (text/html) - Returns the HTML structure for the API reference.

#### Error Response (403)
- **Status** (403) - Returned when access to the documentation route is forbidden.
```

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

### Linking to Scalar in Blade Templates

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Provides examples for creating links to the Scalar documentation within Blade views.

```blade
<!-- Link to Scalar -->
<a href="{{ route('scalar') }}">API Documentation</a>

<!-- With query parameters (ignored by Scalar) -->
<a href="{{ route('scalar') }}?theme=dark">API Documentation</a>
```

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

### Forbidden HTTP Response

Source: https://github.com/scalar/laravel/blob/main/_autodocs/6_endpoints.md

Example of a 403 Forbidden response when access is denied.

```http
GET /scalar HTTP/1.1
Host: example.com
Accept: text/html

HTTP/1.1 403 Forbidden
Content-Type: text/html; charset=UTF-8

Forbidden
```

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

### Define Authorization Gate

Source: https://github.com/scalar/laravel/blob/main/_autodocs/2_scalar-controller.md

Example of defining the viewScalar gate within the AppServiceProvider to restrict access to specific users.

```php
// Define authorization in app/Providers/AppServiceProvider.php:
use App\Models\User;
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::define('viewScalar', function (?User $user) {
        // Allow specific users to view Scalar
        return $user && in_array($user->email, [
            'admin@example.com',
            'devlead@example.com',
        ]);
    });
}
```

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

### Compare facade and direct class usage

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

Illustrates the syntax differences between direct class instantiation and facade usage.

```php
// Direct class usage (requires full namespace)
use Scalar\Scalar;
$title = Scalar::pageTitle();

// Facade usage (cleaner, global alias available)
use Scalar\Facades\Scalar;
$title = Scalar::pageTitle();

// Or just use the global alias
$title = Scalar::pageTitle();
```

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

### Publish Configuration File

Source: https://github.com/scalar/laravel/blob/main/_autodocs/9_package-structure.md

Run this command to publish the package configuration file to the application's config directory.

```text
config/scalar.php (published)
```

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

### Boot Method Definition

Source: https://github.com/scalar/laravel/blob/main/_autodocs/3_service-provider.md

The boot method signature for the service provider.

```php
public function boot(): void
```

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

### Publish View Files

Source: https://github.com/scalar/laravel/blob/main/_autodocs/9_package-structure.md

Run this command to publish the package's Blade view files to the application's resources directory.

```text
resources/views/vendor/scalar/layout.blade.php (published)
resources/views/vendor/scalar/reference.blade.php (published)
```

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

### Configure Scalar Settings

Source: https://github.com/scalar/laravel/blob/main/_autodocs/3_service-provider.md

Define package behavior, routes, and UI themes in the configuration file.

```php
<?php

return [
    'path' => '/api-reference',
    'domain' => 'docs.example.com',
    'middleware' => ['web', 'auth'],
    'url' => '/openapi.json',
    'cdn' => 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',
    'configuration' => [
        'theme' => 'laravel',
        'layout' => 'modern',
        'showSidebar' => true,
        'darkMode' => false,
        // ... other options
    ],
];
```

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

### Custom Domain and Path Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Configure a specific subdomain and path for the documentation route.

```php
'domain' => 'docs.example.com',
'path' => '/api-reference',
'middleware' => ['web'],
```

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

### Basic Route Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Standard configuration for setting the route path and middleware.

```php
'path' => '/scalar',
'middleware' => ['web'],
```

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

### Enable Dark Mode

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Set the default theme mode to dark.

```php
// config/scalar.php
'configuration' => [
    'darkMode' => true,
],
```

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

### ConfigurePackage Method Definition

Source: https://github.com/scalar/laravel/blob/main/_autodocs/3_service-provider.md

The method signature for configuring package resources.

```php
public function configurePackage(Package $package): void
```

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

### Define Multiple API References

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Configure multiple routes to serve different API references with unique configurations.

```php
// routes/web.php
Route::get('/docs/api', function () {
    return view('scalar.reference', [
        'config' => Scalar::configuration(),
    ]);
});

Route::get('/docs/webhooks', function () {
    return view('scalar.reference', [
        'config' => array_merge(Scalar::configuration(), [
            'url' => '/webhooks-openapi.json',
        ]),
    ]);
});
```

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

### Configure Default HTTP Client

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Sets the default HTTP client in the configuration file to prefill credentials in the test interface.

```php
// config/scalar.php
'configuration' => [
    'defaultHttpClient' => [
        'targetId' => 'shell',
        'clientKey' => 'curl',
    ],
],
```

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

### Customize Documentation Theme

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Select a theme for the documentation interface within the configuration array.

```php
// config/scalar.php
'configuration' => [
    'theme' => 'laravel',  // Use Laravel theme
    // Other options:
    // 'theme' => 'deepSpace',
    // 'theme' => 'mars',
    // 'theme' => 'moon',
    // 'theme' => 'purple',
    // ...
],
```

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

### Retrieve Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/1_scalar-class.md

Returns the full configuration as a JSON-ready Laravel Collection.

```php
public static function configuration(): \Illuminate\Support\Collection
```

```php
// In a Blade template:
Scalar.createApiReference('#app', {!! Scalar::configuration() !!})

// Rendered configuration includes:
{
    "theme": "laravel",
    "layout": "modern",
    "showSidebar": true,
    "hideModels": false,
    "darkMode": false,
    "url": "/openapi.yaml",
    "_integration": "laravel"
}
```

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

### Protected Route Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Apply authentication and authorization middleware to the documentation route.

```php
'path' => '/api-docs',
'middleware' => ['web', 'auth', 'can:view-api-docs'],
```

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

### Environment Variable Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Set Scalar paths and URLs directly in the .env file.

```env
SCALAR_PATH=/api-docs
SCALAR_URL=https://api.example.com/openapi.json
SCALAR_CDN=https://cdn.example.com/scalar
```

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

### Scalar Configuration File

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Define environment-specific settings in the configuration file using the env helper.

```php
// config/scalar.php
return [
    'path' => env('SCALAR_PATH', '/scalar'),
    'url' => env('SCALAR_URL', '/openapi.json'),
    // ...
];
```

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

### Configure Middleware Execution Order

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Middleware is applied sequentially based on the configuration array order.

```php
'middleware' => ['web', 'auth', 'throttle:60,1']
```

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

### Configure server overrides

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Define a list of servers to override those specified in the OpenAPI document.

```php
'servers' => [
    [
        'url' => 'https://api.example.com',
        'description' => 'Production server',
    ],
    [
        'url' => 'https://staging-api.example.com',
        'description' => 'Staging server',
    ],
],
```

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

### Configure custom CSS

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Inject custom CSS styles into the documentation page using a heredoc string.

```php
'customCss' => <<<CSS
    .header { background: #ff0000; }
CSS,
```

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

### Configure authentication prefill

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Define authentication credentials to prefill in the documentation interface.

```php
'authentication' => [
    // TODO: Configuration options
],
```

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

### Package Namespace Structure

Source: https://github.com/scalar/laravel/blob/main/_autodocs/9_package-structure.md

Visual representation of the project directory and namespace hierarchy.

```text
Scalar\
├── Scalar                    # Main class
├── ScalarServiceProvider     # Service provider
├── Controllers\
│   └── ScalarController      # HTTP controller
├── Facades\
│   └── Scalar                # Facade
└── Tests\                    # Test namespace
    ├── ScalarTest
    ├── ArchTest
    └── TestCase
```

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

### Publish Scalar Assets

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Commands to publish configuration files or Blade templates for customization.

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

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

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

### Configure API Reference Layout

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Sets the layout style for the API reference UI.

```php
'layout' => 'modern',
```

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

### Test Configuration Values

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Verify that the configured OpenAPI URL is correctly rendered in the response.

```php
it('includes OpenAPI URL in response', function () {
    $response = $this->get('/scalar');
    
    $response->assertSee(config('scalar.url'));
});
```

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

### Configure Download Button Visibility

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Toggles the visibility of the OpenAPI document download button.

```php
'hideDownloadButton' => false,
```

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

### Package Directory Layout

Source: https://github.com/scalar/laravel/blob/main/_autodocs/9_package-structure.md

Visual representation of the file structure for the Scalar Laravel package.

```text
scalar/laravel/
├── config/
│   └── scalar.php                 # Configuration file
├── database/
│   └── factories/                 # Database factories (if any)
├── resources/
│   └── views/
│       └── scalar/
│           ├── layout.blade.php   # Main HTML template
│           └── reference.blade.php # API reference view
├── routes/
│   └── web.php                    # Route definitions
├── src/
│   ├── Scalar.php                 # Main class
│   ├── ScalarServiceProvider.php   # Service provider
│   ├── Controllers/
│   │   └── ScalarController.php    # HTTP controller
│   └── Facades/
│       └── Scalar.php             # Facade
├── tests/
│   ├── Pest.php                   # Pest configuration
│   ├── TestCase.php               # Base test class
│   ├── ArchTest.php               # Architecture tests
│   └── ScalarTest.php             # Scalar tests
├── composer.json                  # Composer configuration
├── README.md                      # Package documentation
├── CHANGELOG.md                   # Version history
└── LICENSE.md                     # MIT License
```

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

### Configure Scalar settings in config/scalar.php

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Define package settings using the env() helper to allow overrides from the environment file.

```php
'url' => env('SCALAR_OPENAPI_URL', '/openapi.json'),
'cdn' => env('SCALAR_CDN_URL', 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'),
```

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

### Retrieve Scalar API configuration and settings

Source: https://github.com/scalar/laravel/blob/main/_autodocs/0_README.md

Use these static methods to access the page title, OpenAPI document URL, CDN assets, and full configuration object.

```php
// Get the HTML page title
$title = Scalar::pageTitle();

// Get the OpenAPI document URL
$url = Scalar::url();

// Get the CDN URL for Scalar assets
$cdn = Scalar::cdn();

// Get the complete configuration (for frontend)
$config = Scalar::configuration();
```

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

### Verify Scalar Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Check the configured URL for the OpenAPI document.

```php
config('scalar.url')
```

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

### Debug Scalar Routes

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Use artisan commands to list and filter registered application routes.

```bash
php artisan route:list
```

```bash
php artisan route:list | grep scalar
```

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

### Integrate with Scramble

Source: https://github.com/scalar/laravel/blob/main/_autodocs/0_README.md

Point the url configuration to the Scramble JSON route to use it as the OpenAPI source.

```php
'url' => route('scramble.json'),
```

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

### Configure Initial Dark Mode State

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Sets the initial dark mode state upon page load.

```php
'darkMode' => false,
```

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

### Configure Route Path

Source: https://github.com/scalar/laravel/blob/main/_autodocs/INDEX.md

Update the path setting in config/scalar.php to change the documentation URL.

```php
'path' => '/api-docs',
```

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

### Configure default fonts

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Toggle the loading of default Inter and JetBrains Mono fonts.

```php
'withDefaultFonts' => true,
```

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

### Publish Scalar Resources

Source: https://github.com/scalar/laravel/blob/main/_autodocs/3_service-provider.md

Artisan commands to publish configuration and view files for the Scalar package.

```bash
# Publish only config
php artisan vendor:publish --tag="scalar-config"

# Publish only views
php artisan vendor:publish --tag="scalar-views"

# Publish all Scalar resources
php artisan vendor:publish --provider="Scalar\ScalarServiceProvider"
```

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

### API Versioning Routes

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Define multiple Scalar instances by grouping routes with different prefixes and view parameters.

```php
// routes/web.php
Route::group(['prefix' => 'docs/v1'], function () {
    Route::get('/', fn() => view('scalar', [
        'url' => '/openapi/v1.json',
        'title' => 'API v1 Documentation',
    ]));
});
```

```php
Route::group(['prefix' => 'docs/v2'], function () {
    Route::get('/', fn() => view('scalar', [
        'url' => '/openapi/v2.json',
        'title' => 'API v2 Documentation',
    ]));
});
```

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

### Register the facade in composer.json

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

Configures the package alias for Laravel's auto-discovery.

```json
{
    "extra": {
        "laravel": {
            "aliases": {
                "Scalar": "Scalar\\Facades\\Scalar"
            }
        }
    }
}
```

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

### Run Tests

Source: https://github.com/scalar/laravel/blob/main/README.md

Execute the project's tests using Composer. This command is used to verify the functionality and stability of the Scalar for Laravel package.

```bash
composer test
```

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

### Configure base server URL

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Set a base URL for servers when the OpenAPI specification uses relative paths.

```php
'baseServerURL' => 'https://api.example.com',
```

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

### Publish Scalar Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/0_README.md

Publishes the package configuration file to the application's config directory.

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

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

### Integrate with laravel-openapi

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Commands and configuration to use laravel-openapi as the generator.

```bash
composer require vyuldashev/laravel-openapi
```

```php
// config/scalar.php
'url' => route('openapi'),
```

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

### Define Scalar configuration array

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

The configuration file defines the API documentation path, middleware, and various UI settings for the Scalar API reference.

```php
<?php

return [
    'domain' => null,
    'path' => '/api-docs',
    'middleware' => ['web', 'auth'],
    'url' => route('scramble.json'),
    'cdn' => 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',
    
    'configuration' => [
        'theme' => 'laravel',
        'layout' => 'modern',
        'proxyUrl' => 'https://proxy.scalar.com',
        'showSidebar' => true,
        'hideModels' => false,
        'hideDownloadButton' => false,
        'hideTestRequestButton' => false,
        'hideSearch' => false,
        'darkMode' => false,
        'forceDarkModeState' => 'dark',
        'hideDarkModeToggle' => false,
        'searchHotKey' => 'k',
        'metaData' => [
            'title' => 'Acme Corp API Reference',
        ],
        'favicon' => '/favicon.svg',
        'hiddenClients' => [],
        'defaultHttpClient' => [
            'targetId' => 'shell',
            'clientKey' => 'curl',
        ],
        'withDefaultFonts' => true,
        'defaultOpenAllTags' => false,
    ],
];
```

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

### Customize Theme

Source: https://github.com/scalar/laravel/blob/main/_autodocs/INDEX.md

Set the theme option within the configuration array in config/scalar.php.

```php
'configuration' => [
    'theme' => 'deepSpace',
],
```

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

### Configure OpenAPI URL

Source: https://github.com/scalar/laravel/blob/main/_autodocs/0_README.md

Set the path to your OpenAPI specification file within the configuration array.

```php
'url' => '/openapi.json',  // URL to your OpenAPI spec
```

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

### Scalar::configuration()

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

Retrieves the complete configuration object for Scalar.

```APIDOC
## Scalar::configuration()

### Description
Returns the full configuration object as a Collection.

### Returns
- **Collection** - The complete configuration object.
```

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

### Configure Custom CDN

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Override the default jsDelivr CDN by setting a custom URL in the configuration.

```php
'cdn' => 'https://your-cdn.com/scalar-api-reference',
```

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

### Integrate with Scramble

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Commands and configuration to use Scramble as the OpenAPI generator.

```bash
composer require dedoc/scramble
php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider"
```

```php
// config/scalar.php
'url' => route('scramble.json'),
```

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

### Test Scalar Endpoint Registration and Response

Source: https://github.com/scalar/laravel/blob/main/_autodocs/6_endpoints.md

Use Pest or PHPUnit to verify route registration, view rendering, and gate enforcement.

```php
use Illuminate	Support	Facades	Route;

it('registers the Scalar route', function () {
    $routes = Route::getRoutes();
    $route = $routes->getByName('scalar');
    
    expect($route)->not->toBeNull()
        ->and('/' . $route->uri())->toBe('/scalar');
});

it('returns the Scalar view', function () {
    $response = $this->get('/scalar');
    
    $response->assertOk()
        ->assertViewIs('scalar::reference');
});

it('respects the viewScalar gate', function () {
    Gate::define('viewScalar', fn () => false);
    
    $response = $this->get('/scalar');
    
    $response->assertForbidden();
});
```

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

### Configure Endpoint Middleware

Source: https://github.com/scalar/laravel/blob/main/_autodocs/6_endpoints.md

Add additional middleware to the scalar configuration array to protect the endpoint.

```php
'middleware' => ['web', 'auth', 'throttle:60,1'],
```

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

### Configure Favicon

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Sets the path to the favicon image displayed in the browser tab.

```php
'favicon' => '/favicon.svg',
```

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

### Use Scalar facade in Service classes

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

Injecting or using the facade within custom application services.

```php
<?php

namespace App\Services;

use Scalar\Facades\Scalar;

class DocumentationService
{
    public function getApiMetadata()
    {
        return [
            'title' => Scalar::pageTitle(),
            'openapi_url' => Scalar::url(),
            'cdn_url' => Scalar::cdn(),
        ];
    }
}
```

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

### Configure Page Metadata

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Defines HTML metadata tags for the documentation page header.

```php
'metaData' => [
    'title' => 'My Company API Reference',
    'description' => 'Complete API documentation',
    'og:image' => 'https://example.com/og-image.png',
],
```

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

### Common Middleware Patterns

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Standard middleware configurations for authentication, roles, rate limiting, and CORS.

```php
'middleware' => ['web', 'auth'],
```

```php
'middleware' => ['web', 'auth', 'role:admin,developer'],
```

```php
'middleware' => ['web', 'throttle:60,1'],
```

```php
'middleware' => ['web', 'cors'],
```

```php
'middleware' => [
    'web',
    'auth',
    'verified',
    'admin-only',
    'log-access',
],
```

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

### Configure Search Hotkey

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Sets the keyboard shortcut used to trigger the search modal.

```php
'searchHotKey' => 'k',
```

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

### Configuration Access Flow

Source: https://github.com/scalar/laravel/blob/main/_autodocs/9_package-structure.md

Path of configuration data from the config file to the frontend JavaScript.

```text
config/scalar.php
    ↓
Scalar class static methods
    ↓
Blade templates
    ↓
JavaScript frontend (Scalar.createApiReference)
```

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

### Define Scalar environment variables in .env

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Set the corresponding environment variables to override default configuration values.

```text
SCALAR_OPENAPI_URL=https://api.example.com/openapi.json
SCALAR_CDN_URL=https://cdn.example.com/scalar-api-reference
```

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

### Testing Scalar Integration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/2_scalar-controller.md

Unit and feature testing patterns to verify route accessibility, view rendering, and authorization logic.

```php
// Test that the route is accessible
$response = $this->get(config('scalar.path'));
$response->assertOk();

// Test that the view is rendered
$response->assertViewIs('scalar::reference');

// Test authorization
Gate::define('viewScalar', fn () => false);
$response = $this->get(config('scalar.path'));
$response->assertForbidden();
```

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

### Scalar::configuration()

Source: https://github.com/scalar/laravel/blob/main/_autodocs/1_scalar-class.md

Returns the complete Scalar configuration as a Laravel Collection, ready for JSON encoding.

```APIDOC
## Scalar::configuration()

### Description
Retrieves all configuration from `scalar.configuration`, merges theme and URL settings, and adds the Laravel integration identifier. This is intended to be JSON-encoded for the frontend JavaScript API.

### Signature
`public static function configuration(): \Illuminate\Support\Collection`

### Returns
- **\Illuminate\Support\Collection** - A collection containing all Scalar configuration options.
```

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

### Link to API Documentation in Blade

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Use the route helper to generate a link to the Scalar documentation page.

```blade
<a href="{{ route('scalar') }}">View API Documentation</a>
```

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

### Test Route URL Generation

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Ensure the route helper generates the expected URL path.

```php
it('generates correct scalar URL', function () {
    expect(route('scalar'))->toBe('/scalar');
});
```

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

### Composer Autoload Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/9_package-structure.md

Defines the PSR-4 namespace mapping for the package source and database factories.

```json
"autoload": {
    "psr-4": {
        "Scalar\\": "src/",
        "Scalar\\Database\\Factories\\": "database/factories/"
    }
}
```

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

### Facade DocBlock reference

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

The PHPDoc annotation used to link the facade to the underlying class for IDE support.

```php
/**
 * @see \Scalar\Scalar
 */
class Scalar extends Facade
```

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

### Set Custom Page Title

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Define the meta title for the documentation page.

```php
// config/scalar.php
'configuration' => [
    'metaData' => [
        'title' => 'My Company API Reference',
    ],
],
```

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

### Test HTTP Request to Route

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Verify that the scalar route returns a successful HTTP response.

```php
it('responds to GET request on scalar route', function () {
    $response = $this->get(config('scalar.path'));
    
    $response->assertOk();
});
```

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

### Retrieve OpenAPI URL

Source: https://github.com/scalar/laravel/blob/main/_autodocs/1_scalar-class.md

Fetches the URL for the OpenAPI document used by the reference.

```php
public static function url(): string
```

```php
// Get the OpenAPI document URL
$openApiUrl = Scalar::url();
// Returns: "/openapi.yaml" or "https://api.example.com/openapi.json"
```

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

### Integrate with Scribe

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Commands and configuration to use Scribe as the OpenAPI generator.

```bash
composer require --dev knuckleswtf/scribe
php artisan scribe:generate
```

```php
// config/scalar.php
'url' => '/docs/openapi.json',
```

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

### Configure Dark Mode Toggle Visibility

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Toggles the visibility of the dark mode switch in the UI.

```php
'hideDarkModeToggle' => false,
```

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

### Configure API Reference Theme

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Sets the visual theme for the API reference. The 'laravel' theme applies custom CSS integration specific to the Laravel framework.

```php
'theme' => 'laravel',
```

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

### Local Development Access

Source: https://github.com/scalar/laravel/blob/main/_autodocs/2_scalar-controller.md

Note on local environment behavior where the gate check is bypassed.

```php
// No gate check required; all requests allowed in 'local' environment
// Access at: http://localhost:8000/scalar
```

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

### Load Scalar Views

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

Use the scalar:: namespace to load layout or reference templates via the view helper.

```php
view('scalar::layout');        // Load layout template
view('scalar::reference');     // Load reference template
```

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

### Configure default tag expansion

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Control whether all endpoint tags are expanded by default upon loading.

```php
'defaultOpenAllTags' => false,
```

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

### Set Default HTTP Client

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Defines the default client selected in the request tester.

```php
'defaultHttpClient' => [
    'targetId' => 'shell',
    'clientKey' => 'curl',
],
```

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

### Integrate with OpenAPI Generators

Source: https://github.com/scalar/laravel/blob/main/_autodocs/INDEX.md

Configure the URL for Scribe or Scramble OpenAPI generators in the package configuration.

```php
'url' => '/docs/openapi.json',
```

```php
'url' => route('scramble.json'),
```

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

### Accessing the API Reference

Source: https://github.com/scalar/laravel/blob/main/_autodocs/2_scalar-controller.md

Methods for generating the Scalar route URL within a Laravel application.

```php
// In routes or navigation
route('scalar');  // Returns: /scalar

// Direct URL
http://example.com/scalar
```

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

### Configure authorization gate

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Override the viewScalar gate in the AppServiceProvider to control access to the documentation.

```php
<?php

namespace App\Providers;

use Illuminate\Support\Facades\Gate;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Gate::define('viewScalar', function ($user = null) {
            // Your authorization logic here
            return $user?->is_admin ?? false;
        });
    }
}
```

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

### Configure Scalar Domain

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Sets the subdomain for the Scalar documentation interface.

```php
'domain' => 'docs.example.com',
```

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

### Access Scalar via Facade

Source: https://github.com/scalar/laravel/blob/main/_autodocs/1_scalar-class.md

Use the Scalar facade for a cleaner syntax when accessing configuration and metadata throughout the application.

```php
use Scalar\Facades\Scalar;

$title = Scalar::pageTitle();
$url = Scalar::url();
$config = Scalar::configuration();
```

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

### Test Route Existence

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Verify that the scalar route is registered in the application route collection.

```php
use Illuminate\Support\Facades\Route;

it('registers the scalar route', function () {
    $routes = Route::getRoutes();
    $route = $routes->getByName('scalar');
    
    expect($route)->not->toBeNull();
});
```

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

### Configure Scalar CDN URL

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Sets the base URL for loading Scalar's JavaScript and CSS assets. Use this to override the default CDN or host assets locally.

```php
'cdn' => 'https://cdn.example.com/scalar-api-reference',
```

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

### Publish Scalar Views

Source: https://github.com/scalar/laravel/blob/main/README.md

Optionally, publish the view files for Scalar. This enables customization of the visual presentation of your API reference documentation.

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

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

### Configure Sidebar Visibility

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Controls the visibility of the endpoint sidebar.

```php
'showSidebar' => true,
```

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

### Restrict Access to Non-Production

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Disable access to the documentation in production environments.

```php
Gate::define('viewScalar', function ($user = null) {
    return ! app()->isProduction();
});
```

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

### Rate Limited Route Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Apply rate limiting middleware to restrict access frequency.

```php
'path' => '/scalar',
'middleware' => ['web', 'throttle:100,1'],
```

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

### Publish Scalar Views

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

Command to publish the Scalar Blade templates to your application's resources directory for customization.

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

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

### Configure Scalar Path

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Defines the URI path where the Scalar interface is accessible.

```php
'path' => '/api-reference',
```

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

### Request Handling Flow

Source: https://github.com/scalar/laravel/blob/main/_autodocs/9_package-structure.md

Sequence of operations from the initial HTTP request to the final HTML response.

```text
HTTP GET /scalar
    ↓
Route (routes/web.php)
    ↓
ScalarController::__invoke()
    ↓
Authorization gate check (viewScalar)
    ↓
View rendering (scalar::reference)
    ↓
Layout template (scalar::layout)
    ↓
Scalar::configuration() for frontend config
    ↓
HTML response with Scalar.js initialization
```

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

### Test Route Registration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Verify that the scalar route is correctly registered in the application.

```php
use Illuminate\Support\Facades\Route;

it('registers scalar route', function () {
    $route = Route::getRoutes()->getByName('scalar');
    expect($route)->not->toBeNull();
});
```

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

### Access Scalar methods in a Controller

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

Demonstrates usage with an explicit use statement versus relying on the global alias.

```php
<?php

use Scalar\Facades\Scalar;

class MyController extends Controller
{
    public function show()
    {
        $title = Scalar::pageTitle();
        $url = Scalar::url();
        $config = Scalar::configuration();
        
        return view('my-view', compact('title', 'url', 'config'));
    }
}
```

```php
<?php

class MyController extends Controller
{
    public function show()
    {
        // Available globally as registered in composer.json
        $title = Scalar::pageTitle();
        $url = Scalar::url();
        
        return view('my-view', compact('title', 'url'));
    }
}
```

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

### Define Scalar Route Parameters

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Scalar routes do not support URL parameters; only the base path is valid.

```text
Valid URLs:
  GET /scalar
  GET /scalar?foo=bar  (query params ignored)

Invalid URLs:
  GET /scalar/{id}     (no parameter support)
```

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

### HTML Response Structure

Source: https://github.com/scalar/laravel/blob/main/_autodocs/6_endpoints.md

The HTML document returned by the endpoint, which initializes the Scalar API reference.

```html
<!doctype html>
<html>
<head>
    <title>{configured title}</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    {theme CSS if laravel theme}
</head>
<body>
    <div id="app"></div>
    <script src="{cdn url}"></script>
    <script>
        Scalar.createApiReference('#app', {configuration object})
    </script>
</body>
</html>
```

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

### Scalar.createApiReference()

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

Initializes the Scalar API reference interface within a specified DOM element.

```APIDOC
## Scalar.createApiReference(selector, configuration)

### Description
Initializes and renders the Scalar API reference interface into the specified container element.

### Parameters
- **selector** (string) - Required - The CSS selector for the container element (e.g., '#app').
- **configuration** (object) - Required - The Scalar configuration object, typically retrieved from `Scalar::configuration()`.
```

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

### Retrieve Page Title

Source: https://github.com/scalar/laravel/blob/main/_autodocs/1_scalar-class.md

Fetches the configured page title for the API reference view.

```php
public static function pageTitle(): string
```

```php
// In a Blade template or controller
$title = Scalar::pageTitle();
// Returns: "My App API Reference" (or custom configured value)
```

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

### Scalar View Directory Structure

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

The file structure created in the Laravel resources directory after publishing the package views.

```text
resources/
└── views/
    └── vendor/
        └── scalar/
            ├── layout.blade.php
            └── reference.blade.php
```

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

### Implement getFacadeAccessor

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

Required method to identify the underlying class resolved from the container.

```php
protected static function getFacadeAccessor(): string
```

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

### Cache OpenAPI Documents

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Improve performance by caching dynamically generated OpenAPI documents for a specified duration.

```php
// Cache for 24 hours
Route::get('/openapi.json', function () {
    return cache()->remember('openapi-doc', 86400, function () {
        return generateOpenApiDocument();
    });
});
```

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

### Configure Test Request Button Visibility

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Toggles the visibility of the button used for making test requests.

```php
'hideTestRequestButton' => false,
```

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

### Configure Model Visibility

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Toggles the visibility of schema models and components.

```php
'hideModels' => false,
```

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

### Configure Scalar Middleware

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Defines the array of middleware applied to the Scalar routes.

```php
'middleware' => ['web', 'auth', 'admin'],
```

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

### Clear Application Caches

Source: https://github.com/scalar/laravel/blob/main/_autodocs/0_README.md

Clears configuration, route, and view caches to ensure changes take effect.

```bash
php artisan config:clear
php artisan route:clear
php artisan view:clear
```

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

### Production Authorization Requirement

Source: https://github.com/scalar/laravel/blob/main/_autodocs/2_scalar-controller.md

Note on production environment behavior where the gate check is mandatory.

```php
// Authorization gate MUST pass or request is rejected with 403
// Ensure your gate is properly configured in AppServiceProvider
```

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

### Generating URLs with Custom Domains

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Generates absolute URLs or full paths when a custom domain is configured for Scalar.

```php
// Generate URL with domain
route('scalar', [], true);  // Absolute URL
// Returns: https://docs.example.com/scalar

// Or use full URL
url('https://docs.example.com/scalar');
```

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

### Configure Page Title Metadata

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Overrides the default HTML page title.

```php
'metaData' => [
    'title' => 'Acme Corp API Reference',
],
```

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

### Configure OpenAPI URL

Source: https://github.com/scalar/laravel/blob/main/README.md

Set the URL for your OpenAPI/Swagger document in the Scalar configuration file. This URL is used by Scalar to fetch the API specification for rendering.

```php
// config/scalar.php

return [
    // …

    'url' => '/openapi.yaml',

    // …
]
```

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

### Scalar::url()

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

Retrieves the URL for the OpenAPI document.

```APIDOC
## Scalar::url()

### Description
Returns the URL pointing to the OpenAPI document.

### Returns
- **string** - The OpenAPI document URL.
```

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

### Test Authorization Gate

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Verify gate functionality using the Laravel tinker console.

```php
Gate::check('viewScalar')
```

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

### Initialize Scalar API Reference

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

Call this function within a Blade view to mount the Scalar API reference to a specific DOM element.

```javascript
Scalar.createApiReference('#app', {configuration object})
```

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

### Configure Search Bar Visibility

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Toggles the visibility of the sidebar search bar.

```php
'hideSearch' => false,
```

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

### Configure OpenAPI Document URL

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Defines the source URL for the OpenAPI specification. The endpoint must be publicly accessible and return valid JSON or YAML.

```php
'url' => '/openapi.json',
```

```php
'url' => url('/api-documentation'),
```

```php
'url' => route('scramble.json'),
```

```php
'url' => 'https://api.example.com/openapi.json',
```

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

### Reference View Template

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

The main Blade template that mounts the Scalar API reference UI.

```blade
@extends('scalar::layout')

@section('content')
    <div id="app"></div>

    <script src="{{ \Scalar\Scalar::cdn() }}"></script>

    <script>
       Scalar.createApiReference('#app', {!! \Scalar\Scalar::configuration() !!})
    </script>
@endsection
```

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

### Define ScalarServiceProvider Class

Source: https://github.com/scalar/laravel/blob/main/_autodocs/3_service-provider.md

The base class definition for the Scalar service provider, extending the Spatie PackageServiceProvider.

```php
namespace Scalar;

use Illuminate	Support	Facades	Gate;
use Spatie	LaravelPackageTools	Package;
use Spatie	LaravelPackageTools	PackageServiceProvider;

class ScalarServiceProvider extends PackageServiceProvider
```

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

### Test Middleware Protection

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Verify that the route correctly redirects unauthenticated users to the login page.

```php
it('requires authentication for scalar route', function () {
    config(['scalar.middleware' => ['web', 'auth']]);
    
    $response = $this->get('/scalar');
    
    $response->assertRedirect('/login');
});
```

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

### Publish Scalar Configuration

Source: https://github.com/scalar/laravel/blob/main/README.md

Publish the configuration file for Scalar to your Laravel project. This allows you to customize settings related to API reference generation.

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

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

### Retrieve CDN URL

Source: https://github.com/scalar/laravel/blob/main/_autodocs/1_scalar-class.md

Fetches the CDN URL for Scalar assets, typically used in Blade templates.

```php
public static function cdn(): string
```

```php
// Get the CDN URL
$cdnUrl = Scalar::cdn();
// Returns: "https://cdn.jsdelivr.net/npm/@scalar/api-reference"

// In a Blade view:
<script src="{{ Scalar::cdn() }}"></script>
```

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

### Scalar::cdn()

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

Retrieves the CDN URL for Scalar assets.

```APIDOC
## Scalar::cdn()

### Description
Returns the CDN URL used for loading Scalar assets.

### Returns
- **string** - The CDN URL.
```

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

### Configure Rate Limiting

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Limits the number of requests to the Scalar route using the throttle middleware.

```php
// config/scalar.php
'middleware' => ['web', 'throttle:100,1'],
```

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

### Test Authorization Logic

Source: https://github.com/scalar/laravel/blob/main/_autodocs/6_endpoints.md

Verify that the Scalar endpoint correctly respects the viewScalar gate by asserting forbidden responses.

```php
// In tests
Gate::define('viewScalar', fn () => false);
$response = $this->get(config('scalar.path'));
$response->assertForbidden();
```

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

### Adding Analytics

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

Includes Google Analytics tracking scripts within the layout head section.

```blade
<!-- In layout.blade.php head section -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_ID');
</script>
```

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

### Authorization Logic Flow

Source: https://github.com/scalar/laravel/blob/main/_autodocs/2_scalar-controller.md

The logical flow for determining access to the Scalar API reference.

```text
If Gate::check('viewScalar') returns true:
  → Render the view
Else if app environment is 'local':
  → Render the view
Else:
  → Return HTTP 403 Forbidden
```

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

### Create Custom Blade Component

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Define a custom Blade component to wrap the Scalar API reference.

```blade
// resources/views/components/api-docs.blade.php
<div class="api-docs-container">
    <header class="api-header">
        <h1>API Documentation</h1>
    </header>
    
    <div id="app"></div>

    <script src="{{ Scalar::cdn() }}"></script>
    <script>
        Scalar.createApiReference('#app', {!! Scalar::configuration() !!})
    </script>
</div>
```

```blade
<x-api-docs />
```

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

### Scalar Layout Template Structure

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

The base HTML structure for the Scalar interface, extending Laravel's layout system.

```html
<!doctype html>
<html>
<head>
    <title>{{ \Scalar\Scalar::pageTitle() }}</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    {theme CSS}
</head>
<body>
    @yield('content')
</body>
</html>
```

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

### Force Dark Mode State

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Forces the UI to remain in a specific dark mode state, overriding user preferences.

```php
'forceDarkModeState' => 'dark',
```

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

### Enable Dark Mode

Source: https://github.com/scalar/laravel/blob/main/_autodocs/INDEX.md

Toggle the darkMode boolean in the configuration array in config/scalar.php.

```php
'configuration' => [
    'darkMode' => true,
],
```

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

### Protect Routes with Middleware

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Applies authentication or role-based middleware to the Scalar route.

```php
// config/scalar.php
'middleware' => ['web', 'auth'],
```

```php
// config/scalar.php
'middleware' => ['web', 'auth', 'role:admin'],

// And define the 'role' middleware in your application
```

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

### Create Scalar Blade Component

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

Define a reusable Blade component to wrap the Scalar API reference initialization.

```blade
<div class="api-docs">
    <header class="api-header">
        <h1>{{ $title ?? 'API Documentation' }}</h1>
    </header>
    
    <div id="app"></div>

    <script src="{{ \Scalar\Scalar::cdn() }}"></script>

    <script>
       Scalar.createApiReference('#app', {!! \Scalar\Scalar::configuration() !!})
    </script>
</div>
```

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

### Test Route Accessibility

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Ensure the Scalar route returns the expected view and status code.

```php
it('returns scalar view', function () {
    $response = $this->get('/scalar');
    
    $response->assertOk()
        ->assertViewIs('scalar::reference');
});
```

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

### Registering the Scalar Route

Source: https://github.com/scalar/laravel/blob/main/_autodocs/8_routing.md

Registers the primary route for the Scalar API documentation controller.

```php
Route::get('/', ScalarController::class)->name('scalar');
```

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

### Hide HTTP Clients

Source: https://github.com/scalar/laravel/blob/main/_autodocs/5_configuration.md

Excludes specific HTTP client options from the language selector.

```php
'hiddenClients' => [
    // Hide some less common clients
],
```

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

### Test Authorization Gate

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Confirm that the route returns a forbidden status when the authorization gate denies access.

```php
use Illuminate\Support\Facades\Gate;

it('respects authorization gate', function () {
    Gate::define('viewScalar', fn () => false);
    
    $response = $this->get('/scalar');
    
    $response->assertForbidden();
});
```

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

### Adding Custom CSS

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

Injects a custom stylesheet into the head section of the layout.

```blade
<head>
    <title>{{ \Scalar\Scalar::pageTitle() }}</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="{{ asset('css/custom-scalar.css') }}">
</head>
```

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

### Use Scalar facade in Blade templates

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

Accessing facade methods directly within Blade views.

```blade
<!-- Using the global alias -->
<title>{{ Scalar::pageTitle() }}</title>

<script src="{{ Scalar::cdn() }}"></script>

<script>
    Scalar.createApiReference('#app', {!! Scalar::configuration() !!})
</script>
```

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

### Define the Scalar Facade class

Source: https://github.com/scalar/laravel/blob/main/_autodocs/4_scalar-facade.md

The facade class extends Laravel's base Facade and points to the underlying Scalar implementation.

```php
namespace Scalar\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @see \Scalar\Scalar
 */
class Scalar extends Facade
```

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

### ScalarController __invoke Method

Source: https://github.com/scalar/laravel/blob/main/_autodocs/2_scalar-controller.md

The main HTTP handler method for the Scalar route.

```php
public function __invoke()
```

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

### Render Scalar in Blade Templates

Source: https://github.com/scalar/laravel/blob/main/_autodocs/1_scalar-class.md

Use these methods to inject the API reference title, assets, and configuration into your Blade views.

```php
<!-- Set HTML page title -->
<title>{{ Scalar::pageTitle() }}</title>

<!-- Load Scalar assets from CDN -->
<script src="{{ Scalar::cdn() }}"></script>

<!-- Initialize API reference with configuration -->
<script>
  Scalar.createApiReference('#app', {!! Scalar::configuration() !!})
</script>
```

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

### Republish Scalar Views

Source: https://github.com/scalar/laravel/blob/main/_autodocs/10_usage-guide.md

Force update of Scalar views if changes are not reflecting.

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

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

### Use Scalar Blade Component

Source: https://github.com/scalar/laravel/blob/main/_autodocs/7_views.md

Render the custom component in your Blade templates with optional attributes.

```blade
<x-scalar-docs title="My API" />
```
Tokens:
Raw