effyads / laravel
EffyAds advertisement sync, rendering and click/view tracking for Laravel applications
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.2|^8.0
- illuminate/bus: ^10.0|^11.0|^12.0|^13.0
- illuminate/cache: ^10.0|^11.0|^12.0|^13.0
- illuminate/console: ^10.0|^11.0|^12.0|^13.0
- illuminate/contracts: ^10.0|^11.0|^12.0|^13.0
- illuminate/database: ^10.0|^11.0|^12.0|^13.0
- illuminate/filesystem: ^10.0|^11.0|^12.0|^13.0
- illuminate/http: ^10.0|^11.0|^12.0|^13.0
- illuminate/queue: ^10.0|^11.0|^12.0|^13.0
- illuminate/routing: ^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^10.0|^11.0|^12.0|^13.0
- illuminate/view: ^10.0|^11.0|^12.0|^13.0
Requires (Dev)
- orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
- phpunit/phpunit: ^10.5|^11.0|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-22 15:55:50 UTC
README
Shows advertisements managed in EffyAds on a Laravel site. The platform pushes advertisements to the site, the package renders them with a Blade component and reports views and clicks back.
Supports Laravel 10, 11, 12 and 13 (PHP 8.1+, Laravel 13 needs PHP 8.3+).
Installation
1. Install the package
composer require effyads/laravel
2. Run the installer
php artisan effyads:install
This publishes config/effyads.php, generates an API key, prints the .env
lines and asks whether to run the migrations. Options:
| Option | Effect |
|---|---|
--write-env |
Adds the lines to .env after confirmation. Existing values are never overwritten. |
--show-key |
Shows the full key when one is already configured (it is masked by default). |
3. Run the migrations
php artisan migrate
Skip this if you let the installer run them.
4. Check your .env
EFFYADS_API_KEY=... # printed by effyads:install EFFYADS_PLATFORM_URL=https://app.effyads.com EFFYADS_QUEUE_CONNECTION=sync # optional, sync is the default
EFFYADS_QUEUE_CONNECTION decides how views and clicks reach EffyAds:
sync(default): sent right after the response has been delivered to the visitor. No queue worker needed, and the pixel and click redirect stay fast.- A queue connection such as
redisordatabase: only use this when a worker runs for that connection, otherwise events stay in the queue unsent. Failed sends are retried 3 times.
5. Place an advertisement
Define zones in config/effyads.php:
'zones' => [ 'homepage-hero' => 'Homepage hero banner', 'blog-sidebar' => 'Blog sidebar', ],
Then render one in any view:
<x-effyads::ad zone="homepage-hero" /> <x-effyads::ad zone="blog-sidebar" class="my-6" :width="300" :height="250" />
- Shows advertisements with status
active, orscheduledonce the start date has passed, within their start and end date. - When several advertisements match a zone, one is picked at random on every
render, weighted by
targeting.weight(default 1,0= never). Set'rotation' => 'first'in the config to always show the oldest match. - Extra attributes such as
classare added to the wrapper<div>. The image getsloading="lazy", andwidth/heightfrom the component or from the advertisement'smedia_width/media_height. - All zones on a page share one database query.
- With
APP_DEBUG=true, a zone that is not inconfig('effyads.zones')logs a warning.
6. Connect the site in the dashboard
In the EffyAds dashboard, use Connect a website and enter a name, the site's URL and the API key from step 2.
The site must be publicly reachable: EffyAds calls it to push
advertisements, so localhost or a .test domain does not work. To test
locally, share the site with a tunnel and connect that URL instead:
herd share # Laravel Herd
expose share http://myapp.test
ngrok http 80
Multiple sites in one Laravel app
By default the package serves one site with one API key. A multi-tenant app
(for example groningen.example.nl and assen.example.nl, each connected as
its own website in the dashboard) needs every site to have its own
advertisements and its own key. Otherwise all sites show the same ads, and a
sync/bulk from one site deletes the ads of the others.
Register two resolvers, usually in AppServiceProvider::boot():
use EffyAds\Laravel\EffyAds; use Illuminate\Http\Request; // Which site does this request belong to? null = no site. EffyAds::resolveSiteUsing(fn (Request $request): ?string => /* ... */); // Which API key must the platform send for this site? EffyAds::resolveApiKeyUsing(fn (?string $site): ?string => /* ... */);
Once a site resolver is set, every advertisement is stored with its site, and
the API, the Blade component and the tracking routes only see that site's
advertisements. sync/bulk only deletes within the site. sync/status
returns site and site_url, so the dashboard can check that it talks to
the right site. Without resolvers nothing changes.
Generate a key per site and store it where your key resolver reads it:
php artisan effyads:install --site=groningen # only prints a new key
Example: stancl/tenancy
The EffyAds routes are registered by the package, outside your tenant route
file, so add the tenancy middleware to them in config/effyads.php:
'route_middleware' => [ \Stancl\Tenancy\Middleware\InitializeTenancyByDomain::class, \Stancl\Tenancy\Middleware\PreventAccessFromCentralDomains::class, ],
Then resolve the site and key from the current tenant. This example keeps the
key in the tenant's data column as effyads_api_key:
use App\Models\Tenant; use EffyAds\Laravel\EffyAds; public function boot(): void { EffyAds::resolveSiteUsing(fn () => tenant()?->getTenantKey()); EffyAds::resolveApiKeyUsing(fn (?string $site) => $site ? Tenant::find($site)?->effyads_api_key : null); }
Store a key for each tenant, for example in php artisan tinker:
Tenant::find('groningen')->update(['effyads_api_key' => '<key from effyads:install --site=groningen>']);
Connect each tenant domain as a separate website in the EffyAds dashboard, with that tenant's key.
With this middleware the EffyAds routes, including the public tracking pixel and click redirect, only work on tenant domains. That is intended: on the central domain there is no site, so there are no advertisements to track.
API surface
All routes below require the X-EffyAds-API-Key header, compared with
hash_equals against the configured key.
| Method | Path | Purpose |
|---|---|---|
| GET/POST | /effyads/v1/advertisements |
list / create (upsert by platform_id) |
| GET/PUT/DELETE | /effyads/v1/advertisements/{platform_id} |
read / update / delete one |
| GET | /effyads/v1/sync/status |
health check |
| POST | /effyads/v1/sync/bulk |
reconcile against a list of platform ids |
| GET | /effyads/v1/targeting/options |
available zones |
| POST | /effyads/v1/media/upload |
base64 image upload to the configured filesystem disk |
Public routes (hit directly by visitors' browsers):
| Method | Path | Purpose |
|---|---|---|
| GET | /effyads/track/view/{platform_id} |
1x1 tracking pixel |
| GET | /effyads/track/click/{platform_id} |
records the click, redirects to the ad's link |
Both tracking routes dispatch EffyAds\Laravel\Jobs\RecordTrackingEvent,
which POSTs to {EFFYADS_PLATFORM_URL}/api/tracking.
Testing tip: with the default sync connection the event is sent after
the response, when the app terminates. In a feature test that makes several
requests on the same app instance, these after-response callbacks can run
more than once, so Http::assertSentCount() may count an event twice. This
does not happen in production, where every request gets a fresh app. In your
own tests, use Bus::fake() and Bus::assertDispatchedAfterResponse(), or set
effyads.queue_connection to another connection and use Queue::fake().
Security
Setting (config/effyads.php) |
Default | Purpose |
|---|---|---|
api_rate_limit |
120 |
Requests per minute per IP on effyads/v1 (throttle:effyads-api). |
allow_query_api_key |
false |
Temporarily accept ?api_key= (logs a deprecation warning). Keys in URLs end up in logs, so use the header. |
media_max_kb |
5120 |
Maximum size of an uploaded image. |
tracking.rate_limit |
60 |
Requests per minute per IP on the tracking routes (throttle:effyads-tracking). |
tracking.dedupe_seconds |
view: 1800, click: 60 |
The same visitor (IP + user agent) is counted once per ad per window. 0 disables. |
tracking.bot_user_agents |
regex | Matching (and empty) user agents are not counted. null counts everything. |
- Media upload: the file type is detected from the bytes, never from the
client's
filenameormime_type. Only real JPEG, PNG, GIF and WebP images are stored, under a random name with the matching extension. - Tracking: views and clicks are only recorded for advertisements that exist and are active (for the current site). An unknown ad still gets the pixel, but nothing is recorded.
- API key: any failure returns the same
403 Unauthorized, without a reason.
Differences from the WordPress plugin
- Targeting: WordPress targets by taxonomy, post type and page. A Laravel
app has no universal equivalent, so targeting uses app-defined zones
(
config('effyads.zones')). - Response shape: responses use
id(the local row id) instead of WordPress'swordpress_id. - CORS: not handled by this package. Add
effyads/v1/*topathsinconfig/cors.phpif the platform ever calls these endpoints from a browser.
Distribution (for EffyAds maintainers)
The package is developed in laravel-package/ of the private EffyAds
monorepo. The Laravel package split workflow mirrors that folder to the
public, read-only repo Wites-NL/effyads-laravel,
which Packagist reads:
- every push to
masterupdates the split repo'smainbranch (1.x-dev); - a monorepo tag
laravel-vX.Y.Zbecomes tagvX.Y.Zin the split repo, and Packagist publishes it as versionX.Y.Z.
To release: update CHANGELOG.md, merge staging into master, then
git tag laravel-v1.0.0 && git push origin laravel-v1.0.0.
The workflow needs the monorepo secret EFFYADS_LARAVEL_SPLIT_TOKEN: a
fine-grained token with Contents: read and write on the split repo.
Changes made directly in the split repo are overwritten by the next split.
Development
composer install vendor/bin/phpunit