### MetaData Configuration Example

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

Example of configuring the 'metaData' array, specifically setting the page title for the API documentation header.

```php
'metaData' => [
    'title' => 'My Company API Documentation',
]
```

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

### Environment-Based and Custom Authorization Example

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

An example demonstrating how to combine environment checks with custom user-based authorization for the Scalar endpoint.

```php
Gate::define('viewScalar', function ($user = null) {
    // Allow authenticated users in development
    if (app()->environment('local')) {
        return true;
    }
    
    // Allow specific team members in production
    return $user && $user->team_id === config('scalar.allowed_team_id');
});
```

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

### Server Configuration Example

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

Example demonstrating how to configure the 'servers' array, providing a list of API server URLs and their corresponding descriptions. This is used to define available servers for the API reference.

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

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

### Complete Scalar Configuration Example

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

A comprehensive example of the Scalar configuration array, demonstrating various settings for domain, path, middleware, CDN, and detailed API reference configurations.

```php
<?php

return [
    'domain' => null,
    'path' => '/scalar',
    'middleware' => ['web'],
    'url' => '/openapi.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' => config('app.name').' API Reference',
        ],
        'favicon' => '/favicon.svg',
        'hiddenClients' => [],
        'defaultHttpClient' => [
            'targetId' => 'shell',
            'clientKey' => 'curl',
        ],
        'withDefaultFonts' => true,
        'defaultOpenAllTags' => false,
    ],
];
```

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

### DefaultHttpClient Configuration Example

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

Example of setting the 'defaultHttpClient' configuration, specifying the target client category and its specific identifier. This determines the default HTTP client shown in the API reference.

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

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

### HiddenClients Configuration Example

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

Example of configuring the 'hiddenClients' array to specify which HTTP snippet clients should be hidden from the client menu in the API reference.

```php
'hiddenClients' => ['unirest', 'wget']
```

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

### Facade Reference

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

Documentation for the static facade, including basic usage, available methods, and real-world examples.

```APIDOC
## Facade Reference

### Overview
Provides static access to the `Scalar` class methods, simplifying their usage.

### Basic Usage
```php
use ScalarFacade;

$title = ScalarFacade::pageTitle();
```

### Available Methods
- `pageTitle()`
- `url()`
- `cdn()`
- `configuration()`

### Testing Patterns
Includes guidance on how to test facade interactions.
```

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

### Configuring Scalar Route Middleware

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

Example of applying middleware to the Scalar route in the `config/scalar.php` file.

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

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

### Real-World Example: Blade View

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Facade.md

Demonstrates a practical implementation of the Scalar facade within a Blade view for rendering an API reference component.

```blade
@extends('layouts.app')

@section('content')
    <div id="api-reference"></div>
    
    <script src="{{ Scalar::cdn() }}"></script>
    <script>
        Scalar.createApiReference('#api-reference', {!! Scalar::configuration() !!})
    </script>
@endsection
```

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

### Basic GET Request to Scalar Endpoint

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

Use this command to make a basic GET request to the default Scalar API documentation endpoint.

```bash
curl -X GET http://localhost:8000/scalar
```

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

### Real-World Example: Service Provider

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Facade.md

Illustrates using the Scalar facade within a Laravel service provider to dynamically set configuration or retrieve configuration values during application bootstrapping.

```php
use Scalar\Facades\Scalar;

public function boot()
{
    // Dynamically set configuration based on environment
    config(['scalar.url' => $this->getOpenApiUrl()]);
    
    // Retrieve configuration
    $config = Scalar::configuration();
}
```

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

### 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
```

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

### Real-World Example: Controller

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Facade.md

Shows how to use the Scalar facade within a Laravel controller to retrieve data for rendering a view, such as the page title and OpenAPI URL.

```php
use Scalar\Facades\Scalar;

class ApiDocumentationController extends Controller
{
    public function show()
    {
        return view('documentation', [
            'title' => Scalar::pageTitle(),
            'openApiUrl' => Scalar::url(),
        ]);
    }
}
```

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

### GET /scalar

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

Handles GET requests to the API reference endpoint. It checks authorization and renders the API reference view.

```APIDOC
## GET /scalar

### Description
Handles GET requests to the API reference endpoint. It checks authorization (unless in a local environment) and renders the `scalar::reference` view.

### Method
GET

### Endpoint
/scalar

### Behavior
- Checks `viewScalar` gate (unless in local environment).
- Returns 403 Forbidden if authorization fails.
- Renders `scalar::reference` view on success.

### Configuration
- Path: `config('scalar.path')` (default: `/scalar`)
- Domain: `config('scalar.domain')` (default: `null`)
- Middleware: `config('scalar.middleware')` (default: `['web']`)
```

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

### Configuring Scalar Endpoint Path

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

Example of configuring the HTTP endpoint path for Scalar in the `config/scalar.php` file.

```php
// config/scalar.php
'path' => '/scalar',
```

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

### Configuring Scalar Endpoint Domain

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

Example of configuring a specific domain for the Scalar endpoint in the `config/scalar.php` file.

```php
// config/scalar.php
'domain' => 'api',
```

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

### Scalar Configuration Structure

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

An example of the complete configuration object passed to the Scalar JavaScript library. It includes theme, layout, and various display options.

```php
[
    'theme' => string,
    'layout' => string,
    'url' => string,
    '_integration' => 'laravel',
    'proxyUrl' => string,
    'showSidebar' => boolean,
    'hideModels' => boolean,
    'hideDownloadButton' => boolean,
    'hideTestRequestButton' => boolean,
    'hideSearch' => boolean,
    'darkMode' => boolean,
    'forceDarkModeState' => string,
    'hideDarkModeToggle' => boolean,
    'searchHotKey' => string,
    'metaData' => array,
    'favicon' => string,
    'hiddenClients' => array,
    'defaultHttpClient' => array,
    'withDefaultFonts' => boolean,
    'defaultOpenAllTags' => boolean,
    // ... additional optional keys
]
```

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

### Facade Registration in composer.json

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Facade.md

Example of how the Scalar facade is registered as a service container alias within the `composer.json` file's `extra.laravel.aliases` configuration.

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

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

### Configuration Customization

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

Provides an example of how to customize the Scalar package's configuration by creating or modifying the `config/scalar.php` file. This snippet illustrates setting the API URL, documentation path, middleware, and UI theme.

```php
// config/scalar.php
return [
    'url' => '/api/openapi.json',
    'path' => '/docs/api',
    'middleware' => ['web', 'auth'],
    'configuration' => [
        'theme' => 'bluePlanet',
        'metaData' => [
            'title' => 'My Company API Documentation',
        ],
    ],
];
```

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

### Testing Facade Method Return Types

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Facade.md

Provides examples of how to test the Scalar facade in Laravel, specifically asserting the return types of methods like `pageTitle()` and `url()`.

```php
use Scalar\Facades\Scalar;

public function test_facade_returns_page_title()
{
    $title = Scalar::pageTitle();
    $this->assertIsString($title);
}

public function test_facade_returns_url()
{
    $url = Scalar::url();
    $this->assertStringStartsWith('http', $url);
}
```

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

### GET /scalar Endpoint

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

Documentation for the main HTTP endpoint that serves the API reference documentation.

```APIDOC
## GET /scalar

### Description
Serves the Scalar API reference documentation to the browser.

### Method
GET

### Endpoint
`/scalar`

### Parameters
No specific path or query parameters are required for this endpoint.

### Request Body
Not applicable.

### Response
#### Success Response (200 OK)
- **Content-Type**: `text/html`
- **Body**: HTML structure containing the API reference documentation, including JavaScript for initialization.

#### Forbidden Response (403 Forbidden)
- **Trigger Conditions**: Authorization checks fail.
- **When it occurs**: When the user is not authorized to view the API reference.

### Route Configuration
- **Path**: Customizable via `config/scalar.php` (`path` key).
- **Domain**: Customizable via `config/scalar.php` (`domain` key).
- **Middleware**: Customizable via `config/scalar.php` (`middleware` key).
```

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

### Laravel Package Service Provider Configuration

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

Example `composer.json` configuration for registering the Scalar Laravel package's service provider and facade. This is typically handled automatically by Composer's autoload discovery.

```json
{
    "extra": {
        "laravel": {
            "providers": ["Scalar\\ScalarServiceProvider"],
            "aliases": {"Scalar": "Scalar\\Facades\\Scalar"}
        }
    }
}
```

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

### Custom Authorization Gate for Scalar

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

Example of overriding the default authorization gate in `AppServiceProvider` to implement custom access logic for the Scalar endpoint.

```php
// app/Providers/AppServiceProvider.php

use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::define('viewScalar', function ($user = null) {
        // Only authenticated users with admin role
        return $user?->hasRole('admin') ?? false;
    });
}
```

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

### Facade Access to Scalar Methods

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

Use the Scalar facade for convenient static access to package methods like getting page titles, URLs, and configuration.

```php
use Scalar\Facades\Scalar;

// Get page title
$title = Scalar::pageTitle();

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

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

// Get complete configuration as Collection
$config = Scalar::configuration();
```

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

### Default Scalar Authorization Gate

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

Example of the default authorization gate definition for Scalar, which allows all access.

```php
Gate::define('viewScalar', function ($user = null) {
    return true;
});
```

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

### Customize Scalar Authorization Gate

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/ScalarController.md

Example of how to customize the 'viewScalar' gate in App\Providers\AppServiceProvider. This allows for fine-grained control over who can access the Scalar API reference.

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

public function boot(): void
{
    Gate::define('viewScalar', function ($user = null) {
        // Allow only authenticated users with 'admin' role
        return $user?->hasRole('admin') ?? false;
    });
}
```

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

### Scalar API Reference HTML Response

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

This is an example of the HTML response generated by the Scalar endpoint, including the Scalar library and initialization script.

```html
<!doctype html>
<html>
<head>
    <title>My App API Reference</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <!-- Theme styles if using Laravel theme -->
</head>
<body>
    <div id="app"></div>

    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>

    <script>
       Scalar.createApiReference('#app', {
           "theme":"laravel",
           "url":"https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json",
           "_integration":"laravel",
           "layout":"modern",
           "showSidebar":true,
           ...
       })
    </script>
</body>
</html>
```

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

### Configure Search Shortcut

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

The `searchHotKey` option defines the keyboard shortcut to open the search modal. Use with CTRL/CMD. Examples include 'k' for CMD+k/CTRL+k or '/' for CMD+/ /CTRL+/.

```php
'configuration' => [
    'searchHotKey' => 'k',  // CMD+k or CTRL+k opens search
    'searchHotKey' => '/',  // CMD+/ or CTRL+/ opens search
]
```

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

### Get Scalar String Primitives

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

Retrieve the page title, OpenAPI document URL, or CDN URL for Scalar assets. These methods return simple string values.

```php
use Scalar\Facades\Scalar;

$title = Scalar::pageTitle();  // "My App API Reference"
$openApiUrl = Scalar::url();   // "https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json"
$cdnUrl = Scalar::cdn();       // "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
```

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

### Get API Reference Page Title

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Retrieves the page title for the API reference documentation. It fetches the title from the `scalar.configuration.metaData.title` configuration or defaults to the application name followed by 'API Reference'.

```php
use Scalar\Facades\Scalar;

$title = Scalar::pageTitle();
// Returns: "My App API Reference" or value from config('scalar.configuration.metaData.title')
```

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

### Custom Authorization Gate Logic

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

Implement custom authorization logic for the 'viewScalar' gate in `App\Providers\AppServiceProvider`. This example restricts access to authenticated admin users in production environments.

```php
// app/Providers/AppServiceProvider.php
Gate::define('viewScalar', function ($user = null) {
    // Only authenticated admin users in production
    return app()->environment('local') || $user?->isAdmin() ?? false;
});
```

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

### Register Scalar API Reference Route

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/ScalarController.md

Defines a GET route for the Scalar API reference endpoint. Access this route in your browser to view the API documentation.

```php
use Illuminate\Support\Facades\Route;
use Scalar\Controllers\ScalarController;

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

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

### Change Scalar Theme in Configuration

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

Update the Scalar theme by modifying the 'theme' key within the 'configuration' array in your `config/scalar.php` file. This example sets the theme to 'bluePlanet'.

```php
// config/scalar.php
'configuration' => [
    'theme' => 'bluePlanet',
]
```

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

### Get Scalar Assets CDN URL

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Retrieves the URL for the CDN hosting Scalar's API reference assets. The default URL is `https://cdn.jsdelivr.net/npm/@scalar/api-reference`.

```php
use Scalar\Facades\Scalar;

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

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

### GET /scalar

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

Renders the Scalar API reference page. This endpoint serves an HTML page that includes the Scalar JavaScript library and configuration to display your API documentation.

```APIDOC
## GET /scalar

### Description
Renders the Scalar API reference page. This endpoint serves an HTML page that includes the Scalar JavaScript library and configuration to display your API documentation.

### Method
GET

### Endpoint
/scalar (configurable via `config('scalar.path')`)

### Parameters
#### Query Parameters
No query or body parameters are accepted.

### Request Headers
Standard HTTP headers are accepted. No special headers are required.

### Response
#### Success Response (200 OK)
- **Content-Type**: `text/html; charset=UTF-8`
- **Body**: HTML page containing the Scalar API reference layout, JavaScript library, and configuration data.

### Response Example
```html
<!doctype html>
<html>
<head>
    <title>My App API Reference</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <!-- Theme styles if using Laravel theme -->
</head>
<body>
    <div id="app"></div>

    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>

    <script>
       Scalar.createApiReference('#app', {
           "theme":"laravel",
           "url":"https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json",
           "_integration":"laravel",
           "layout":"modern",
           "showSidebar":true,
           ...
       })
    </script>
</body>
</html>
```

### Forbidden Response (403 Forbidden)
- **Condition**: Authorization gate `viewScalar` returns `false` in non-local environments.
- **Content**: Standard Laravel 403 error page.
```

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

### Configure Package Assets and Routes

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/ScalarServiceProvider.md

The `configurePackage` method sets up the package's name, configuration file, views, and routes. This method is automatically called during the service provider's registration phase.

```php
protected function configurePackage(Package $package): void
{
    $package
        ->name('scalar')
        ->hasConfigFile()
        ->hasViews('scalar')
        ->hasRoute('web');
}
```

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

### ScalarServiceProvider Methods

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

Reference for the `ScalarServiceProvider` class, detailing its `boot` and `configurePackage` methods for package initialization and configuration.

```APIDOC
## ScalarServiceProvider Reference

### Overview
Manages the bootstrapping and configuration of the Scalar package within the Laravel application.

### Methods
#### `boot()`
- **Description**: Initializes the package, including defining authorization gates.
- **Lifecycle**: Part of the Laravel service provider boot process.

#### `configurePackage()`
- **Description**: Configures the package's structure and settings.
- **Lifecycle**: Called during the service provider's registration phase.
```

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

### Using Scalar Class Methods

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

Demonstrates how to access static methods of the Scalar class for retrieving configuration details like page title and the complete configuration object.

```php
use Scalar\Scalar;
// or
use Scalar\Facades\Scalar;

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

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

### Basic PHP Usage

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

Demonstrates how to retrieve the page title and configuration collection using the Scalar facade. This is useful for accessing package information within your PHP code.

```php
use Scalar\Facades\Scalar;

// Get page title
$title = Scalar::pageTitle();

// Get configuration as a Collection
$config = Scalar::configuration();

// Use in a view
echo Scalar::pageTitle();
```

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

### Apply a Different Theme

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

Set the 'theme' configuration option in `config/scalar.php` to apply a different visual theme to the API documentation. Available themes include 'bluePlanet', 'deepSpace', and 'mars'.

```php
'configuration' => [
    'theme' => 'bluePlanet',  // or 'deepSpace', 'mars', etc.
],
```

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

### configuration()

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Returns the complete configuration object as a Laravel collection, formatted for use with the Scalar API Reference JavaScript library. It merges all configuration options and handles theme settings.

```APIDOC
## configuration()

### Description
Returns the complete configuration object as a Laravel collection, formatted for use with the Scalar API Reference JavaScript library. This method merges all configuration options and handles theme settings.

### Method
`static`

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

### Returns
`Collection` - A Laravel collection containing the merged configuration with `_integration`, `theme`, and `url` keys

### Behavior
- If the configured theme is `'laravel'`, the theme is set to `'none'` to prevent theme double-application
- The `_integration` key is set to `'laravel'` to identify the package integration
- The `url` from `scalar.url` configuration is merged in
- All configuration from `scalar.configuration` is included

### Example
```php
use Scalar\Facades\Scalar;

$config = Scalar::configuration();
// Returns a Collection with keys:
// - theme: 'none' or configured theme
// - url: OpenAPI document URL
// - _integration: 'laravel'
// - layout: 'modern'
// - showSidebar: true
// - darkMode: false
// ... (all configuration options from config/scalar.php)

// Use in a Blade view:
// Scalar.createApiReference('#app', {!! Scalar::configuration() !!})
```
```

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

### Custom Authorization Gate Definition

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

Example of defining a custom authorization gate in Laravel's AppServiceProvider to control access to the Scalar endpoint.

```php
// In app/Providers/AppServiceProvider.php
Gate::define('viewScalar', function ($user = null) {
    return false;  // This would result in a 403 response
});
```

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

### Set Initial Dark Mode State

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

The `darkMode` option determines the initial appearance of the documentation. Set to `true` for dark mode, `false` for light mode. Defaults to `false`.

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

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

### Basic Facade Access

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Facade.md

Demonstrates how to access Scalar class methods using the Scalar facade. This is the recommended approach for most use cases within a Laravel application.

```php
use Scalar\Facades\Scalar;

// Access Scalar methods via the facade
$title = Scalar::pageTitle();
$url = Scalar::url();
$cdn = Scalar::cdn();
$config = Scalar::configuration();
```

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

### Direct Class Access

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Facade.md

Shows how to use the Scalar class directly by importing it. This approach is an alternative to using the facade.

```php
use Scalar\Scalar;

$title = Scalar::pageTitle();
```

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

### Get OpenAPI Document URL

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Retrieves the URL of the OpenAPI/Swagger document used by Scalar to generate the API reference. This value is sourced from the `scalar.url` configuration.

```php
use Scalar\Facades\Scalar;

$openApiUrl = Scalar::url();
// Returns: "https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json" or custom URL
```

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

### Define Authorization Gate

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

Define the 'viewScalar' authorization gate in your service provider to control access to the Scalar endpoint. This example shows a basic definition that can be customized.

```php
Gate::define('viewScalar', function ($user = null) {
    return true; // Allow/deny access
});
```

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

### Define Custom Authorization Gate

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

Customize access control for the Scalar endpoint by defining a custom authorization gate. This example allows access if the user is an admin.

```php
Gate::define('viewScalar', function ($user = null) {
    return $user?->hasRole('admin') ?? false;
});
```

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

### Publish Scalar Package Assets

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/ScalarServiceProvider.md

Users can publish the package's configuration file and views using Artisan commands. The `--tag` option specifies which assets to publish.

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

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

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

### Using Scalar Configuration Collection

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

Demonstrates how to retrieve the Scalar configuration as a Laravel Collection and access its values using array-like or Collection methods. This is typically done by calling Scalar::configuration().

```php
use Scalar\Facades\Scalar;

$config = Scalar::configuration();  // \Illuminate\Support\Collection

// Access values like an array
$theme = $config['theme'];

// or use Collection methods
$config->all();       // Get all items as array
$config->toJson();    // Convert to JSON
$config->keys();      // Get all keys
$config->merge([...]) // Merge additional items
```

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

### Access Scalar Class via Facade

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Demonstrates how to access the static methods of the Scalar class using its Facade, `Scalar\Facades\Scalar`. This provides a convenient shorthand for calling methods like `pageTitle()` and `configuration()`.

```php
use Scalar\Facades\Scalar;

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

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

### 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
```

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

### Securing the Scalar Endpoint with Middleware

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

Illustrates how to apply authentication middleware to the Scalar endpoint by configuring the `middleware` key in `config/scalar.php`. Unauthenticated requests will be redirected, while authenticated requests will display the API reference.

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

```bash
# Without authentication - redirects to login
curl -X GET http://localhost:8000/scalar
# Returns: 302 redirect to login page
```

```bash
# With authentication
curl -X GET http://localhost:8000/scalar \
  -H "Cookie: XSRF-TOKEN=...; laravel_session=..."
# Returns: 200 with API reference
```

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

### Customize Authorization Gate

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

Restrict access to the Scalar endpoint by overriding the `viewScalar` gate in your application's service provider. This example allows access for authenticated admin users in production.

```php
// app/Providers/AppServiceProvider.php

use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::define('viewScalar', function ($user = null) {
        // Only allow authenticated admin users in production
        return app()->environment('local') || $user?->isAdmin() ?? false;
    });
}
```

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

### Scalar Facade Alias Equivalence

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

Demonstrates that the Scalar facade can be called directly or using its fully qualified namespace. Both methods achieve the same result.

```php
// These are equivalent:
Scalar::pageTitle();
\Scalar\Scalar::pageTitle();
```

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

### Configuring a Custom Path for the Scalar Endpoint

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

Shows how to define a custom URL path for the Scalar API documentation in the `config/scalar.php` configuration file. Access the endpoint using the specified custom path.

```php
// config/scalar.php
'path' => '/docs/api'
```

```bash
GET http://example.com/docs/api
```

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

### Access Scalar Class Directly

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Shows the equivalent of using the Facade by calling static methods directly on the `Scalar` class. This approach requires importing the `Scalar` class directly.

```php
use Scalar\Scalar;

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

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

### Define Default Authorization Gate

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/ScalarServiceProvider.md

The `boot` method defines a default authorization gate named 'viewScalar'. This gate, by default, always returns true, allowing access to the API reference. It can be overridden in `App\Providers\AppServiceProvider` for custom access control.

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

    // Default behavior - always allows access
    Gate::define('viewScalar', function ($user = null) {
        return true;
    });
}
```

```php
// Override in app/Providers/AppServiceProvider.php
public function boot(): void
{
    Gate::define('viewScalar', function ($user = null) {
        return $user?->hasRole('admin') ?? false;
    });
}
```

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

### Directory Structure

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

This is the directory structure for the Scalar for Laravel package documentation.

```text
output/
├── README.md                    # This file
├── index.md                     # Start here - package overview
├── API_SUMMARY.md               # Quick reference table
├── configuration.md             # All config options
├── endpoints.md                 # HTTP routes
├── types.md                     # Data structures
└── api-reference/               # Individual component docs
    ├── Scalar.md                # Main class
    ├── ScalarController.md      # Request handler
    ├── ScalarServiceProvider.md # Service provider
    └── Facade.md                # Static facade
```

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

### Using Scalar Facade in Blade Templates

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Facade.md

Illustrates how to integrate the Scalar facade into Blade views for dynamic content rendering, such as setting the page title, including CDN assets, and initializing Scalar with configuration.

```blade
<!DOCTYPE html>
<html>
<head>
    <title>{{ Scalar::pageTitle() }}</title>
</head>
<body>
    <div id="app"></div>
    <script src="{{ Scalar::cdn() }}"></script>
    <script>
        Scalar.createApiReference('#app', {!! Scalar::configuration() !!})
    </script>
</body>
</html>
```

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

### Configure Scalar Theme

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

Apply a color theme to the Scalar API reference. Choose from built-in themes or disable for custom CSS.

```php
'theme' => 'laravel',     // Laravel theme
'theme' => 'bluePlanet',  // Blue Planet theme
'theme' => 'darkSpace',   // Deep Space theme
'theme' => 'none',        // No theme (custom CSS only)
```

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

### Access Scalar Configuration

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

Retrieve the package configuration using the Scalar facade. This is useful for dynamically accessing settings within your application.

```php
use Scalar\Facades\Scalar;

$config = Scalar::configuration();
```

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

### Configure Scalar CDN

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

Set the URL for the CDN hosting Scalar's API reference assets like JavaScript and CSS.

```php
'cdn' => 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',  // jsDelivr CDN (default)
'cdn' => 'https://unpkg.com/@scalar/api-reference',             // unpkg CDN
'cdn' => 'https://cdn.example.com/scalar',                      // Custom CDN
```

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

### Configure Scalar Middleware

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

Apply custom middleware to Scalar routes for authentication, logging, or rate limiting.

```php
'middleware' => ['web'],                        // Default
'middleware' => ['web', 'auth'],                // Require authentication
'middleware' => ['web', 'auth:admin'],          // Require admin authentication
'middleware' => ['web', 'throttle:60,1'],       // Rate limit
```

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

### Configure Scalar Layout

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

Set the layout type for the API reference. The 'modern' layout provides a side-by-side view.

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

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

### Define Theme Type

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

Defines the possible string values for the theme configuration. Note that the 'laravel' theme is specially handled and converted to 'none'.

```typescript
type Theme = 'alternate'
           | 'bluePlanet'
           | 'deepSpace'
           | 'default'
           | 'kepler'
           | 'laravel'
           | 'mars'
           | 'moon'
           | 'purple'
           | 'saturn'
           | 'solarized'
           | 'none';
```

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

### cdn()

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Returns the URL to the CDN where Scalar's API reference assets are hosted. It defaults to the official Scalar CDN.

```APIDOC
## cdn()

### Description
Returns the URL to the CDN where Scalar's API reference assets are hosted.

### Method
`static`

### Signature
`public static function cdn(): string`

### Returns
`string` - The CDN URL for Scalar assets, defaults to `https://cdn.jsdelivr.net/npm/@scalar/api-reference`

### Example
```php
use Scalar\Facades\Scalar;

$cdnUrl = Scalar::cdn();
// Returns: "https://cdn.jsdelivr.net/npm/@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"
```

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

### Set Favicon Path

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

Specify the path to your favicon image file using the `favicon` option. This allows customization of the browser tab icon.

```php
'configuration' => [
    'favicon' => '/favicon.svg',
    'favicon' => '/images/logo.png',
]
```

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

### Define Layout Type

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

Defines the possible string values for the layout configuration. Currently, only 'modern' is supported.

```typescript
type Layout = 'modern';
```

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

### Hide Download Button

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

Set `hideDownloadButton` to `true` to remove the "Download OpenAPI Document" button from the interface. Defaults to `false`.

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

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

### Configure OpenAPI/Swagger URL

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

Specify the URL for the OpenAPI/Swagger document Scalar uses. Supports local or remote URLs.

```php
'url' => 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json', // Default sample
'url' => '/openapi.yaml',                                                 // Local YAML
'url' => '/api/openapi.json',                                             // Local JSON endpoint
'url' => 'https://api.example.com/openapi.json',                          // Remote URL
```

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

### Set API Base Server URL

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

Configure the base URL for API servers when using server-side rendering. For client-side rendering, this is automatically derived from `window.location.origin`.

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

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

### url()

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Returns the URL to the OpenAPI/Swagger document that Scalar will use to generate the API reference. This is fetched from the `scalar.url` configuration.

```APIDOC
## url()

### Description
Returns the URL to the OpenAPI/Swagger document that Scalar will use to generate the API reference.

### Method
`static`

### Signature
`public static function url(): string`

### Returns
`string` - The OpenAPI document URL from `scalar.url` configuration

### Example
```php
use Scalar\Facades\Scalar;

$openApiUrl = Scalar::url();
// Returns: "https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json" or custom URL
```
```

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

### 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',

    // …
]
```

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

### Generate Scalar API Reference Configuration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Generates the complete configuration object for the Scalar API Reference JavaScript library. This method merges various configuration settings, including theme, URL, and integration details, returning a Laravel collection.

```php
use Scalar\Facades\Scalar;

$config = Scalar::configuration();
// Returns a Collection with keys:
// - theme: 'none' or configured theme
// - url: OpenAPI document URL
// - _integration: 'laravel'
// - layout: 'modern'
// - showSidebar: true
// - darkMode: false
// ... (all configuration options from config/scalar.php)

// Use in a Blade view:
// Scalar.createApiReference('#app', {!! Scalar::configuration() !!})
```

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

### Set Default HTTP Client

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

The `defaultHttpClient` option configures which HTTP client is selected by default. Specify `targetId` (e.g., 'shell') and `clientKey` (e.g., 'curl').

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

```php
'configuration' => [
    'defaultHttpClient' => [
        'targetId' => 'javascript',
        'clientKey' => 'fetch',
    ]
]
```

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

### Configure Scalar Proxy URL

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

Specify a URL for a request proxy to handle API client requests from the browser, avoiding CORS issues.

```php
'proxyUrl' => 'https://proxy.scalar.com'
```

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

### 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"
```

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

### Control Sidebar Visibility

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

Use `showSidebar` to toggle the visibility of the sidebar in the API reference. Set to `true` to show, or `false` to hide.

```php
'configuration' => [
    'showSidebar' => true,   // Show sidebar
    'showSidebar' => false,  // Hide sidebar
]
```

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

### pageTitle()

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/Scalar.md

Returns the page title for the API reference documentation. It retrieves the title from the `scalar.configuration.metaData.title` configuration or falls back to the application name.

```APIDOC
## pageTitle()

### Description
Returns the page title for the API reference documentation.

### Method
`static`

### Signature
`public static function pageTitle(): string`

### Returns
`string` - The page title, retrieved from `scalar.configuration.metaData.title` config or falls back to `{app.name} API Reference`

### Example
```php
use Scalar\Facades\Scalar;

$title = Scalar::pageTitle();
// Returns: "My App API Reference" or value from config('scalar.configuration.metaData.title')
```
```

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

### Composer Package Registration

Source: https://github.com/scalar/laravel/blob/main/_autodocs/api-reference/ScalarServiceProvider.md

The ScalarServiceProvider is automatically registered by Laravel through the `extra.laravel.providers` configuration in the `composer.json` file.

```json
{
    "extra": {
        "laravel": {
            "providers": [
                "Scalar\\ScalarServiceProvider"
            ]
        }
    }
}
```

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

### Inject Custom CSS

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

The `customCss` option allows you to inject custom CSS rules into the documentation page. Provide your CSS as a string.

```php
'configuration' => [
    'customCss' => '.sidebar { background: #f0f0f0; }',
]
```

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

### Configure Scalar Domain

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

Set the subdomain for Scalar accessibility. If null, Scalar uses the application's main domain.

```php
'domain' => 'api', // Scalar accessible at api.example.com/scalar
'domain' => null,  // Scalar accessible at example.com/scalar
```

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

### Change OpenAPI Document Source

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

Update the 'url' configuration to point to either a local endpoint or a remote URL for the OpenAPI JSON document.

```php
'url' => '/api/openapi.json',  // Local endpoint
```

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

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

### Override OpenAPI Servers

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

Provide custom server entries to override those defined in the OpenAPI specification. This is useful for directing requests to different environments like production or staging.

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

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

### Scalar Class Methods

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

Reference for the main `Scalar` class, including methods for retrieving page titles, OpenAPI URLs, CDN URLs, and configuration.

```APIDOC
## Scalar Class Reference

### Class Overview
Provides core functionality for generating API documentation.

### Methods
#### `pageTitle()`
- **Description**: Get page title from configuration.
- **Signature**: `pageTitle(): string`

#### `url()`
- **Description**: Get OpenAPI document URL.
- **Signature**: `url(): string`

#### `cdn()`
- **Description**: Get CDN URL for assets.
- **Signature**: `cdn(): string`

#### `configuration()`
- **Description**: Get complete configuration object.
- **Signature**: `configuration(): array`

### Access Via Facade
Provides convenient static access to the `Scalar` class methods.
```

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

### Customize Authorization Gate with Environment Check

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

Modify the 'viewScalar' authorization gate to allow access in local environments or if the user has an 'isAdmin' role. This provides conditional access control.

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

Gate::define('viewScalar', function ($user = null) {
    return app()->environment('local') || $user?->isAdmin();
});
```

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

### ScalarController Invoke Method

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

Reference for the `ScalarController`'s `__invoke` method, which handles HTTP requests for the API reference.

```APIDOC
## ScalarController `__invoke` Method

### Description
Handles HTTP requests to the API reference, performing authorization checks and returning either a View or a 403 Forbidden response.

### Method
`__invoke(Request $request)`

### Authorization
Performs authorization checks based on configuration.

### Response Types
- **View**: Returns the API reference view on successful authorization.
- **403 Forbidden**: Returned when authorization fails.
```