Skip to main content

Register an Add-on Bootstrap With Benecaster’s Entitlement Gate

Free Beginner

benecaster_register_addon() replaces the manual any_show_addon_is_active() check an add-on would otherwise write inline in its own benecaster_boot handler. Call it once, passing your slug and a bootstrap callback — Benecaster invokes the callback with the plugin Container, and only when your slug is entitled on at least one connected show. An unregistered slug, or one registered but not currently entitled, is silently skipped: your bootstrap never runs, so none of your filters, actions, or REST routes register.

Registration and invocation happen at two different moments: register() only records the callback. Nothing runs until Benecaster’s own late plugins_loaded pass (priority 20 — after benecaster_boot and after any add-on’s own plugins_loaded registration) walks every registered slug. Don’t rely on side effects from your bootstrap having happened by the time benecaster_boot itself returns.

A third, optional argument, $requires_core, declares a compatibility requirement — version (checked with version_compare( BENECASTER_VERSION, ..., '>=' )) and/or capabilities (function or class names checked with function_exists()/class_exists()). Both keys are independent and optional; declare only what you actually depend on. When an entitled add-on’s requirement isn’t met, Benecaster shows an admin notice naming your add-on and what it needs, and skips your bootstrap — never a fatal error, never a silent no-op. This is a compatibility check, not a tamper check: it answers “is the thing I need here?”, never “has Benecaster been modified?” — do not use it to detect or react to changes in Benecaster’s files.

A fourth, optional argument, $scope, lets a free add-on run site-wide. 'show' is the default. 'site' is for an add-on whose per-show switch means nothing — a block library, where one page can carry blocks for several shows. A site-wide add-on boots when any connected show’s license grants it, ignores the per-show switch, and has no Active on list on the Add-ons screen. It is honoured only for an add-on every Benecaster license is granted free; for anything else 'site' quietly means 'show', because a paid add-on is bought for a show, and a site-wide one would serve that purchase to shows it does not cover. Pass it positionally — benecaster_register_addon( $slug, $bootstrap, null, 'site' ) — if your add-on may meet an older Benecaster, where a named scope: argument is a fatal error. See benecaster_register_addon().

Code

<?php
add_action( 'benecaster_boot', function ( \Benecaster\Container $container ) {
    benecaster_register_addon(
        'benecaster-addon-guest-manager',
        function ( \Benecaster\Container $container ) {
            // This only runs when 'benecaster-addon-guest-manager' is
            // entitled on at least one connected show — no
            // any_show_addon_is_active() check needed here.
            $container->make( \GuestManager\GuestManagerPlugin::class )->register();
        },
        [
            'version'      => '1.60.0',                        // minimum Benecaster version
            'capabilities' => [ 'benecaster_addon_is_active' ], // function/class names that must exist
        ]
    );
} );

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →