gutenberg / lib / experimental / guidelines / guidelines.php

guidelines.php in Gutenberg 23.2.2, at lib/experimental/guidelines/guidelines.php

131 lines 3.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Guidelines public API.
4	*
5	* @package gutenberg
6	*/
7
8	if ( ! defined( 'ABSPATH' ) ) {
9	exit;
10	}
11
12	if ( ! function_exists( 'wp_guideline_types' ) ) {
13	/**
14	* Returns the registered guideline types keyed by slug.
15	*
16	* Plugins can register their own types via the `wp_guideline_types` filter.
17	*
18	* @return array {
19	* Slug-keyed map of guideline types.
20	*
21	* @type array ...$0 {
22	* Data for a single guideline type.
23	*
24	* @type string $title The human-readable label for the type.
25	* }
26	* }
27	* @phpstan-return array<string, array{title: string}>
28	*/
29	function wp_guideline_types(): array {
30	/**
31	* Filters the guideline types available on this site.
32	*
33	* @param array $types {
34	* Slug-keyed map of guideline types.
35	*
36	* @type array ...$0 {
37	* Data for a single guideline type.
38	*
39	* @type string $title The human-readable label for the type.
40	* }
41	* }
42	* @phpstan-param array<string, array{title: string}> $types
43	*/
44	return apply_filters(
45	'wp_guideline_types',
46	array(
47	'artifact' => array(
48	'title' => __( 'Artifact', 'gutenberg' ),
49	),
50	'content' => array(
51	'title' => __( 'Content', 'gutenberg' ),
52	),
53	)
54	);
55	}
56	}
57
58	if ( ! function_exists( '_wp_guidelines_ensure_default_type_term' ) ) {
59	/**
60	* Hook callback for the `save_post_wp_guideline` action that assigns the
61	* `artifact` fallback term when a guideline is saved without a type term.
62	*
63	* Uses `get_the_terms()` so the check is served by the object term cache.
64	*
65	* @access private
66	*
67	* @param int $post_id Saved post ID.
68	*/
69	function _wp_guidelines_ensure_default_type_term( int $post_id ): void {
70	if ( wp_is_post_revision( $post_id ) ) {
71	return;
72	}
73
74	$terms = get_the_terms( $post_id, 'wp_guideline_type' );
75	if ( is_wp_error( $terms ) \|\| ! empty( $terms ) ) {
76	return;
77	}
78
79	// wp_set_object_terms() expects term IDs for hierarchical taxonomies —
80	// strings are interpreted as term names, not slugs. Resolve 'artifact'
81	// to an ID up front (creating the term on first use) so we assign the
82	// exact term we mean instead of relying on name-based lookup.
83	$term = term_exists( 'artifact', 'wp_guideline_type' );
84	if ( ! $term ) {
85	$term = wp_insert_term( 'artifact', 'wp_guideline_type' );
86	if ( is_wp_error( $term ) ) {
87	return;
88	}
89	}
90
91	wp_set_object_terms( $post_id, (int) $term['term_id'], 'wp_guideline_type' );
92	}
93	}
94
95	if ( ! function_exists( '_wp_guidelines_maybe_map_term_label' ) ) {
96	/**
97	* Hook callback for the `wp_insert_term_data` filter that swaps a
98	* raw guideline-type slug for its human-readable label when WordPress
99	* is about to lazily create the term.
100	*
101	* When `wp_set_object_terms()` is called with a slug that doesn't yet
102	* exist, `wp_insert_term()` fires and the filter runs after WP has
103	* computed both `name` and `slug`. A `name` equal to `slug` indicates
104	* the term was created from a raw slug (e.g. by `wp_set_object_terms()`)
105	* rather than from a user-provided label, so the label is replaced with
106	* the title from `wp_guideline_types()`.
107	*
108	* @access private
109	*
110	* @param array $data Term data to be inserted (keyed by column name).
111	* @param string $taxonomy Taxonomy slug.
112	* @return array Possibly modified term data.
113	*/
114	function _wp_guidelines_maybe_map_term_label( array $data, string $taxonomy ): array {
115	if ( 'wp_guideline_type' !== $taxonomy ) {
116	return $data;
117	}
118
119	if ( $data['name'] !== $data['slug'] ) {
120	return $data;
121	}
122
123	$types = wp_guideline_types();
124	if ( isset( $types[ $data['slug'] ] ) ) {
125	$data['name'] = $types[ $data['slug'] ]['title'];
126	}
127
128	return $data;
129	}
130	}
131