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.
idmust 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_idsdecides 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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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:
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.
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.