[ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * REST API: WP_REST_Menu_Locations_Controller class 4 * 5 * @package WordPress 6 * @subpackage REST_API 7 * @since 5.9.0 8 */ 9 10 /** 11 * Core class used to access menu locations via the REST API. 12 * 13 * @since 5.9.0 14 * 15 * @see WP_REST_Controller 16 */ 17 class WP_REST_Menu_Locations_Controller extends WP_REST_Controller { 18 19 /** 20 * Menu Locations Constructor. 21 * 22 * @since 5.9.0 23 */ 24 public function __construct() { 25 $this->namespace = 'wp/v2'; 26 $this->rest_base = 'menu-locations'; 27 } 28 29 /** 30 * Registers the routes for the objects of the controller. 31 * 32 * @since 5.9.0 33 * 34 * @see register_rest_route() 35 */ 36 public function register_routes() { 37 register_rest_route( 38 $this->namespace, 39 '/' . $this->rest_base, 40 array( 41 array( 42 'methods' => WP_REST_Server::READABLE, 43 'callback' => array( $this, 'get_items' ), 44 'permission_callback' => array( $this, 'get_items_permissions_check' ), 45 'args' => $this->get_collection_params(), 46 ), 47 'schema' => array( $this, 'get_public_item_schema' ), 48 ) 49 ); 50 51 register_rest_route( 52 $this->namespace, 53 '/' . $this->rest_base . '/(?P<location>[\w-]+)', 54 array( 55 'args' => array( 56 'location' => array( 57 'description' => __( 'An alphanumeric identifier for the menu location.' ), 58 'type' => 'string', 59 ), 60 ), 61 array( 62 'methods' => WP_REST_Server::READABLE, 63 'callback' => array( $this, 'get_item' ), 64 'permission_callback' => array( $this, 'get_item_permissions_check' ), 65 'args' => array( 66 'context' => $this->get_context_param( array( 'default' => 'view' ) ), 67 ), 68 ), 69 'schema' => array( $this, 'get_public_item_schema' ), 70 ) 71 ); 72 } 73 74 /** 75 * Checks whether a given request has permission to read menu locations. 76 * 77 * @since 5.9.0 78 * 79 * @param WP_REST_Request $request Full details about the request. 80 * @return WP_Error|bool True if the request has read access, WP_Error object otherwise. 81 */ 82 public function get_items_permissions_check( $request ) { 83 if ( ! current_user_can( 'edit_theme_options' ) ) { 84 return new WP_Error( 85 'rest_cannot_view', 86 __( 'Sorry, you are not allowed to view menu locations.' ), 87 array( 'status' => rest_authorization_required_code() ) 88 ); 89 } 90 91 return true; 92 } 93 94 /** 95 * Retrieves all menu locations, depending on user context. 96 * 97 * @since 5.9.0 98 * 99 * @param WP_REST_Request $request Full details about the request. 100 * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure. 101 */ 102 public function get_items( $request ) { 103 $data = array(); 104 105 foreach ( get_registered_nav_menus() as $name => $description ) { 106 $location = new stdClass(); 107 $location->name = $name; 108 $location->description = $description; 109 110 $location = $this->prepare_item_for_response( $location, $request ); 111 $data[ $name ] = $this->prepare_response_for_collection( $location ); 112 } 113 114 return rest_ensure_response( $data ); 115 } 116 117 /** 118 * Checks if a given request has access to read a menu location. 119 * 120 * @since 5.9.0 121 * 122 * @param WP_REST_Request $request Full details about the request. 123 * @return WP_Error|bool True if the request has read access for the item, WP_Error object otherwise. 124 */ 125 public function get_item_permissions_check( $request ) { 126 if ( ! current_user_can( 'edit_theme_options' ) ) { 127 return new WP_Error( 128 'rest_cannot_view', 129 __( 'Sorry, you are not allowed to view menu locations.' ), 130 array( 'status' => rest_authorization_required_code() ) 131 ); 132 } 133 134 return true; 135 } 136 137 /** 138 * Retrieves a specific menu location. 139 * 140 * @since 5.9.0 141 * 142 * @param WP_REST_Request $request Full details about the request. 143 * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure. 144 */ 145 public function get_item( $request ) { 146 $registered_menus = get_registered_nav_menus(); 147 if ( ! array_key_exists( $request['location'], $registered_menus ) ) { 148 return new WP_Error( 'rest_menu_location_invalid', __( 'Invalid menu location.' ), array( 'status' => 404 ) ); 149 } 150 151 $location = new stdClass(); 152 $location->name = $request['location']; 153 $location->description = $registered_menus[ $location->name ]; 154 155 $data = $this->prepare_item_for_response( $location, $request ); 156 157 return rest_ensure_response( $data ); 158 } 159 160 /** 161 * Prepares a menu location object for serialization. 162 * 163 * @since 5.9.0 164 * 165 * @param stdClass $item Post status data. 166 * @param WP_REST_Request $request Full details about the request. 167 * @return WP_REST_Response Menu location data. 168 */ 169 public function prepare_item_for_response( $item, $request ) { 170 // Restores the more descriptive, specific name for use within this method. 171 $location = $item; 172 $locations = get_nav_menu_locations(); 173 $menu = isset( $locations[ $location->name ] ) ? $locations[ $location->name ] : 0; 174 175 $fields = $this->get_fields_for_response( $request ); 176 $data = array(); 177 178 if ( rest_is_field_included( 'name', $fields ) ) { 179 $data['name'] = $location->name; 180 } 181 182 if ( rest_is_field_included( 'description', $fields ) ) { 183 $data['description'] = $location->description; 184 } 185 186 if ( rest_is_field_included( 'menu', $fields ) ) { 187 $data['menu'] = (int) $menu; 188 } 189 190 $context = ! empty( $request['context'] ) ? $request['context'] : 'view'; 191 $data = $this->add_additional_fields_to_object( $data, $request ); 192 $data = $this->filter_response_by_context( $data, $context ); 193 194 $response = rest_ensure_response( $data ); 195 196 $response->add_links( $this->prepare_links( $location ) ); 197 198 /** 199 * Filters menu location data returned from the REST API. 200 * 201 * @since 5.9.0 202 * 203 * @param WP_REST_Response $response The response object. 204 * @param object $location The original location object. 205 * @param WP_REST_Request $request Request used to generate the response. 206 */ 207 return apply_filters( 'rest_prepare_menu_location', $response, $location, $request ); 208 } 209 210 /** 211 * Retrieves the menu location's schema, conforming to JSON Schema. 212 * 213 * @since 5.9.0 214 * 215 * @return array Item schema data. 216 */ 217 public function get_item_schema() { 218 if ( $this->schema ) { 219 return $this->add_additional_fields_schema( $this->schema ); 220 } 221 222 $this->schema = array( 223 '$schema' => 'http://json-schema.org/draft-04/schema#', 224 'title' => 'menu-location', 225 'type' => 'object', 226 'properties' => array( 227 'name' => array( 228 'description' => __( 'The name of the menu location.' ), 229 'type' => 'string', 230 'context' => array( 'embed', 'view', 'edit' ), 231 'readonly' => true, 232 ), 233 'description' => array( 234 'description' => __( 'The description of the menu location.' ), 235 'type' => 'string', 236 'context' => array( 'embed', 'view', 'edit' ), 237 'readonly' => true, 238 ), 239 'menu' => array( 240 'description' => __( 'The ID of the assigned menu.' ), 241 'type' => 'integer', 242 'context' => array( 'embed', 'view', 'edit' ), 243 'readonly' => true, 244 ), 245 ), 246 ); 247 248 return $this->add_additional_fields_schema( $this->schema ); 249 } 250 251 /** 252 * Retrieves the query params for collections. 253 * 254 * @since 5.9.0 255 * 256 * @return array Collection parameters. 257 */ 258 public function get_collection_params() { 259 return array( 260 'context' => $this->get_context_param( array( 'default' => 'view' ) ), 261 ); 262 } 263 264 /** 265 * Prepares links for the request. 266 * 267 * @since 5.9.0 268 * 269 * @param stdClass $location Menu location. 270 * @return array Links for the given menu location. 271 */ 272 protected function prepare_links( $location ) { 273 $base = sprintf( '%s/%s', $this->namespace, $this->rest_base ); 274 275 // Entity meta. 276 $links = array( 277 'self' => array( 278 'href' => rest_url( trailingslashit( $base ) . $location->name ), 279 ), 280 'collection' => array( 281 'href' => rest_url( $base ), 282 ), 283 ); 284 285 $locations = get_nav_menu_locations(); 286 $menu = isset( $locations[ $location->name ] ) ? $locations[ $location->name ] : 0; 287 if ( $menu ) { 288 $path = rest_get_route_for_term( $menu ); 289 if ( $path ) { 290 $url = rest_url( $path ); 291 292 $links['https://api.w.org/menu'][] = array( 293 'href' => $url, 294 'embeddable' => true, 295 ); 296 } 297 } 298 299 return $links; 300 } 301 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Sat Dec 14 01:00:02 2024 | Cross-referenced by PHPXref 0.7.1 |