Filter- and action hooks

WXP Restaurant Reservations offers filters to change the mails, the booking form, the templates, the rate limit and the name of the database tables, and actions that tell your code when a reservation is made, changed or mailed. All names start with wxp_rr_.

How to use a hook #

A filter receives a value, can change it and must return it. An action tells you that something happened, and returns nothing. Add your code to the functions.php of your child theme, or to a small plugin of your own. The last number of add_filter() and add_action() is the number of arguments your function receives; ask for as many as you need.

add_filter( 'hook_name', function ( $value, $extra ) {
	// Change $value here.
	return $value;
}, 10, 2 );

add_action( 'hook_name', function ( $first, $second ) {
	// React here.
}, 10, 2 );

Overview #

Hook	Type	What it does
wxp_rr_reservation_created	Action	Fires after a reservation was made.
wxp_rr_reservation_updated	Action	Fires after a reservation was changed (details, table or status).
wxp_rr_reservation_modified	Action	Fires after the time, the party size or the number of kids of a reservation changed. The guest mail about the change is sent from this hook.
wxp_rr_reservation_status_changed	Action	Fires after the status of a reservation changed: seated, completed, cancelled or no-show.
wxp_rr_mail_enabled	Filter	Decides whether a mail is sent.
wxp_rr_mail_message	Filter	Changes the message before it is sent.
wxp_rr_mail_sent	Action	Fires after a mail was handed to wp_mail().
wxp_rr_restaurant_name	Filter	Changes the restaurant name used in the mails. The default is the title of the site.
wxp_rr_consent_text	Filter	Changes the text next to the consent checkbox of the booking form.
wxp_rr_template_context	Filter	Changes the data passed to a reservation template.
wxp_rr_template_paths	Filter	Changes the folders where templates are looked for, in lookup order. The folders of your (child) theme come before the templates folder of the plugin.
wxp_rr_twig_cache	Filter	Sets a folder for the compiled templates. Caching is off by default.
wxp_rr_load_css	Filter	Decides whether the plugin loads its own stylesheet. Return false to use your own CSS.
wxp_rr_rate_limit	Filter	Changes how often a visitor may use the public routes of the booking form.
wxp_rr_client_ip	Filter	Changes the address that is rate limited. Behind a proxy or a CDN, return the address of the real visitor.
wxp_rr_table_prefix	Filter	Changes the prefix of the database tables of the plugin. The default is the WordPress prefix followed by wxp_rr_. This is meant for tests; do not change it on a site with reservations, because the plugin then looks at other tables.

Actions: reservations #

wxp_rr_reservation_created #

Action. Fires after a reservation was made.

Argument	Type	Description
$reservation	Reservation	The new reservation.

add_action( 'wxp_rr_reservation_created', function ( $reservation ) {
	// Tell your own system about the new reservation.
} );

wxp_rr_reservation_updated #

Action. Fires after a reservation was changed (details, table or status).

Argument	Type	Description
$reservation	Reservation	The reservation after the change.

wxp_rr_reservation_modified #

Action. Fires after the time, the party size or the number of kids of a reservation changed. The guest mail about the change is sent from this hook.

Argument	Type	Description
$reservation	Reservation	The reservation after the change.
$previous	Reservation	The reservation as it was before.

wxp_rr_reservation_status_changed #

Action. Fires after the status of a reservation changed: seated, completed, cancelled or no-show.

Argument	Type	Description
$reservation	Reservation	The reservation after the change.
$status	ReservationStatus	The new status.

Actions and filters: mail #

wxp_rr_mail_enabled #

Filter. Decides whether a mail is sent.

Argument	Type	Description
$send	bool	true by default.
$type	string	The mail type: confirmation, changed, cancelled or venue.
$booking	Reservation	The reservation.

Return: true to send, false to skip.

// Do not send the mail to the restaurant itself.
add_filter( 'wxp_rr_mail_enabled', function ( $send, $type ) {
	return 'venue' === $type ? false : $send;
}, 10, 2 );

wxp_rr_mail_message #

Filter. Changes the message before it is sent.

Argument	Type	Description
$message	array	to, subject, body (HTML) and headers. An empty to cancels the mail.
$type	string	The mail type.
$booking	Reservation	The reservation.

Return: the message.

wxp_rr_mail_sent #

Action. Fires after a mail was handed to wp_mail().

Argument	Type	Description
$type	string	The mail type.
$booking	Reservation	The reservation.
$sent	bool	Whether wp_mail() accepted the mail.

wxp_rr_restaurant_name #

Filter. Changes the restaurant name used in the mails. The default is the title of the site.

Argument	Type	Description
$name	string	The name.

Return: the name.

Booking form and templates #

wxp_rr_consent_text #

Filter. Changes the text next to the consent checkbox of the booking form.

Argument	Type	Description
$text	string	The text.

Return: the text.

add_filter( 'wxp_rr_consent_text', function () {
	return 'I agree that my details are used for this reservation.';
} );

wxp_rr_template_context #

Filter. Changes the data passed to a reservation template.

Argument	Type	Description
$context	array	The template data.
$template	string	The name of the template.

Return: the template data.

wxp_rr_template_paths #

Filter. Changes the folders where templates are looked for, in lookup order. The folders of your (child) theme come before the templates folder of the plugin.

Argument	Type	Description
$paths	string[]	Folders.

Return: the list of folders.

wxp_rr_twig_cache #

Filter. Sets a folder for the compiled templates. Caching is off by default.

Argument	Type	Description
$cache	string|false	A folder, or false (default).

Return: a folder, or false.

wxp_rr_load_css #

Filter. Decides whether the plugin loads its own stylesheet. Return false to use your own CSS.

Argument	Type	Description
$load	bool	true by default.

Return: true or false.

add_filter( 'wxp_rr_load_css', '__return_false' );

Protection and database #

wxp_rr_rate_limit #

Filter. Changes how often a visitor may use the public routes of the booking form.

Argument	Type	Description
$limit	array	Two numbers: the attempts allowed, and the length of the window in seconds. A limit of 0 turns the limit off.
$action	string	The route: availability or create.

Return: the limit.

// At most 5 bookings per visitor per 10 minutes.
add_filter( 'wxp_rr_rate_limit', function ( array $limit, string $action ) {
	return 'create' === $action ? array( 5, 600 ) : $limit;
}, 10, 2 );

wxp_rr_client_ip #

Filter. Changes the address that is rate limited. Behind a proxy or a CDN, return the address of the real visitor.

Argument	Type	Description
$ip	string	The address of the visitor.

Return: the address.

add_filter( 'wxp_rr_client_ip', function ( $ip ) {
	if ( ! empty( $_SERVER['HTTP_X_FORWARDED_FOR'] ) ) {
		$parts = explode( ',', sanitize_text_field( wp_unslash( $_SERVER['HTTP_X_FORWARDED_FOR'] ) ) );
		return trim( $parts[0] );
	}
	return $ip;
} );

wxp_rr_table_prefix #

Filter. Changes the prefix of the database tables of the plugin. The default is the WordPress prefix followed by wxp_rr_. This is meant for tests; do not change it on a site with reservations, because the plugin then looks at other tables.

Argument	Type	Description
$prefix	string	The prefix.

Return: the prefix.

Good to know #

• Demo data: the actions are not fired for the demo reservations of the importer, and never inside a database transaction.
• Repeated requests: when a guest sends the same booking twice (for example by a double click), the second request returns the first reservation and wxp_rr_reservation_created is fired once.
• Mails: the plugin sends its own mails from these actions. Your function runs next to them, so you can add your own handling without switching the mails off.