gutenberg / lib / experimental / guidelines / guidelines.php

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

205 lines 6.1 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	'memory' => array(
54	'title' => __( 'Memory', 'gutenberg' ),
55	),
56	)
57	);
58	}
59	}
60
61	if ( ! function_exists( '_wp_guidelines_ensure_default_type_term' ) ) {
62	/**
63	* Hook callback for the `save_post_wp_guideline` action that assigns the
64	* `artifact` fallback term when a guideline is saved without a type term.
65	*
66	* Uses `get_the_terms()` so the check is served by the object term cache.
67	*
68	* @access private
69	*
70	* @param int $post_id Saved post ID.
71	*/
72	function _wp_guidelines_ensure_default_type_term( int $post_id ): void {
73	if ( wp_is_post_revision( $post_id ) ) {
74	return;
75	}
76
77	$terms = get_the_terms( $post_id, 'wp_guideline_type' );
78	if ( is_wp_error( $terms ) \|\| ! empty( $terms ) ) {
79	return;
80	}
81
82	// Resolve to an ID up front (creating the term on first use):
83	// wp_set_object_terms() interprets strings as names for hierarchical
84	// taxonomies, not slugs.
85	$term = term_exists( 'artifact', 'wp_guideline_type' );
86	if ( ! $term ) {
87	$term = wp_insert_term( 'artifact', 'wp_guideline_type' );
88	if ( is_wp_error( $term ) ) {
89	return;
90	}
91	}
92
93	wp_set_object_terms( $post_id, (int) $term['term_id'], 'wp_guideline_type' );
94	}
95	}
96
97	if ( ! function_exists( '_wp_guidelines_synthesize_caps' ) ) {
98	/**
99	* Hook callback for the `user_has_cap` filter that grants guideline
100	* capabilities based on the user's role, post ownership, and post status.
101	*
102	* Administrators get every guideline capability. Contributors, Authors,
103	* and Editors can list and create guidelines, and fully manage their own
104	* private rows. Publishing guidelines and acting on other users' rows is
105	* reserved for Administrators.
106	*
107	* @access private
108	*
109	* @param array $allcaps All capabilities of the user.
110	* @param array $caps Required primitive capabilities for the requested capability.
111	* @param array $args Arguments that accompany the requested capability check.
112	* @param WP_User $user The user object.
113	* @return array Possibly augmented capabilities.
114	*/
115	function _wp_guidelines_synthesize_caps( array $allcaps, array $caps, array $args, WP_User $user ): array {
116	if ( ! empty( $allcaps['manage_options'] ) ) {
117	$allcaps['read_guidelines'] = true;
118	$allcaps['edit_guidelines'] = true;
119	$allcaps['edit_others_guidelines'] = true;
120	$allcaps['edit_published_guidelines'] = true;
121	$allcaps['edit_private_guidelines'] = true;
122	$allcaps['publish_guidelines'] = true;
123	$allcaps['delete_guidelines'] = true;
124	$allcaps['delete_others_guidelines'] = true;
125	$allcaps['delete_published_guidelines'] = true;
126	$allcaps['delete_private_guidelines'] = true;
127	$allcaps['read_private_guidelines'] = true;
128	return $allcaps;
129	}
130
131	if ( empty( $allcaps['edit_posts'] ) ) {
132	return $allcaps;
133	}
134
135	// Ambient floor for Contributor+: `read_guidelines` clears the
136	// post-type read check; `edit_guidelines` clears the create and
137	// ownership checks that don't pass a post ID. Per-post primitives
138	// are granted only in the per-post branch below.
139	$allcaps['read_guidelines'] = true;
140	$allcaps['edit_guidelines'] = true;
141
142	if ( ! isset( $args[0], $args[2] ) ) {
143	return $allcaps;
144	}
145
146	if ( ! in_array( $args[0], array( 'edit_post', 'delete_post', 'read_post' ), true ) ) {
147	return $allcaps;
148	}
149
150	$post = get_post( $args[2] );
151	if (
152	! $post instanceof WP_Post \|\|
153	'wp_guideline' !== $post->post_type \|\|
154	(int) $post->post_author !== (int) $user->ID \|\|
155	'private' !== $post->post_status
156	) {
157	return $allcaps;
158	}
159
160	$allcaps['edit_private_guidelines'] = true;
161	$allcaps['delete_guidelines'] = true;
162	$allcaps['delete_private_guidelines'] = true;
163	$allcaps['read_private_guidelines'] = true;
164
165	return $allcaps;
166	}
167	}
168
169	if ( ! function_exists( '_wp_guidelines_maybe_map_term_label' ) ) {
170	/**
171	* Hook callback for the `wp_insert_term_data` filter that swaps a
172	* raw guideline-type slug for its human-readable label when WordPress
173	* is about to lazily create the term.
174	*
175	* When `wp_set_object_terms()` is called with a slug that doesn't yet
176	* exist, `wp_insert_term()` fires and the filter runs after WP has
177	* computed both `name` and `slug`. A `name` equal to `slug` indicates
178	* the term was created from a raw slug (e.g. by `wp_set_object_terms()`)
179	* rather than from a user-provided label, so the label is replaced with
180	* the title from `wp_guideline_types()`.
181	*
182	* @access private
183	*
184	* @param array $data Term data to be inserted (keyed by column name).
185	* @param string $taxonomy Taxonomy slug.
186	* @return array Possibly modified term data.
187	*/
188	function _wp_guidelines_maybe_map_term_label( array $data, string $taxonomy ): array {
189	if ( 'wp_guideline_type' !== $taxonomy ) {
190	return $data;
191	}
192
193	if ( $data['name'] !== $data['slug'] ) {
194	return $data;
195	}
196
197	$types = wp_guideline_types();
198	if ( isset( $types[ $data['slug'] ] ) ) {
199	$data['name'] = $types[ $data['slug'] ]['title'];
200	}
201
202	return $data;
203	}
204	}
205