Plugin Best Practices

<?php
namespace Acme\Events;

defined( 'ABSPATH' ) || exit;

// The namespace prefixes the class. It does NOT prefix any of these strings -
// they all end up as literal values in wp_options, wp_postmeta and the hook
// registry, where every plugin on the site shares one keyspace.

update_option( 'acme_events_settings', $settings );          // not 'settings'
set_transient( 'acme_events_feed', $feed, HOUR_IN_SECONDS ); // not 'feed'

// Leading underscore hides the meta key from the custom fields UI.
update_post_meta( $post_id, '_acme_events_starts_at', $timestamp );

// Custom hooks are part of the public API, so name them as carefully as
// a function: prefix, subject, verb.
$events = apply_filters( 'acme_events_query_results', $events, $atts );
do_action( 'acme_events_after_import', $imported_ids );

// register_post_type() rejects a key over 20 characters and
// register_taxonomy() one over 32, both with a WP_Error and a
// _doing_it_wrong() notice added in 4.2. Budget for the prefix.
register_post_type( 'acme_event', $args );                    // 10 characters
// register_taxonomy( string $taxonomy, array|string $object_type, array|string $args = array() )
// $object_type is required and comes second - $args is the THIRD argument.
register_taxonomy( 'acme_event_type', 'acme_event', $args );  // 15 characters

<?php
namespace Acme\Events;

defined( 'ABSPATH' ) || exit;

final class Shortcode {

	private Repository $repository;

	// Dependencies arrive through the constructor, not from a global.
	public function __construct( ?Repository $repository = null ) {
		$this->repository = $repository ?? new Repository();
	}

	public function register_hooks(): void {
		// The instance is captured by the callback, so nothing needs to find it later.
		add_action( 'init', array( $this, 'register_shortcode' ) );
	}

	public function register_shortcode(): void {
		add_shortcode( 'acme_events', array( $this, 'render' ) );
	}

	public function render( $atts, $content = null, $tag = '' ): string {
		$atts   = shortcode_atts( array( 'limit' => 3 ), $atts, $tag );
		$events = $this->repository->upcoming( absint( $atts['limit'] ) );

		/**
		 * Filters the events about to be rendered.
		 *
		 * This is how another plugin extends us - not by reaching into a global.
		 *
		 * @param WP_Post[] $events Events to render.
		 * @param array     $atts   Resolved shortcode attributes.
		 */
		$events = apply_filters( 'acme_events_shortcode_events', $events, $atts );

		return $this->to_html( $events );
	}
}

// Not this: any plugin loading later can replace it, and no test can swap it out.
// global $acme_events;
// $acme_events = new Shortcode();

<?php
namespace Acme\Events;

defined( 'ABSPATH' ) || exit;

// Called from an 'init' callback or later, never at file scope: WordPress 6.7
// warns when a translation function runs before init.
function notice_text( int $count, string $name ): string {

	// _n( $single, $plural, $number, $domain ) picks the form for $number.
	// The translators comment must sit immediately above the call.
	/* translators: 1: number of events, 2: calendar name. */
	$template = _n(
		'%1$d event imported from %2$s.',
		'%1$d events imported from %2$s.',
		$count,
		'acme-events'
	);

	// Numbered placeholders, so a translator may reorder them.
	return sprintf( $template, $count, $name );
}

// Escape at the point of output, choosing the helper for the context.
echo '<p>' . esc_html( notice_text( 3, 'Acme Calendar' ) ) . '</p>';
printf( '<a href="%s">%s</a>', esc_url( $url ), esc_html__( 'View all events', 'acme-events' ) );
printf( '<input placeholder="%s" />', esc_attr__( 'Search events', 'acme-events' ) );

// The domain must be a literal. None of these are extractable:
//   __( 'Save', $domain );
//   __( 'Save', ACME_TEXT_DOMAIN );
//   __( $label, 'acme-events' );