← All changes | includes/class-recommendations.php +168 -0 1.3.2 → 1.4.0 View file →

		@@ -23,8 +23,22 @@
23	23
24	24	final class Recommendations {
25	25
26	26	/**
	27	+ * Bounds on what `xspeed_recommendations` may add.
	28	+ *
	29	+ * The list renders in the Overview card and the cache page's next-best
	30	+ * action, and the REST route returns it as is. The caps are well above any
	31	+ * honest use and keep a buggy contributor from flooding either screen.
	32	+ */
	33	+ private const MAX_CONTRIBUTED = 5;
	34	+ private const MAX_TITLE_LEN = 120;
	35	+ private const MAX_DETAIL_LEN = 400;
	36	+ private const MAX_LABEL_LEN = 40;
	37	+ private const MAX_TAG_LEN = 24;
	38	+ private const FILTER = 'xspeed_recommendations';
	39	+
	40	+ /**
27	41	* Evaluate all rules against a state snapshot. Pure — unit-tested.
28	42	*
29	43	* @param array $state See state() for the shape.
30	44	* @return array<int,array{id:string,priority:int,title:string,detail:string,action:array<string,mixed>}>
		@@ -228,8 +242,162 @@
228	242
229	243	/** Ranked recommendations for the live site. */
230	244	public static function all(): array {
231	245	return self::evaluate( self::state() );
	246	+ }
	247	+
	248	+ /**
	249	+ * The live list with add-on entries folded in, for the Overview card.
	250	+ *
	251	+ * Kept apart from all() on purpose. all() feeds the cache page's next best
	252	+ * action, `wp xspeed recommend` and apply(), which answer "what should I
	253	+ * fix on this site"; an add-on's entry can be an offer, and an offer must
	254	+ * not take the slot of the site's real next fix or read as one in the CLI.
	255	+ */
	256	+ public static function all_with_contributed(): array {
	257	+ $state = self::state();
	258	+ return self::with_contributed( self::evaluate( $state ), $state );
	259	+ }
	260	+
	261	+ /**
	262	+ * Add the entries other plugins contribute, then re-rank.
	263	+ *
	264	+ * Contributors may only add. The filter starts from an empty array and
	265	+ * gets the native list as read-only context, so nothing it returns can
	266	+ * remove or rewrite a native entry, and an id a native rule already uses
	267	+ * is dropped rather than replacing it. Only `link` actions are accepted:
	268	+ * an `apply` action would POST to an endpoint that cannot resolve an id it
	269	+ * does not own (that is what `xspeed_apply_recommendation` is for).
	270	+ *
	271	+ * @param array<int,array<string,mixed>> $native Ranked native entries.
	272	+ * @param array<string,mixed> $state What the rules read, as context.
	273	+ * @return array<int,array<string,mixed>> Native and contributed, ranked.
	274	+ */
	275	+ public static function with_contributed( array $native, array $state ): array {
	276	+ /**
	277	+ * Filter: xspeed_recommendations
	278	+ *
	279	+ * Extra recommendations for the Overview card. Starts empty; append
	280	+ * entries and return the array.
	281	+ *
	282	+ * Each entry: id (string, required, unique), title (string, required),
	283	+ * detail (string, required, one or two sentences, no markup), priority
	284	+ * (int 0-100, lower ranks first, default 50), tag (string, optional, a
	285	+ * short label such as "Add-on" shown beside the title) and action
	286	+ * (required: `type` 'link', `label`, `module` slug, optional `subtab`
	287	+ * and `focus`). Anything else is dropped.
	288	+ *
	289	+ * @param array $contributed Contributed entries (empty on entry).
	290	+ * @param array $native The native entries, as context.
	291	+ * @param array $state What the native rules read, as context.
	292	+ */
	293	+ $depth = isset( $GLOBALS['wp_current_filter'] ) && is_array( $GLOBALS['wp_current_filter'] )
	294	+ ? count( $GLOBALS['wp_current_filter'] )
	295	+ : 0;
	296	+ try {
	297	+ $raw = apply_filters( self::FILTER, array(), $native, $state );
	298	+ } catch ( \Throwable $e ) {
	299	+ // A contributor that throws costs the round its contributions,
	300	+ // not the card. apply_filters() leaves our name on the
	301	+ // current-filter stack when a callback throws, plus any filter
	302	+ // the contributor ran itself, so cut back to where it was.
	303	+ if ( isset( $GLOBALS['wp_current_filter'] ) && is_array( $GLOBALS['wp_current_filter'] ) ) {
	304	+ array_splice( $GLOBALS['wp_current_filter'], $depth );
	305	+ }
	306	+ if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
	307	+ // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
	308	+ error_log( '[xspeed] xspeed_recommendations contributor threw: ' . $e->getMessage() );
	309	+ }
	310	+ return $native;
	311	+ }
	312	+ if ( ! is_array( $raw ) || empty( $raw ) ) {
	313	+ return $native;
	314	+ }
	315	+
	316	+ $taken = array();
	317	+ foreach ( $native as $rec ) {
	318	+ $taken[ (string) ( $rec['id'] ?? '' ) ] = true;
	319	+ }
	320	+
	321	+ $out = $native;
	322	+ $added = 0;
	323	+ foreach ( $raw as $row ) {
	324	+ if ( $added >= self::MAX_CONTRIBUTED ) {
	325	+ break;
	326	+ }
	327	+ $entry = self::normalise_contributed( $row );
	328	+ if ( null === $entry || isset( $taken[ $entry['id'] ] ) ) {
	329	+ continue;
	330	+ }
	331	+ $taken[ $entry['id'] ] = true;
	332	+ $out[] = $entry;
	333	+ ++$added;
	334	+ }
	335	+
	336	+ // Ties keep their position, so a contribution never jumps a native
	337	+ // entry it ties with. PHP 7.4's sort is not stable, hence the index.
	338	+ $order = array_flip( array_keys( $out ) );
	339	+ uksort(
	340	+ $out,
	341	+ static function ( $a, $b ) use ( $out, $order ) {
	342	+ return array( $out[ $a ]['priority'], $order[ $a ] ) <=> array( $out[ $b ]['priority'], $order[ $b ] );
	343	+ }
	344	+ );
	345	+ return array_values( $out );
	346	+ }
	347	+
	348	+ /**
	349	+ * One contributed entry in the native shape, or null when it is unusable.
	350	+ *
	351	+ * @param mixed $row What the contributor returned.
	352	+ * @return array<string,mixed>|null
	353	+ */
	354	+ private static function normalise_contributed( $row ): ?array {
	355	+ if ( ! is_array( $row ) ) {
	356	+ return null;
	357	+ }
	358	+ $text = static function ( $value, int $max ): string {
	359	+ if ( ! is_string( $value ) ) {
	360	+ return '';
	361	+ }
	362	+ $value = trim( wp_strip_all_tags( $value ) );
	363	+ return function_exists( 'mb_substr' ) ? mb_substr( $value, 0, $max ) : substr( $value, 0, $max );
	364	+ };
	365	+
	366	+ $id = is_string( $row['id'] ?? null ) ? sanitize_key( $row['id'] ) : '';
	367	+ $title = $text( $row['title'] ?? null, self::MAX_TITLE_LEN );
	368	+ $detail = $text( $row['detail'] ?? null, self::MAX_DETAIL_LEN );
	369	+ $action = is_array( $row['action'] ?? null ) ? $row['action'] : array();
	370	+ $label = $text( $action['label'] ?? null, self::MAX_LABEL_LEN );
	371	+ $module = is_string( $action['module'] ?? null ) ? sanitize_key( $action['module'] ) : '';
	372	+ if ( '' === $id || '' === $title || '' === $detail || 'link' !== ( $action['type'] ?? '' ) || '' === $label || '' === $module ) {
	373	+ return null;
	374	+ }
	375	+
	376	+ $link = array(
	377	+ 'type' => 'link',
	378	+ 'label' => $label,
	379	+ 'module' => $module,
	380	+ );
	381	+ foreach ( array( 'subtab', 'focus' ) as $key ) {
	382	+ if ( is_string( $action[ $key ] ?? null ) && '' !== $action[ $key ] ) {
	383	+ $link[ $key ] = $text( $action[ $key ], 80 );
	384	+ }
	385	+ }
	386	+
	387	+ $entry = array(
	388	+ 'id' => $id,
	389	+ // (int) 'high' is 0, which would rank the entry above every native fix.
	390	+ 'priority' => is_numeric( $row['priority'] ?? null ) ? max( 0, min( 100, (int) $row['priority'] ) ) : 50,
	391	+ 'title' => $title,
	392	+ 'detail' => $detail,
	393	+ 'action' => $link,
	394	+ );
	395	+ $tag = $text( $row['tag'] ?? null, self::MAX_TAG_LEN );
	396	+ if ( '' !== $tag ) {
	397	+ $entry['tag'] = $tag;
	398	+ }
	399	+ return $entry;
232	400	}
233	401
234	402	/**
235	403	* One-click apply: re-evaluate, find the recommendation, and run its