> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ad-unblock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP

> Script loading for PHP applications with Laravel and Symfony support

Server-side script loading packages for PHP applications, providing secure, cached script loading with framework-specific integrations for Laravel and Symfony.

<Warning>
  Every rendered `<script>` tag **must** include a `data-code` attribute set
  to your Account ID (verification code). AdUnblock uses this value to verify
  that the script is running on your registered domain. Find your Account ID
  at the top of your AdUnblock dashboard.
</Warning>

## Available Frameworks

<CardGroup cols={2}>
  <Card title="Laravel" icon="laravel">
    Blade helper function with built-in caching and auto-discovery
  </Card>

  <Card title="Symfony" icon="symfony">
    Twig extension with dependency injection and bundle structure
  </Card>
</CardGroup>

## Expected Remote Response Format

All PHP packages expect the remote URL to return JSON in this format:

```json theme={null}
["https://example.com/script1.js", "https://example.com/script2.js"]
```

## Laravel Integration

A Laravel package to fetch and render scripts from a remote URL with caching support.

**Repository**: [github.com/adunblock/adunblock-server-tag-laravel](https://github.com/adunblock/adunblock-server-tag-laravel)

### Installation

Install the package via Composer:

```bash theme={null}
composer require adunblock/server-tag-laravel:^1.0
```

The package will be automatically registered via Laravel's package auto-discovery feature.

<Note>
  Version 1.0+ is a stable release and doesn't require lowering `minimum-stability` in your `composer.json`.
</Note>

### Basic Usage

In your Blade template, you can now use the `server_tag` function. Pass your
Account ID (verification code) via the fourth argument:

```php theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>My Page</title>
  {!!
    server_tag(
      'https://public.adunblocker.com/api/vendor_scripts',
      300,
      null,
      ['data-code' => 'YOUR_ACCOUNT_ID']
    )
  !!}
</head>
<body>
  <h1>My Page</h1>
</body>
</html>
```

### With Caching

The second argument is the cache duration in seconds (default: `300`):

```php theme={null}
{!!
  server_tag(
    'https://public.adunblocker.com/api/vendor_scripts',
    600,
    null,
    ['data-code' => 'YOUR_ACCOUNT_ID']
  )
!!}
```

This caches the response for 10 minutes (600 seconds).

### Custom Rendering

You can provide a custom closure to the `render_script` argument to render the script tags in a different way:

```php theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>My Page</title>
  {!!
    server_tag('https://public.adunblocker.com/api/vendor_scripts', 300, function($scripts) {
      $scriptTags = array_map(function ($src) {
        return "<script src=\"{$src}\" defer></script>";
      }, $scripts);
      return implode("\n", $scriptTags);
    })
  !!}
</head>
<body>
  <h1>My Page</h1>
</body>
</html>
```

### Function Signature

```php theme={null}
server_tag(
    string $url,
    int $cache_seconds = 300,
    ?callable $render_script = null,
    ?array $script_attributes = null
): string
```

**Parameters:**

* `$url` (string): The remote URL to fetch scripts from
* `$cache_seconds` (int, optional): Cache duration in seconds. Default is `300`
* `$render_script` (callable, optional): Custom rendering function. Receives an array of script URLs and returns an HTML string
* `$script_attributes` (array, optional): Associative array of attributes applied to every generated `<script>` tag. **Must include `'data-code' => YOUR_ACCOUNT_ID`.** Defaults to `['async' => true]`.

### Laravel Features

* **Blade Helper Function**: Easy-to-use function for templates
* **Built-in Caching**: Automatic caching with configurable TTL
* **Auto-discovery**: Automatic service provider registration
* **Error Handling**: Graceful fallback to empty arrays
* **Security**: XSS protection with proper HTML escaping

### Laravel Requirements

* PHP 7.4 or higher
* Laravel 8/9/10/11/12

## Symfony Integration

A Symfony bundle to fetch and render scripts from a remote URL with Twig integration and caching support.

**Repository**: [github.com/adunblock/adunblock-server-tag-symfony](https://github.com/adunblock/adunblock-server-tag-symfony)

### Installation

Install the bundle via Composer:

```bash theme={null}
composer require adunblock/server-tag-symfony:^1.0
```

<Note>
  Version 1.0+ is a stable release and doesn't require lowering `minimum-stability` in your `composer.json`.
</Note>

Enable the bundle in your `config/bundles.php`:

```php theme={null}
<?php

return [
    // ... other bundles
    AdUnblock\ServerTag\Symfony\AdunblockServerTagBundle::class => ['all' => true],
];
```

### Basic Usage

In your Twig template, you can now use the `server_tag` function:

```twig theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>My Page</title>
  {{ server_tag('https://public.adunblocker.com/api/vendor_scripts') }}
</head>
<body>
  <h1>My Page</h1>
</body>
</html>
```

### With Caching

Add caching to reduce external requests by specifying cache duration in seconds:

```twig theme={null}
{{ server_tag('https://public.adunblocker.com/api/vendor_scripts', 300) }}
```

This caches the response for 5 minutes (300 seconds).

### Custom Rendering

You can provide a custom callable to the `render_script` parameter to customize how script tags are rendered:

```twig theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>My Page</title>
  {{ server_tag('https://public.adunblocker.com/api/vendor_scripts', 300, custom_renderer) }}
</head>
<body>
  <h1>My Page</h1>
</body>
</html>
```

### Function Signature

```php theme={null}
server_tag(string $url, int $cache_seconds = 0, ?callable $render_script = null): string
```

**Parameters:**

* `$url` (string): The remote URL to fetch scripts from
* `$cache_seconds` (int, optional): Cache duration in seconds. Default is 0 (no caching)
* `$render_script` (callable, optional): Custom rendering function. Receives an array of script URLs and returns an HTML string

### Symfony Features

* **Twig Integration**: Easy-to-use Twig function for templates
* **HTTP Client**: Uses Symfony's HTTP client for reliable requests
* **Caching**: Built-in caching support with configurable TTL
* **Error Handling**: Graceful error handling with fallback to empty arrays
* **Security**: XSS protection with proper HTML escaping
* **Bundle Structure**: Proper Symfony bundle with dependency injection

### Symfony Requirements

* PHP 7.4 or higher
* Symfony 5.0, 6.0, 7.0, or 8.0
* Twig 2.0 or 3.0

## Common Features

All PHP packages provide:

* ✅ **Remote Script Fetching**: Fetch JavaScript files from external URLs
* ✅ **Caching Support**: Built-in caching with configurable TTL
* ✅ **Error Handling**: Graceful fallback when remote URLs are unavailable
* ✅ **Security**: XSS protection with proper HTML escaping
* ✅ **Custom Rendering**: Support for custom script tag rendering

## Security Considerations

* **URL Validation**: Only HTTP and HTTPS URLs are allowed
* **XSS Protection**: All output is properly escaped
* **Error Handling**: Failed requests don't break page rendering
* **Caching**: Reduces load on remote servers

## Performance Tips

1. **Use Caching**: Configure appropriate cache intervals for your use case
2. **Error Handling**: Implement proper fallbacks for failed requests
3. **CDN Usage**: Use CDN URLs for better performance
4. **Cache Warming**: Pre-warm caches during deployment
