Skip to content

Hooks and filters

The extension points Club Player Manager and its companions mean for you to use. Everything else in the codebase is internal and moves without notice.

The hooks a companion plugin uses to share the core plugin's data and screens (squad columns, the member page, the guardian account page, actions about a member's records) are documented in full in the platform layer; they are listed below with a link to each.

Adding to the Squads screen

Club Management → Squads is the plugin's home screen and the place another plugin adds its own content without either plugin knowing about the other. Three actions mark the insertion points, top to bottom.

Hook Fires
cpm_overview_before_content Above the headline cards
cpm_overview_after_stats Between the headline cards and the squad list
cpm_overview_after_content At the foot of the page

The hooks keep the screen's old name, Overview, in their own names. Each is passed the club figures the page has already gathered, so a listener never has to query for them again:

Key Type What it is
is_club_admin bool Whether the viewer is a club admin rather than a squad secretary
squads object[] Each carries a ->player_count
total_players int The number of members
waiting_count int\|null null for a squad secretary, who gets no club-wide waiting-list figure
add_action(
    'cpm_overview_after_content',
    function ( array $summary ) {
        echo '<h2 class="cpm-section-title">Kit orders</h2>';
        // …your own panel.
    }
);

Anything echoed on these hooks goes straight into the page wrapper, so escape it and follow the admin UI conventions — the point of the hooks is that added content looks like it belongs.

cpm_overview_stats

To add a headline card alongside Members, Squads and Waiting list, filter the cards instead. Each is value (int), label (string) and an optional url that turns the card into a link.

add_filter(
    'cpm_overview_stats',
    function ( array $stats, array $summary ) {
        $stats[] = array(
            'value' => 12,
            'label' => __( 'Coaches', 'my-plugin' ),
            'url'   => admin_url( 'admin.php?page=my-coaches' ),
        );
        return $stats;
    },
    10,
    2
);

Respect $summary['is_club_admin'] if your figure is something a squad secretary should not see.

Adding to the action list

Club Management → Actions is the club's list of outstanding jobs. A plugin contributes whole rows to it by registering a provider on cpm_action_list_providers.

add_filter(
    'cpm_action_list_providers',
    function ( array $providers ): array {
        $providers['my_kit_orders'] = array(
            'label'    => __( 'Kit orders', 'my-plugin' ),
            'callback' => 'my_plugin_kit_actions',
            // 'capability' => 'cpm_access',   // optional; this is the default
        );
        return $providers;
    }
);

function my_plugin_kit_actions( array $context ): array {
    $actions = array();
    foreach ( CPM_Platform::confirmed_players( $context['season_id'] ) as $player ) {
        if ( my_plugin_has_kit( $player->id ) ) {
            continue;
        }
        $actions[] = array(
            'id'        => 'kit:' . $context['season_id'] . ':' . $player->id,
            'title'     => sprintf( 'Order a shirt for %s', $player->full_name ),
            'detail'    => 'Confirmed for ' . $context['season_name'],
            'url'       => admin_url( 'admin.php?page=my-kit&player=' . $player->id ),
            'squad_ids' => $player->squad_ids,
        );
    }
    return $actions;
}

The callback is handed the context the page already worked out, and answers with what needs doing right now:

Key Type What it is
is_club_admin bool Whether the viewer is a club admin rather than a squad secretary
season_id int The active season, or 0 when the club has none — answer with nothing
season_name string For the detail line

Three rules decide whether a provider behaves:

  • Actions are derived, never stored. Your callback runs on every page load, so an action leaves the list by the job being done — there is nothing to retire and no way for the list to ask for something twice.
  • id must be stable and unique within your provider. It is what a dismissal ("set aside") is remembered by, so compose it from what the action is about, never from a row id that could change. Club Player Manager namespaces it with your provider key.
  • squad_ids decides who sees the row. An action naming squads reaches those squads' team secretaries as well as club admins; one naming none is club-wide and only club admins see it. Scoping is applied for you — your callback is never told whose squads are whose.

A provider that throws costs its own section and nothing else.

Adding to the Setup screen

cpm_setup_next_steps

apply_filters( 'cpm_setup_next_steps', array $next_steps );

The "more to explore" links on Club Management → Setup. The core plugin's setup stops once the club has its squads, members and tasks; a companion plugin adds a link to wherever its own part of setting up starts. Each entry is an array of label, description and url.

add_filter(
    'cpm_setup_next_steps',
    function ( array $steps ): array {
        $steps[] = array(
            'label'       => __( 'Set up kit orders', 'my-plugin' ),
            'description' => __( 'Sizes and suppliers for this season.', 'my-plugin' ),
            'url'         => admin_url( 'admin.php?page=my-kit-settings' ),
        );
        return $steps;
    }
);

Reacting to registrations and payments

These actions fire at the moments other code usually cares about. All of them run inside the request that caused them, so keep listeners quick — or schedule your own job and return.

cpm_player_season_confirmed

do_action( 'cpm_player_season_confirmed', int $season_id, int $player_id );

A member has been newly confirmed for a season, whether by the parent approving through the form or by a club admin recording the answer on the season's page. Fires once per member, on the transition only — not on every save of an already-confirmed row.

cpm_season_registration_confirmed

do_action( 'cpm_season_registration_confirmed', int $season_id, int $player_id, string $status );

The same moment, with the confirmed status that was set. This is the hook the plugin's own confirmation automations listen on; use it when you need to know which confirmed status applies, and cpm_player_season_confirmed when you only need the fact.

cpm_registration_payment_confirmed

do_action( 'cpm_registration_payment_confirmed', int $player_product_id, int $player_id );

A Registration product's fee has cleared for a member — the moment the club's registration-paid alert goes out. $player_product_id identifies the specific member-and-product row, not the product.

It deliberately does not wait for the Direct Debit: a one-off fee never sets a mandate up at all, and an instalment plan's mandate goes active later. Products of other types — kit, subs — are purchases rather than registrations and never raise it.

cpm_gc_event

do_action( 'cpm_gc_event', object $event, ?int $player_id, string $env );

Every GoCardless webhook event the plugin had not already recorded: one hook for every resource type and action. $player_id is the member the event was resolved to, or null. $env is the environment the webhook came from (sandbox or live); a listener that goes back to GoCardless for more must ask that environment, because both environments' webhooks are accepted whichever one is active.

It fires after the event is recorded, so a redelivered webhook never reaches it again. The plugin's own payment emails to parents listen here.

cpm_gc_event_failed

do_action( 'cpm_gc_event_failed', object $event, ?int $player_id );

GoCardless has reported that something failed: a Direct Debit payment, a mandate, a billing request or an instalment schedule. Fires straight after cpm_gc_event for the same event, and only once per event. The club's Payment failure alert email listens here.

cpm_billing_request_expired

do_action( 'cpm_billing_request_expired', int $player_product_id, int $player_id );

The daily sweep has closed a payment setup request nobody started, after cpm_billing_request_expiry_days (below). The request is cancelled at GoCardless, so the emailed link stops working, and the member's product is offered again. Nothing had been collected, so nothing is refunded.

Payment emails to parents

cpm_payment_notices

apply_filters( 'cpm_payment_notices', array $notices );

The register of payment emails sent to parents (payment received, payment failed, payment coming up, plan confirmed, plan cancelled, setup not finished), keyed by slug. A definition you add here behaves exactly like a shipped one: it gets its own entry on Email Settings, its own on/off switch, editable wording, and a guarantee that each parent is sent it once. Build one with CPM_Payment_Notice::on_event() (sent when a GoCardless event arrives) or CPM_Payment_Notice::on_date() (sent by the daily sweep), so it is normalised the same way.

Settings that are filters

Code-only settings, for sites where the defaults are wrong. None has a settings screen, because a club that needs to change one has a reason a checkbox would not capture.

Filter Default What it changes
cpm_email_queue_batch_size 10 Messages drained per background pass. Raise it on a host with generous timeouts, lower it on a slow one. Floored at 1.
cpm_email_queue_retention_days 3 How long finished queue rows are kept before the daily prune removes them
cpm_email_log_retention_days 90 How long the Email Log keeps a sent message. Raise it if the club needs a longer record of what it sent whom.
cpm_billing_request_expiry_days 7 How many days a payment setup request is left open before the daily sweep closes it. 0 or less turns the sweep off.
cpm_payment_notice_retention_days 400 How long the record of which payment emails were sent is kept. It has to outlast the plan it protects, or a parent could be told twice. 0 or less keeps them forever.
// A host that times out at 30 seconds is happier with smaller batches.
add_filter( 'cpm_email_queue_batch_size', fn() => 5 );

// Keep two years of email history.
add_filter( 'cpm_email_log_retention_days', fn() => 730 );

// Give parents a fortnight to start a payment setup before it is closed.
add_filter( 'cpm_billing_request_expiry_days', fn() => 14 );

Raising log retention grows a table that is never otherwise trimmed. That is the intended trade, but it is a trade.

Hooks documented in the platform layer

These are the hooks a companion plugin uses to sit inside the core plugin's screens and keep its own records in step. Each is described, with its arguments and rules, in the platform layer.

Hook Type What it does Where
cpm_squad_player_columns filter Adds a column to a squad's member tables Reading core's data
cpm_squad_list_columns filter Adds a column to the squad list on Club Management → Squads Reading core's data
cpm_squad_page_title filter Sets the generated title of a squad's public page Squad page extension points
cpm_squad_page_sections action Adds a section to a squad's public page Squad page extension points
cpm_imported_team_registration action One team registration read out of an FA Club Player Report Actions core fires
cpm_before_player_deleted action A member is about to be deleted Actions core fires
cpm_player_fan_merged action A duplicate merge moved one FA Number onto another Actions core fires
cpm_player_detail_cards action Adds a card to a member's page The member page
cpm_account_links filter Adds a link to "More from the club" on the guardian account page The guardian account
cpm_account_recognised_email filter Lets an address that is not a guardian's sign in to the account page The guardian account
cpm_enqueue_admin_styles action The moment to enqueue a companion plugin's admin stylesheet Your plugin's stylesheet

English FA

efa_allowed_source_hosts

apply_filters( 'efa_allowed_source_hosts', string[] $hosts );

English FA never fetches from FA Full-Time itself: its collector pushes each league's collected page to the site, together with the address it came from. The site records that address and refuses a push whose address is not on one of these hosts (or a subdomain of one). Defaults to:

array( 'fulltime.thefa.com', 'thefa.com', 'fulltime-league.thefa.com' )

Widen it only if your league is served from somewhere else that the collector fetches from:

add_filter(
    'efa_allowed_source_hosts',
    function ( array $hosts ) {
        $hosts[] = 'fulltime.mycountyfa.com';
        return $hosts;
    }
);

Host names are lower-cased and empty entries dropped, so case does not matter.

Referees

crf_fixture_message

apply_filters( 'crf_fixture_message', string $message, object $fixture, string $name, string $url );

The ready-written message a referee request is sent with. $name is the referee's name, or '' for a message to a group; $url is the link the referee accepts the fixture at, and should stay in whatever you return. See Referees.

Scheduled jobs

Not hooks to extend, but the events worth knowing about when diagnosing a quiet site.

Event Schedule What it does
cpm_process_email_queue one-off, rescheduled while work remains Drains the outgoing email queue
cpm_prune_email_queue daily Removes finished queue rows past their retention
cpm_prune_email_log daily Removes log entries past their retention
cpm_send_payment_notices daily, plus a catch-up run soon after when there is more to send Sends the date-based payment emails to parents, such as a payment coming up
cpm_close_expired_billing_requests daily, plus a catch-up run soon after when there is more to close Closes payment setup requests nobody started
cpm_prune_guardian_sessions daily Removes expired guardian sign-in sessions and spent sign-in links
efa_send_match_invitations one-off, booked an hour after a match invitation and rescheduled while work remains English FA: emails guardians their children's match invitations, when invitation emails are switched on

English FA's fixtures and results have no scheduled job on the site. Its collector pushes them in on its own schedule; see English FA.

wp cron event list | grep -E 'cpm|efa'
wp cron event run cpm_process_email_queue

A site with DISABLE_WP_CRON set and no system cron will queue email and never send it — see Troubleshooting.

Capabilities

Two gate the core plugin, and they are what to check rather than manage_options if you are adding a screen that should follow the plugin's access rules:

Capability Who has it
cpm_access Any club admin or squad secretary — "can reach the plugin at all"
cpm_manage_all Club admins only

A squad secretary's view is scoped to their own squads in the plugin itself, not by hiding menu items, so a screen you add on cpm_access must do its own scoping. The platform layer provides the helpers for that.

The rest are narrower, and are granted from those two:

Capability Who has it What it gates
cpm_edit_content_pages / cpm_manage_content_pages The same people as cpm_access / cpm_manage_all The season and squad page post types
efa_manage WordPress administrators and club admins Every English FA screen, and its collector's REST routes
crf_manage WordPress administrators and club admins The Referees admin screens
ccp_manage WordPress administrators and club admins Every Card Payment screen

Building a companion plugin

If you are going further than a hook — your own admin screens inside the Club Management menu, reading the club's data, sharing its look — read the platform layer. It covers what is public, how to depend on it without breaking during a deploy, and the version contract between a companion plugin and the core.