--- title: "Advertisements for Laravel — docs | Roundly" description: "Developer docs for Advertisements for Laravel: ad lifecycle, exact Money prices, placements, impression and click tracking, creatives and geo-targeting." url: https://roundly-consulting.com/open-source/docs/advertisements-for-laravel language: en --- [All packages](https://roundly-consulting.com/open-source.md) Open source # Advertisements for Laravel Install `composer require roundly-consulting/advertisements-for-laravel` Requires: PHP ^8.4 · Laravel ^12.0|^13.0 [GitHub](https://github.com/roundly-consulting/advertisements-for-laravel) [Packagist](https://packagist.org/packages/roundly-consulting/advertisements-for-laravel) [Donate (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Patreon](https://www.patreon.com/cw/roundly) ## Overview A native advertisement engine for Laravel. It ships an Advertisement model with a draft → scheduled → published → expired → archived lifecycle, nestable categories and placements (ad zones), per-locale names, and impression and click tracking with click-through rate — written inline or buffered to the queue. Four sibling Roundly packages supply the rest: image creatives per placement with a text-ad fallback, geo-targeting and per-country reports, per-locale slugs with 301 history, and exact Money prices. MIT-licensed, with no third-party dependencies beyond Laravel and Roundly’s own packages. ### What you get #### Full ad lifecycle Draft, schedule, publish, expire and archive with one call each — every transition fires an event and status is recomputed from the dates on every read. #### Placements & serving Model ad zones, attach ads by model, id or slug, and fetch the active or a random ad for a zone in one call. #### Impression & click tracking Denormalized counters and click-through rate, request context on every event row, written inline or buffered to the queue. #### Creatives with a text-ad fallback A responsive image creative sized to each placement, falling back to a restylable text ad so no slot stays empty. #### Geo-targeting & reports Allow or block countries, target a radius around a point, and break impressions and clicks down by country. #### Exact Money prices Minor-unit Money in a decimal(38,0) column — no floats, currency-safe writes and numeric ordering. #### Facade, DI or actions One Advertisements facade, an injectable manager and single-purpose actions — plus a recording fake with an assertion per operation. ### Documentation #### [Installation](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/installation.md) Install via Composer, publish and run the migrations (plus media-library’s, always, and sluggable’s for slug history), then optionally the config and view. #### [Configuration](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/configuration.md) Every config key with its default and env variable — models, author key type, currency, locale, slug history, tracking, creatives and geo. #### [Quick start](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/quick-start.md) Create an ad, give it a placement, publish it, then serve, render and track it — the whole flow through the Advertisements facade. #### [The Advertisements facade](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/facade.md) The whole API on one facade — lifecycle verbs, serving queries, rendering, and a for($ad) handle for placements and tracking. #### [DI and actions](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/without-facade.md) Inject AdvertisementManager for the same API without static calls, or call the single-purpose action behind each facade method. #### [Creating & updating ads](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/creating-advertisements.md) Build ads from the AdvertisementData DTO or its exact fromMinor() / fromDecimal() factories, straight from requests, and update only the fields you pass. #### [Lifecycle & status](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/lifecycle.md) Publish now or on a schedule, unpublish, expire, archive and soft-delete — each transition fires an event; status is recomputed on every read. #### [Query scopes](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/query-scopes.md) Chain published, active, scheduled, expired, draft, archived, author, placement, category and geo scopes — or start from the facade. #### [Prices](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/prices.md) Prices are exact Money values in a decimal(38,0) minor-unit column — no floats, currency-safe writes, numeric ordering and API resources. #### [Placements](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/placements.md) Model ad zones such as a sidebar or in-feed slot, attach ads by model, id or slug, and fetch the active or a random ad for a zone in one call. #### [Impression & click tracking](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/tracking.md) Record impressions and clicks of live ads inline or via the queue, with transactional counters, CTR, request context and per-country reports. #### [Creatives](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/creatives.md) Attach an image creative per placement, get a display variant sized to the zone, and render a responsive or the text-ad fallback. #### [Geo-targeting](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/geo-targeting.md) Restrict ads to allowed or blocked countries or a radius around a point, and serve each viewer only the ads their location matches. #### [Translations](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/translations.md) Name, description and slug are per-locale JSON maps with active-locale reads, a configurable fallback and no third-party dependency. #### [Categories](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/categories.md) Organise ads into a nestable category tree and filter by one category alone or together with every category nested beneath it. #### [Slugs & routing](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/slugs-routing.md) Per-locale ad slugs with database-enforced uniqueness, any-locale route binding, optional 301s from retired slugs and validation rules. #### [Events](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/events.md) Every create, update and lifecycle transition dispatches an event with the ad; impressions and clicks dispatch one with the tracking row. #### [Custom models](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/custom-models.md) Point the four model config keys at your own subclasses to add fields and logic while keeping every scope, relation and cast. #### [Artisan commands](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/commands.md) Prune expired ads with model:prune, inspect the setup with about, and add per-locale slug indexes with sluggable:indexes. #### [Testing](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/testing.md) Advertisements::fake() records every lifecycle, placement and tracking call with an assertion for each, plus factories and geolocation fakes. #### [Exceptions](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/exceptions.md) The package’s exception base, InvalidTargeting, AdvertisementNotActive and AdvertisementNotInPlacement, plus money, sluggable and toolkit errors. #### [Requirements](https://roundly-consulting.com/open-source/docs/advertisements-for-laravel/requirements.md) PHP 8.4+ with ext-bcmath, Laravel 12 or 13, and six Roundly packages Composer installs for you; gd or imagick for creative variants. ## 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.md)