README

Advertisements for Laravel

Run ads in your Laravel app: a draft → schedule → publish → expire → archive lifecycle, placements (zones) that serve the live ads, impression and click tracking with click-through rates, per-locale names and slugs, exact Money prices, geo-targeting and a responsive creative per placement with a text-ad fallback.

Installation

Requires PHP 8.4 with ext-bcmath, and Laravel 12 or 13.

composer require roundly-consulting/advertisements-for-laravel
php artisan vendor:publish --tag="advertisements-migrations"
php artisan vendor:publish --tag="media-migrations"   # creatives live in media-library-for-laravel
php artisan migrate

If the models that author ads use UUID or ULID keys, set ADVERTISEMENTS_KEY_TYPE=uuid / ulid before migrating.

Usage

Create an ad, place it in a zone and publish it:

use RoundlyConsulting\Advertisements\DataTransferObjects\AdvertisementData;
use RoundlyConsulting\Advertisements\Facades\Advertisements;
use RoundlyConsulting\Advertisements\Models\Placement;
use RoundlyConsulting\Money\Money;

Placement::create(['slug' => 'sidebar', 'name' => ['en' => 'Sidebar']]);

$ad = Advertisements::create(new AdvertisementData(
    name: 'Vintage road bike',
    price: Money::ofMajor('250.00', 'EUR'),
    author: $user,                                  // any Eloquent model
));

Advertisements::for($ad)->placements()->attach(['sidebar']);
Advertisements::publish($ad);                       // live now; pass a date to schedule it

Serve the zone and count what happens:

$ad = Advertisements::random('sidebar');            // one live ad for the zone

echo Advertisements::render($ad, 'sidebar');        // its creative, or the text-ad fallback

Advertisements::for($ad)->track('sidebar')->impression();
Advertisements::for($ad)->track('sidebar')->click();

$ad->impressions();                                 // 1
$ad->ctr();                                         // 1.0

Documentation

The full documentation — configuration, every feature and its API, and testing — lives on our website: roundly-consulting.com/open-source/docs/advertisements-for-laravel

Release notes are in CHANGELOG.md. To contribute, see the contributing guide.

Support our work

This package is free and open source, built and maintained by Roundly Consulting. If it saves you time, please consider supporting our open-source work — a one-time donation, a monthly pledge on Patreon or a crypto donation helps fund maintenance, new features and new packages.

License

The MIT License (MIT). Please see License File for more information.

roundly-consulting / advertisements-for-laravel

Package info

Security

Fund package maintenance!

Statistics