Hooks: Actions and Filters

add_action( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 ): true
add_filter( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 ): true

<?php
defined( 'ABSPATH' ) || exit;

/**
 * Stock badge in book titles. Its hooks are attached from an object, so removing them needs the same instance.
 */
final class Lumen_Catalog_Stock {

	/** @var Lumen_Catalog_Stock|null The instance that owns the hooks. */
	private static $instance = null;

	/**
	 * Returns the instance, creating it and attaching its callbacks on first use.
	 */
	public static function instance() {
		if ( null === self::$instance ) {
			self::$instance = new self();
			add_filter( 'the_title', array( self::$instance, 'mark_out_of_stock' ), 10, 2 );
		}
		return self::$instance;
	}

	/**
	 * Appends "(out of stock)" to the title of books whose stock is zero.
	 *
	 * @param string $title   Post title.
	 * @param int    $post_id Post ID, the second argument of the_title.
	 * @return string
	 */
	public function mark_out_of_stock( $title, $post_id = 0 ) {
		if ( 'lp_book' === get_post_type( $post_id ) && '0' === get_post_meta( $post_id, 'lp_stock', true ) ) {
			/* translators: %s: book title. */
			$title = sprintf( __( '%s (out of stock)', 'lumen-catalog' ), $title );
		}
		return $title;
	}
}

add_action( 'plugins_loaded', array( 'Lumen_Catalog_Stock', 'instance' ) );

<?php
// Run with: wp eval-file hook-removal-demo.php
add_filter( 'lumen_demo', 'strtoupper', 20 );
var_dump( remove_filter( 'lumen_demo', 'strtoupper' ) );       // bool(false): wrong priority (default 10).
var_dump( remove_filter( 'lumen_demo', 'strtoupper', 20 ) );   // bool(true): same name and priority.

$exclaim = static fn( $text ) => $text . '!';
add_filter( 'lumen_demo', $exclaim );
var_dump( remove_filter( 'lumen_demo', static fn( $text ) => $text . '!' ) ); // bool(false): look-alike closure.
var_dump( remove_filter( 'lumen_demo', $exclaim ) );                          // bool(true): the same closure.

$stock = Lumen_Catalog_Stock::instance();
var_dump( has_filter( 'the_title', array( $stock, 'mark_out_of_stock' ) ) );                   // int(10): its priority.
var_dump( remove_filter( 'the_title', array( new Lumen_Catalog_Stock(), 'mark_out_of_stock' ) ) ); // bool(false): other instance.
var_dump( remove_filter( 'the_title', array( $stock, 'mark_out_of_stock' ) ) );                // bool(true): same instance.

<?php
defined( 'ABSPATH' ) || exit;

/**
 * Creates a book from an import row.
 *
 * @param array  $row    Keys: title, isbn, pages.
 * @param string $source Where the row comes from, for example 'csv' or 'distributor'.
 * @return int|WP_Error Post ID, or an error from wp_insert_post().
 */
function lumen_catalog_import_book( array $row, $source ) {
	/**
	 * Filters an import row from any source.
	 *
	 * @since 0.1.0
	 * @param array  $row    Import row.
	 * @param string $source Import source.
	 */
	$row = apply_filters( 'lumen_catalog_import_row', $row, $source );

	/**
	 * Filters an import row from one source only. The dynamic part, `$source`, is the import source.
	 *
	 * @since 0.1.0
	 * @param array $row Import row.
	 */
	$row = apply_filters( "lumen_catalog_import_row_{$source}", $row );

	$post_id = wp_insert_post(
		array(
			'post_type'   => 'lp_book',
			'post_status' => 'publish',
			'post_title'  => sanitize_text_field( $row['title'] ?? '' ),
			'meta_input'  => array(
				'lp_isbn'  => sanitize_text_field( $row['isbn'] ?? '' ),
				'lp_pages' => absint( $row['pages'] ?? 0 ),
			),
		),
		true
	);

	if ( ! is_wp_error( $post_id ) ) {
		/**
		 * Fires after a book has been imported.
		 *
		 * @since 0.1.0
		 * @param int    $post_id New book ID.
		 * @param array  $row     Import row, after the filters.
		 * @param string $source  Import source.
		 */
		do_action( 'lumen_catalog_book_imported', $post_id, $row, $source );
	}

	return $post_id;
}

// The distributor sends ISBNs without hyphens and titles in capitals; only its rows are touched.
add_filter(
	'lumen_catalog_import_row_distributor',
	static function ( array $row ) {
		$row['isbn']  = preg_replace( '/[^0-9X]/', '', strtoupper( $row['isbn'] ?? '' ) );
		$row['title'] = ucwords( strtolower( $row['title'] ?? '' ) );
		return $row;
	}
);

// Add a row to the details box; 2 accepted arguments because the callback needs the book ID.
add_filter(
	'lumen_catalog_book_details_rows',
	static function ( array $rows, $post_id ) {
		$series = get_the_term_list( $post_id, 'lp_series', '', ', ' );
		if ( is_string( $series ) && '' !== $series ) {
			$rows[ __( 'Series', 'lumen-catalog' ) ] = wp_strip_all_tags( $series );
		}
		return $rows;
	},
	10,
	2
);

// React to an import: 3 accepted arguments; the return value of an action is ignored.
add_action(
	'lumen_catalog_book_imported',
	static function ( $post_id, array $row, $source ) {
		error_log( sprintf( 'Imported book %d (%s) from %s', $post_id, $row['isbn'] ?? '', $source ) );
	},
	10,
	3
);

wp eval '
$id = lumen_catalog_import_book( array( "title" => "WINTER ORCHARD", "isbn" => "978-0-306-40615-7", "pages" => "248" ), "distributor" );
echo get_the_title( $id ), " | ", get_post_meta( $id, "lp_isbn", true ), PHP_EOL;
$id = lumen_catalog_import_book( array( "title" => "Harbour Lights", "isbn" => "978-1-56619-909-4" ), "csv" );
echo get_the_title( $id ), " | ", get_post_meta( $id, "lp_isbn", true ), PHP_EOL;
echo did_action( "lumen_catalog_book_imported" ), " imports, filter applied ", did_filter( "lumen_catalog_import_row" ), " times", PHP_EOL;
'

Winter Orchard | 9780306406157
Harbour Lights | 978-1-56619-909-4
2 imports, filter applied 2 times

<?php
defined( 'ABSPATH' ) || exit;

add_action( 'save_post_lp_book', 'lumen_catalog_default_excerpt', 10, 3 );

/**
 * Fills an empty excerpt from the first words of the content when a book is saved.
 *
 * @param int     $post_id Book ID.
 * @param WP_Post $post    Book object.
 * @param bool    $update  Whether an existing book was updated.
 */
function lumen_catalog_default_excerpt( $post_id, $post, $update ) {
	if ( wp_is_post_revision( $post_id ) || wp_is_post_autosave( $post_id ) || '' !== $post->post_excerpt ) {
		return;
	}

	// wp_update_post() fires save_post_lp_book again: detach first, or the callback calls itself forever.
	remove_action( 'save_post_lp_book', 'lumen_catalog_default_excerpt', 10 );
	wp_update_post(
		array(
			'ID'           => $post_id,
			'post_excerpt' => wp_trim_words( wp_strip_all_tags( $post->post_content ), 20 ),
		)
	);
	add_action( 'save_post_lp_book', 'lumen_catalog_default_excerpt', 10, 3 );
}

id=$(wp post create --post_type=lp_book --post_title="Tide Tables" --post_status=publish --porcelain \
  --post_content="Two sisters keep the tide tables of a small harbour town and discover that the sea is keeping a record of its own.")
wp post get "$id" --field=post_excerpt

wp eval '
add_filter( "lumen_catalog_import_row", function ( $row ) { echo current_filter(), " ", var_export( doing_filter( "lumen_catalog_import_row" ), true ), PHP_EOL; return $row; } );
add_action( "lumen_catalog_book_imported", function () { echo current_filter(), " ", var_export( doing_filter( "lumen_catalog_import_row" ), true ), " ", var_export( doing_action(), true ), PHP_EOL; } );
lumen_catalog_import_book( array( "title" => "Salt Roads" ), "csv" );
echo did_action( "init" ), " ", did_action( "wp" ), " ", var_export( doing_filter(), true ), PHP_EOL;'

lumen_catalog_import_row true
lumen_catalog_book_imported false true
1 0 false

<?php
/**
 * Plugin Name: Lumen Hook Log
 * Description: Logs the first firing of each action (and of matching filters) in one request. Local only.
 */
defined( 'ABSPATH' ) || exit;

// LUMEN_HOOK_LOG: true logs actions; a regular expression also logs matching filters, shown in [brackets].
if ( 'local' !== wp_get_environment_type() || ! defined( 'LUMEN_HOOK_LOG' ) || ! LUMEN_HOOK_LOG ) {
	return;
}

$GLOBALS['lumen_hook_log'] = array();

add_action(
	'all',
	static function ( $hook_name ) {
		static $actions_seen = array();
		$log                 = &$GLOBALS['lumen_hook_log'];

		// do_action() counts the hook in $wp_actions before it calls 'all'; apply_filters() does not.
		$count                      = did_action( $hook_name );
		$is_action                  = $count > ( $actions_seen[ $hook_name ] ?? 0 );
		$actions_seen[ $hook_name ] = $count;

		if ( $is_action ) {
			$log[ $hook_name ] = $log[ $hook_name ] ?? $hook_name;
		} elseif ( is_string( LUMEN_HOOK_LOG ) && preg_match( LUMEN_HOOK_LOG, $hook_name ) ) {
			$log[ $hook_name ] = $log[ $hook_name ] ?? "[{$hook_name}]";
		}
	}
);

add_action(
	'shutdown',
	static function () {
		$uri = isset( $_SERVER['REQUEST_URI'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : '';
		error_log( "Hooks for {$uri}:" . PHP_EOL . wordwrap( implode( ' ', $GLOBALS['lumen_hook_log'] ), 116 ) );
	},
	PHP_INT_MAX
);

<?php
/**
 * Plugin Name: Lumen Mail Log
 * Description: Writes outgoing mail to the debug log instead of sending it (local environments only).
 */
defined( 'ABSPATH' ) || exit;

if ( 'local' !== wp_get_environment_type() ) {
	return;
}

// A filter, not a replacement of the pluggable wp_mail(): any other plugin can still hook mail.
add_filter(
	'pre_wp_mail',
	static function ( $short_circuit, array $atts ) {
		$to = implode( ', ', (array) $atts['to'] );
		error_log( sprintf( 'Mail not sent (local): to=%s subject="%s"', $to, $atts['subject'] ) );
		return true; // Any non-null value stops wp_mail() and becomes its return value.
	},
	10,
	2
);