---
title: "Configuration — Advertisements for Laravel | Roundly"
description: "Every config key with its default and env variable — models, author key type, currency, locale, slug history, tracking, creatives and geo."
url: https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/configuration
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Advertisements for Laravel](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel.md)

# Configuration

The package works with zero configuration. The published config/advertisements.php, without its comment headers:

```php
return [
    // Eloquent models the package resolves — override with your own subclasses.
    'model' => RoundlyConsulting\Advertisements\Models\Advertisement::class,

    // Key type of the polymorphic author column: 'bigint', 'uuid' or 'ulid'.
    'key_type' => env('ADVERTISEMENTS_KEY_TYPE', 'bigint'),

    'placement_model' => RoundlyConsulting\Advertisements\Models\Placement::class,
    'category_model' => RoundlyConsulting\Advertisements\Models\Category::class,
    'event_model' => RoundlyConsulting\Advertisements\Models\AdvertisementEvent::class,

    // Impression / click recording — inline, or buffered to the queue.
    'tracking' => [
        'buffered' => env('ADVERTISEMENTS_TRACKING_BUFFERED', false),
        'queue' => env('ADVERTISEMENTS_TRACKING_QUEUE'),
        'connection' => env('ADVERTISEMENTS_TRACKING_CONNECTION'),
    ],

    // Locale used when the active locale has no translation for an attribute.
    'fallback_locale' => env('ADVERTISEMENTS_FALLBACK_LOCALE', config('app.fallback_locale', 'en')),

    // Slugs (sluggable): keep retired advertisement slugs and 301 them to the current one.
    'slugs' => [
        'history' => env('ADVERTISEMENTS_SLUG_HISTORY', false),
    ],

    // Currency used by AdvertisementData::fromMinor() / ::fromDecimal() when none is given.
    'default_currency' => env('ADVERTISEMENTS_CURRENCY', 'EUR'),

    // Register the global Advertisements facade alias.
    'register_facade_alias' => env('ADVERTISEMENTS_FACADE_ALIAS', true),

    // Visual creatives (media-library): one single-file bucket per placement named
    // "{creative_bucket_prefix}:{placement-slug}" plus a generic "{fallback_bucket}".
    'media' => [
        'creative_bucket_prefix' => 'creative',
        'fallback_bucket' => 'creative',
        'disk' => env('ADVERTISEMENTS_MEDIA_DISK'), // null = media-library default
        'responsive_widths' => null,                // null = media-library default ladder
        'display_variant' => 'display',
        'use_fallback_bucket' => true,
        'text_ad_view' => 'advertisements::text-ad',
    ],

    // Geo-targeting & geo reporting (geolocation).
    'geo' => [
        'targeting_enabled' => env('ADVERTISEMENTS_GEO_TARGETING', true),
        'untargeted_match' => true,                 // ads with no targeting match every viewer
        'match_when_unknown' => 'untargeted_only',  // unknown viewer / unknown fact: 'untargeted_only' | 'all'
        'stamp_events' => env('ADVERTISEMENTS_GEO_STAMP', true),
    ],
];
```

## Every key

| Key | Default | Env | Purpose |
| --- | --- | --- | --- |
| `model` | Advertisement::class | — | The advertisement model: the packaged class or a subclass of it — anything else throws InvalidConfigurationException. |
| `key_type` | bigint | ADVERTISEMENTS\_KEY\_TYPE | Key type of the polymorphic author column: bigint, uuid or ulid (anything else throws InvalidConfigurationException). Read at migrate time; every author model must share it. |
| `placement_model` | Placement::class | — | The placement (zone) model. |
| `category_model` | Category::class | — | The category model. |
| `event_model` | AdvertisementEvent::class | — | The impression/click event model. |
| `tracking.buffered` | false | ADVERTISEMENTS\_TRACKING\_BUFFERED | Dispatch recording to the queue instead of writing inline. |
| `tracking.queue` | null | ADVERTISEMENTS\_TRACKING\_QUEUE | Queue for buffered recording (null or blank = default). |
| `tracking.connection` | null | ADVERTISEMENTS\_TRACKING\_CONNECTION | Queue connection for buffered recording (null or blank = default). |
| `fallback_locale` | app.fallback\_locale | ADVERTISEMENTS\_FALLBACK\_LOCALE | Translation fallback, slug-binding fallback and the locale placement/category slugs are generated from. Not set (null or blank) means no translation fallback, and slugs use en. |
| `slugs.history` | false | ADVERTISEMENTS\_SLUG\_HISTORY | Remember retired ad slugs and 301 them to the current one. Needs sluggable’s migration. |
| `default_currency` | EUR | ADVERTISEMENTS\_CURRENCY | Currency for AdvertisementData::fromMinor() / fromDecimal() when none is given; must be registered in money-for-laravel. |
| `register_facade_alias` | true | ADVERTISEMENTS\_FACADE\_ALIAS | Register the global Advertisements alias; false to opt out. |
| `media.creative_bucket_prefix` | creative | — | Prefix of the per-placement bucket name ({prefix}:{slug}). |
| `media.fallback_bucket` | creative | — | Generic, size-less creative bucket tried before the text ad. |
| `media.disk` | null | ADVERTISEMENTS\_MEDIA\_DISK | Disk for creatives (null or blank = media-library default). |
| `media.responsive_widths` | null | — | Responsive width ladder (null = media-library default). Every width must be a positive integer; a bad or blank entry throws instead of being dropped. |
| `media.display_variant` | display | — | Variant name fit to the placement dimensions. |
| `media.use_fallback_bucket` | true | — | Try the generic creative bucket before the text ad. |
| `media.text_ad_view` | advertisements::text-ad | — | Blade view rendering the text-ad fallback. |
| `geo.targeting_enabled` | true | ADVERTISEMENTS\_GEO\_TARGETING | Apply geo-targeting in targetedIn(). |
| `geo.untargeted_match` | true | — | Ads with no targeting match every viewer. |
| `geo.match_when_unknown` | untargeted\_only | — | What an unknown viewer gets — untargeted\_only or all — and whether a rule the viewer lacks the country or coordinates for fails or passes. Anything else (ALL, everything) throws InvalidConfigurationException listing both. |
| `geo.stamp_events` | true | ADVERTISEMENTS\_GEO\_STAMP | Stamp the viewer’s country (+ region, city, coordinates) onto recorded events. |

## Environment

Eleven keys are env-backed, so you rarely need to publish the config at all:

```bash
ADVERTISEMENTS_CURRENCY=EUR
ADVERTISEMENTS_FALLBACK_LOCALE=en
ADVERTISEMENTS_KEY_TYPE=bigint
ADVERTISEMENTS_SLUG_HISTORY=true
ADVERTISEMENTS_TRACKING_BUFFERED=true
ADVERTISEMENTS_TRACKING_CONNECTION=redis
ADVERTISEMENTS_TRACKING_QUEUE=tracking
ADVERTISEMENTS_FACADE_ALIAS=true
ADVERTISEMENTS_MEDIA_DISK=s3
ADVERTISEMENTS_GEO_TARGETING=true
ADVERTISEMENTS_GEO_STAMP=true
```

## Notes

- default\_currency must be registered in money-for-laravel’s currency registry — any ISO 4217 code by default.
- key\_type is only read by the migration: change it before migrating, not after.
- The model keys must name the packaged model or a subclass of it; anything else throws — see Custom models.
- Every bool key accepts true/false, 1/0, on/off or yes/no (from .env or the published file). Anything else throws an InvalidConfigurationException naming the key, so a typo never quietly becomes the default.
- The other keys are just as strict: one that is not set — left out, null or blank ('' or whitespace, such as an ADVERTISEMENTS\_FALLBACK\_LOCALE= line) — takes its default; one set to the wrong shape throws an InvalidConfigurationException naming the key. The currency, locale, bucket names, display variant, text-ad view, disk and queue settings must be strings, and every responsive width a real width (a blank entry inside the list throws). php artisan about shows a broken setting as INVALID.
- With register\_facade\_alias off, import RoundlyConsulting\\Advertisements\\Facades\\Advertisements explicitly; the facade itself keeps working.

## Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

[More ways to support, including crypto](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel.md)