# activitypub/9.2.0/includes/cli/class-blurhash-command.php

ActivityPub, version 9.2.0. 273 lines.

- Page: https://pluginprobe.com/plugins/activitypub/9.2.0/code/includes/cli/class-blurhash-command.php
- Raw: https://pluginprobe.com/plugins/activitypub/9.2.0/raw/includes/cli/class-blurhash-command.php
- Modified: 2026-07-22T15:59:20+00:00

Line numbers below start at 1. Link to a line or a range by appending a fragment to the
page URL, for example `https://pluginprobe.com/plugins/activitypub/9.2.0/code/includes/cli/class-blurhash-command.php#L10-L20`.

```php
<?php
/**
 * WP-CLI commands for the Blurhash encoder.
 *
 * @package Activitypub
 */

namespace Activitypub\Cli;

use Activitypub\Blurhash;

/**
 * `wp activitypub blurhash …` command surface for backfilling and managing
 * stored blurhash placeholders.
 *
 * The runtime path ({@see Blurhash}) covers new uploads via a cron
 * event; this command exists for two cases the runtime can't handle:
 *
 *   1. **First install on a site with existing media** — every
 *      already-uploaded image attachment is missing the postmeta and
 *      will never get it without a re-upload or a forced re-encode.
 *      `wp activitypub blurhash backfill` walks the library and fills the
 *      gap.
 *   2. **Re-encode after an algorithm change** — if the encoder's
 *      components or source-size change, the previously-computed
 *      hashes are stale (still decodable, but produced from a
 *      different recipe). `--force` recomputes against the latest
 *      bytes.
 *
 * Registration is gated on `WP_CLI` so the class is only loaded by
 * the CLI process — no overhead on web requests.
 */
class Blurhash_Command extends \WP_CLI_Command {

	/**
	 * WP_Query page size for the backfill walk. 100 is the same batch
	 * size WP's own bulk operations default to and keeps each query's
	 * working set bounded.
	 *
	 * @var int
	 */
	private const PAGE_SIZE = 100;

	/**
	 * Compute and persist Blurhash placeholders for image
	 * attachments missing one. Use after first install on a site
	 * with existing media, or after an encoder change with --force.
	 *
	 * Default mode walks only attachments that have no stored
	 * `_activitypub_blurhash` — already-encoded media is filtered out
	 * server-side via a `NOT EXISTS` meta query rather than fetched
	 * and skipped in PHP. Combined with `--limit`, this means a
	 * limit of N processes exactly N candidates (the prior behavior
	 * counted already-hashed attachments against the limit and could
	 * never advance past a fully-encoded first page).
	 *
	 * `--force` drops the meta-query filter and walks every image
	 * attachment in ID order. The existing hash is overwritten only
	 * after the new encode succeeds, so a failed re-encode leaves
	 * the prior good hash in place.
	 *
	 * Non-raster `image/*` mime types (SVG, etc.) are recognized by
	 * `wp_attachment_is_image()` returning false and are counted as
	 * skipped, not failed — they're outside the encoder's GD-based
	 * scope by design.
	 *
	 * Exits nonzero when any encode failed, so automation can detect
	 * partial-success runs without parsing the summary text.
	 *
	 * ## OPTIONS
	 *
	 * [--dry-run]
	 * : Walk and report what would be encoded, but don't write postmeta.
	 *
	 * [--limit=<n>]
	 * : Process at most <n> candidate attachments. Default: 0 (no limit).
	 *
	 * [--force]
	 * : Re-encode attachments that already have a stored hash.
	 *
	 * ## EXAMPLES
	 *
	 *     wp activitypub blurhash backfill --dry-run
	 *     wp activitypub blurhash backfill --limit=100
	 *     wp activitypub blurhash backfill --force
	 *
	 * @param array<int, string>   $args       Positional CLI args (unused).
	 * @param array<string, mixed> $assoc_args Associative CLI flags.
	 *
	 * @when after_wp_load
	 */
	public function backfill( $args, $assoc_args ) {
		unset( $args );

		$dry_run = ! empty( $assoc_args['dry-run'] );
		$force   = ! empty( $assoc_args['force'] );
		$limit   = isset( $assoc_args['limit'] ) ? (int) $assoc_args['limit'] : 0;

		// Fail fast when the encoder can't run on this host.
		// Without this gate, the loop would emit a `\WP_CLI::warning`
		// per attachment and exit non-zero — noisy and unactionable.
		// `--dry-run` still works (no encoding attempted), so
		// operators can enumerate candidates from a GD-less host
		// to decide whether to migrate the media.
		if ( ! $dry_run && ! Blurhash::is_encoder_runnable() ) {
			\WP_CLI::error( 'Blurhash encoder requires GD (imagecreatefromstring/truecolor/scale). Install or enable GD and re-run.' );
			return;
		}

		$encoded = 0;
		$skipped = 0;
		$failed  = 0;
		$last_id = 0;

		while ( true ) {
			$query_args = array(
				'post_type'              => 'attachment',
				'post_status'            => 'inherit',
				'post_mime_type'         => 'image',
				'posts_per_page'         => self::PAGE_SIZE,
				'fields'                 => 'ids',
				'no_found_rows'          => true,
				'update_post_meta_cache' => false,
				'update_post_term_cache' => false,
				'orderby'                => 'ID',
				'order'                  => 'ASC',
			);

			// Default mode filters to candidates server-side, so we
			// never call `Blurhash::get()` per row in the loop (the
			// N+1 the prior pagination shape had). `--force` skips
			// the filter and walks everything in ID order.
			//
			// Candidate set is "key missing OR value empty". A
			// non-empty-but-malformed row (postmeta poisoning, a
			// truncated import) self-heals through the runtime
			// cron path because {@see Blurhash::get()} reports
			// malformed values as absent, so `run_encode()` will
			// re-compute on the next `wp_generate_attachment_metadata`
			// regen. Operators who need a one-shot rescue without
			// waiting for a regen run the command with `--force`.
			if ( ! $force ) {
				$query_args['meta_query'] = array( // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query -- one-shot CLI backfill; not a web-path query.
					'relation' => 'OR',
					array(
						'key'     => Blurhash::META_KEY,
						'compare' => 'NOT EXISTS',
					),
					array(
						'key'     => Blurhash::META_KEY,
						'value'   => '',
						'compare' => '=',
					),
				);
			}

			// Keyset pagination — `ID > $last_id` is stable under
			// concurrent inserts and deletes, so a long backfill can't
			// silently skip attachments the way offset pagination
			// (paged=N) does when rows shift mid-run.
			$where_filter = null;
			if ( $last_id > 0 ) {
				$where_filter = self::keyset_where( $last_id );
				\add_filter( 'posts_where', $where_filter, 10, 1 );
			}

			$query = new \WP_Query( $query_args );

			if ( null !== $where_filter ) {
				\remove_filter( 'posts_where', $where_filter, 10 );
			}

			if ( empty( $query->posts ) ) {
				break;
			}

			foreach ( $query->posts as $attachment_id ) {
				$attachment_id = (int) $attachment_id;
				$last_id       = $attachment_id;

				// Non-encodable mime types (SVG, ICO, anything
				// outside the GD raster set) get filtered out
				// up-front and counted as skipped, not failed. The
				// encoder would return null on them too, but a
				// per-attachment WARNING for every SVG on every
				// backfill run is noise; the user already knows we
				// don't encode vector formats.
				if ( ! Blurhash::is_encodable_attachment( $attachment_id ) ) {
					++$skipped;
					continue;
				}

				if ( $limit > 0 && ( $encoded + $failed ) >= $limit ) {
					break 2;
				}

				if ( $dry_run ) {
					++$encoded;
					\WP_CLI::log( "would encode: attachment {$attachment_id}" );
					continue;
				}

				$hash = Blurhash::encode_from_attachment( $attachment_id );

				/*
				 * `false` is a policy skip (e.g. declared dimensions
				 * over the decode-bomb cap) — same bucket as a
				 * non-raster mime, not a failure. Warning on it every
				 * run (and exiting nonzero) would make a permanently
				 * over-cap attachment poison automation forever.
				 */
				if ( false === $hash ) {
					++$skipped;
					\WP_CLI::log( "skipped (out of encode policy): attachment {$attachment_id}" );
					continue;
				}

				if ( null === $hash ) {
					++$failed;
					\WP_CLI::warning( "encode failed: attachment {$attachment_id}" );
					continue;
				}

				// Encode-then-set — never delete-first. A failed
				// re-encode on `--force` leaves the prior good hash
				// in place rather than wiping it.
				Blurhash::set( $attachment_id, $hash );
				++$encoded;
				\WP_CLI::log( "encoded {$attachment_id}: {$hash}" );
			}
		}

		$encoded_label = $dry_run ? 'would encode' : 'encoded';
		$summary       = \sprintf(
			'%s %d, skipped %d (non-raster, unsupported, or out of encode policy), failed %d.',
			$encoded_label,
			$encoded,
			$skipped,
			$failed
		);

		if ( $dry_run ) {
			\WP_CLI::success( '[dry-run] ' . $summary );
			return;
		}

		// Non-zero exit on any failure so automation can detect
		// partial-success runs without parsing the summary text.
		if ( $failed > 0 ) {
			\WP_CLI::error( $summary );
			return;
		}

		\WP_CLI::success( $summary );
	}

	/**
	 * Build a `posts_where` filter closure that constrains the
	 * query to `ID > $last_id`. Used to implement keyset pagination
	 * without polluting WP_Query's stable args. The closure clears
	 * itself after each query in {@see self::backfill()}.
	 *
	 * @param int $last_id Last processed attachment ID.
	 * @return \Closure
	 */
	private static function keyset_where( int $last_id ): \Closure {
		return function ( $where ) use ( $last_id ) {
			global $wpdb;
			return $where . $wpdb->prepare( " AND {$wpdb->posts}.ID > %d", $last_id );
		};
	}
}

```