WP_Speculation_Rules::add_rule( string $mode, string $id,  $rule ): bool

Source

public function add_rule( string $mode, string $id, array $rule ): bool {
	if ( ! self::is_valid_mode( $mode ) ) {
		_doing_it_wrong(
			__METHOD__,
			sprintf(
				/* translators: %s: invalid mode value */
				__( 'The value "%s" is not a valid speculation rules mode.' ),
				esc_html( $mode )
			),
			'6.8.0'
		);
		return false;
	}

	if ( ! $this->is_valid_id( $id ) ) {
		_doing_it_wrong(
			__METHOD__,
			sprintf(
				/* translators: %s: invalid ID value */
				__( 'The value "%s" is not a valid ID for a speculation rule.' ),
				esc_html( $id )
			),
			'6.8.0'
		);
		return false;
	}

	if ( $this->has_rule( $mode, $id ) ) {
		_doing_it_wrong(
			__METHOD__,
			sprintf(
				/* translators: %s: invalid ID value */
				__( 'A speculation rule with ID "%s" already exists.' ),
				esc_html( $id )
			),
			'6.8.0'
		);
		return false;
	}

	/*
	 * Perform some basic speculation rule validation.
	 * Every rule must have either a 'where' key or a 'urls' key, but not both.
	 * The presence of a 'where' key implies a 'source' of 'document', while the presence of a 'urls' key implies
	 * a 'source' of 'list'.
	 */
	if (
		( ! isset( $rule['where'] ) && ! isset( $rule['urls'] ) ) ||
		( isset( $rule['where'] ) && isset( $rule['urls'] ) )
	) {
		_doing_it_wrong(
			__METHOD__,
			sprintf(
				/* translators: 1: allowed key, 2: alternative allowed key */
				__( 'A speculation rule must include either a "%1$s" key or a "%2$s" key, but not both.' ),
				'where',
				'urls'
			),
			'6.8.0'
		);
		return false;
	}
	if ( isset( $rule['source'] ) ) {
		if ( ! self::is_valid_source( $rule['source'] ) ) {
			_doing_it_wrong(
				__METHOD__,
				sprintf(
					/* translators: %s: invalid source value */
					__( 'The value "%s" is not a valid source for a speculation rule.' ),
					esc_html( $rule['source'] )
				),
				'6.8.0'
			);
			return false;
		}

		if ( 'list' === $rule['source'] && isset( $rule['where'] ) ) {
			_doing_it_wrong(
				__METHOD__,
				sprintf(
					/* translators: 1: source value, 2: forbidden key */
					__( 'A speculation rule of source "%1$s" must not include a "%2$s" key.' ),
					'list',
					'where'
				),
				'6.8.0'
			);
			return false;
		}

		if ( 'document' === $rule['source'] && isset( $rule['urls'] ) ) {
			_doing_it_wrong(
				__METHOD__,
				sprintf(
					/* translators: 1: source value, 2: forbidden key */
					__( 'A speculation rule of source "%1$s" must not include a "%2$s" key.' ),
					'document',
					'urls'
				),
				'6.8.0'
			);
			return false;
		}
	}

	// If there is an 'eagerness' key specified, make sure it's valid.
	if ( isset( $rule['eagerness'] ) ) {
		if ( ! self::is_valid_eagerness( $rule['eagerness'] ) ) {
			_doing_it_wrong(
				__METHOD__,
				sprintf(
					/* translators: %s: invalid eagerness value */
					__( 'The value "%s" is not a valid eagerness for a speculation rule.' ),
					esc_html( $rule['eagerness'] )
				),
				'6.8.0'
			);
			return false;
		}

		if ( isset( $rule['where'] ) && 'immediate' === $rule['eagerness'] ) {
			_doing_it_wrong(
				__METHOD__,
				sprintf(
					/* translators: %s: forbidden eagerness value */
					__( 'The eagerness value "%s" is forbidden for document-level speculation rules.' ),
					'immediate'
				),
				'6.8.0'
			);
			return false;
		}
	}

	if ( ! isset( $this->rules_by_mode[ $mode ] ) ) {
		$this->rules_by_mode[ $mode ] = array();
	}

	$this->rules_by_mode[ $mode ][ $id ] = $rule;
	return true;
}

View all references View on Trac View on GitHub