| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Option API 4 * 5 * @package WordPress 6 * @subpackage Option 7 */ 8 9 /** 10 * Retrieves an option value based on an option name. 11 * 12 * If the option does not exist, and a default value is not provided, 13 * boolean false is returned. This could be used to check whether you need 14 * to initialize an option during installation of a plugin, however that 15 * can be done better by using add_option() which will not overwrite 16 * existing options. 17 * 18 * Not initializing an option and using boolean `false` as a return value 19 * is a bad practice as it triggers an additional database query. 20 * 21 * The type of the returned value can be different from the type that was passed 22 * when saving or updating the option. If the option value was serialized, 23 * then it will be unserialized when it is returned. In this case the type will 24 * be the same. For example, storing a non-scalar value like an array will 25 * return the same array. 26 * 27 * In most cases non-string scalar and null values will be converted and returned 28 * as string equivalents. 29 * 30 * Exceptions: 31 * 1. When the option has not been saved in the database, the `$default` value 32 * is returned if provided. If not, boolean `false` is returned. 33 * 2. When one of the Options API filters is used: {@see 'pre_option_{$option}'}, 34 * {@see 'default_option_{$option}'}, or {@see 'option_{$option}'}, the returned 35 * value may not match the expected type. 36 * 3. When the option has just been saved in the database, and get_option() 37 * is used right after, non-string scalar and null values are not converted to 38 * string equivalents and the original type is returned. 39 * 40 * Examples: 41 * 42 * When adding options like this: `add_option( 'my_option_name', 'value' );` 43 * and then retrieving them with `get_option( 'my_option_name' );`, the returned 44 * values will be: 45 * 46 * `false` returns `string(0) ""` 47 * `true` returns `string(1) "1"` 48 * `0` returns `string(1) "0"` 49 * `1` returns `string(1) "1"` 50 * `'0'` returns `string(1) "0"` 51 * `'1'` returns `string(1) "1"` 52 * `null` returns `string(0) ""` 53 * 54 * When adding options with non-scalar values like 55 * `add_option( 'my_array', array( false, 'str', null ) );`, the returned value 56 * will be identical to the original as it is serialized before saving 57 * it in the database: 58 * 59 * array(3) { 60 * [0] => bool(false) 61 * [1] => string(3) "str" 62 * [2] => NULL 63 * } 64 * 65 * @since 1.5.0 66 * 67 * @global wpdb $wpdb WordPress database abstraction object. 68 * 69 * @param string $option Name of the option to retrieve. Expected to not be SQL-escaped. 70 * @param mixed $default Optional. Default value to return if the option does not exist. 71 * @return mixed Value of the option. A value of any type may be returned, including 72 * scalar (string, boolean, float, integer), null, array, object. 73 * Scalar and null values will be returned as strings as long as they originate 74 * from a database stored option value. If there is no option in the database, 75 * boolean `false` is returned. 76 */ 77 function get_option( $option, $default = false ) { 78 global $wpdb; 79 80 if ( is_scalar( $option ) ) { 81 $option = trim( $option ); 82 } 83 84 if ( empty( $option ) ) { 85 return false; 86 } 87 88 /* 89 * Until a proper _deprecated_option() function can be introduced, 90 * redirect requests to deprecated keys to the new, correct ones. 91 */ 92 $deprecated_keys = array( 93 'blacklist_keys' => 'disallowed_keys', 94 'comment_whitelist' => 'comment_previously_approved', 95 ); 96 97 if ( ! wp_installing() && isset( $deprecated_keys[ $option ] ) ) { 98 _deprecated_argument( 99 __FUNCTION__, 100 '5.5.0', 101 sprintf( 102 /* translators: 1: Deprecated option key, 2: New option key. */ 103 __( 'The "%1$s" option key has been renamed to "%2$s".' ), 104 $option, 105 $deprecated_keys[ $option ] 106 ) 107 ); 108 return get_option( $deprecated_keys[ $option ], $default ); 109 } 110 111 /** 112 * Filters the value of an existing option before it is retrieved. 113 * 114 * The dynamic portion of the hook name, `$option`, refers to the option name. 115 * 116 * Returning a truthy value from the filter will effectively short-circuit retrieval 117 * and return the passed value instead. 118 * 119 * @since 1.5.0 120 * @since 4.4.0 The `$option` parameter was added. 121 * @since 4.9.0 The `$default` parameter was added. 122 * 123 * @param mixed $pre_option The value to return instead of the option value. This differs 124 * from `$default`, which is used as the fallback value in the event 125 * the option doesn't exist elsewhere in get_option(). 126 * Default false (to skip past the short-circuit). 127 * @param string $option Option name. 128 * @param mixed $default The fallback value to return if the option does not exist. 129 * Default false. 130 */ 131 $pre = apply_filters( "pre_option_{$option}", false, $option, $default ); 132 133 if ( false !== $pre ) { 134 return $pre; 135 } 136 137 if ( defined( 'WP_SETUP_CONFIG' ) ) { 138 return false; 139 } 140 141 // Distinguish between `false` as a default, and not passing one. 142 $passed_default = func_num_args() > 1; 143 144 if ( ! wp_installing() ) { 145 // Prevent non-existent options from triggering multiple queries. 146 $notoptions = wp_cache_get( 'notoptions', 'options' ); 147 148 if ( isset( $notoptions[ $option ] ) ) { 149 /** 150 * Filters the default value for an option. 151 * 152 * The dynamic portion of the hook name, `$option`, refers to the option name. 153 * 154 * @since 3.4.0 155 * @since 4.4.0 The `$option` parameter was added. 156 * @since 4.7.0 The `$passed_default` parameter was added to distinguish between a `false` value and the default parameter value. 157 * 158 * @param mixed $default The default value to return if the option does not exist 159 * in the database. 160 * @param string $option Option name. 161 * @param bool $passed_default Was `get_option()` passed a default value? 162 */ 163 return apply_filters( "default_option_{$option}", $default, $option, $passed_default ); 164 } 165 166 $alloptions = wp_load_alloptions(); 167 168 if ( isset( $alloptions[ $option ] ) ) { 169 $value = $alloptions[ $option ]; 170 } else { 171 $value = wp_cache_get( $option, 'options' ); 172 173 if ( false === $value ) { 174 $row = $wpdb->get_row( $wpdb->prepare( "SELECT option_value FROM $wpdb->options WHERE option_name = %s LIMIT 1", $option ) ); 175 176 // Has to be get_row() instead of get_var() because of funkiness with 0, false, null values. 177 if ( is_object( $row ) ) { 178 $value = $row->option_value; 179 wp_cache_add( $option, $value, 'options' ); 180 } else { // Option does not exist, so we must cache its non-existence. 181 if ( ! is_array( $notoptions ) ) { 182 $notoptions = array(); 183 } 184 185 $notoptions[ $option ] = true; 186 wp_cache_set( 'notoptions', $notoptions, 'options' ); 187 188 /** This filter is documented in wp-includes/option.php */ 189 return apply_filters( "default_option_{$option}", $default, $option, $passed_default ); 190 } 191 } 192 } 193 } else { 194 $suppress = $wpdb->suppress_errors(); 195 $row = $wpdb->get_row( $wpdb->prepare( "SELECT option_value FROM $wpdb->options WHERE option_name = %s LIMIT 1", $option ) ); 196 $wpdb->suppress_errors( $suppress ); 197 198 if ( is_object( $row ) ) { 199 $value = $row->option_value; 200 } else { 201 /** This filter is documented in wp-includes/option.php */ 202 return apply_filters( "default_option_{$option}", $default, $option, $passed_default ); 203 } 204 } 205 206 // If home is not set, use siteurl. 207 if ( 'home' === $option && '' === $value ) { 208 return get_option( 'siteurl' ); 209 } 210 211 if ( in_array( $option, array( 'siteurl', 'home', 'category_base', 'tag_base' ), true ) ) { 212 $value = untrailingslashit( $value ); 213 } 214 215 /** 216 * Filters the value of an existing option. 217 * 218 * The dynamic portion of the hook name, `$option`, refers to the option name. 219 * 220 * @since 1.5.0 As 'option_' . $setting 221 * @since 3.0.0 222 * @since 4.4.0 The `$option` parameter was added. 223 * 224 * @param mixed $value Value of the option. If stored serialized, it will be 225 * unserialized prior to being returned. 226 * @param string $option Option name. 227 */ 228 return apply_filters( "option_{$option}", maybe_unserialize( $value ), $option ); 229 } 230 231 /** 232 * Protects WordPress special option from being modified. 233 * 234 * Will die if $option is in protected list. Protected options are 'alloptions' 235 * and 'notoptions' options. 236 * 237 * @since 2.2.0 238 * 239 * @param string $option Option name. 240 */ 241 function wp_protect_special_option( $option ) { 242 if ( 'alloptions' === $option || 'notoptions' === $option ) { 243 wp_die( 244 sprintf( 245 /* translators: %s: Option name. */ 246 __( '%s is a protected WP option and may not be modified' ), 247 esc_html( $option ) 248 ) 249 ); 250 } 251 } 252 253 /** 254 * Prints option value after sanitizing for forms. 255 * 256 * @since 1.5.0 257 * 258 * @param string $option Option name. 259 */ 260 function form_option( $option ) { 261 echo esc_attr( get_option( $option ) ); 262 } 263 264 /** 265 * Loads and caches all autoloaded options, if available or all options. 266 * 267 * @since 2.2.0 268 * @since 5.3.1 The `$force_cache` parameter was added. 269 * 270 * @global wpdb $wpdb WordPress database abstraction object. 271 * 272 * @param bool $force_cache Optional. Whether to force an update of the local cache 273 * from the persistent cache. Default false. 274 * @return array List of all options. 275 */ 276 function wp_load_alloptions( $force_cache = false ) { 277 global $wpdb; 278 279 if ( ! wp_installing() || ! is_multisite() ) { 280 $alloptions = wp_cache_get( 'alloptions', 'options', $force_cache ); 281 } else { 282 $alloptions = false; 283 } 284 285 if ( ! $alloptions ) { 286 $suppress = $wpdb->suppress_errors(); 287 $alloptions_db = $wpdb->get_results( "SELECT option_name, option_value FROM $wpdb->options WHERE autoload = 'yes'" ); 288 if ( ! $alloptions_db ) { 289 $alloptions_db = $wpdb->get_results( "SELECT option_name, option_value FROM $wpdb->options" ); 290 } 291 $wpdb->suppress_errors( $suppress ); 292 293 $alloptions = array(); 294 foreach ( (array) $alloptions_db as $o ) { 295 $alloptions[ $o->option_name ] = $o->option_value; 296 } 297 298 if ( ! wp_installing() || ! is_multisite() ) { 299 /** 300 * Filters all options before caching them. 301 * 302 * @since 4.9.0 303 * 304 * @param array $alloptions Array with all options. 305 */ 306 $alloptions = apply_filters( 'pre_cache_alloptions', $alloptions ); 307 308 wp_cache_add( 'alloptions', $alloptions, 'options' ); 309 } 310 } 311 312 /** 313 * Filters all options after retrieving them. 314 * 315 * @since 4.9.0 316 * 317 * @param array $alloptions Array with all options. 318 */ 319 return apply_filters( 'alloptions', $alloptions ); 320 } 321 322 /** 323 * Loads and caches certain often requested site options if is_multisite() and a persistent cache is not being used. 324 * 325 * @since 3.0.0 326 * 327 * @global wpdb $wpdb WordPress database abstraction object. 328 * 329 * @param int $network_id Optional site ID for which to query the options. Defaults to the current site. 330 */ 331 function wp_load_core_site_options( $network_id = null ) { 332 global $wpdb; 333 334 if ( ! is_multisite() || wp_using_ext_object_cache() || wp_installing() ) { 335 return; 336 } 337 338 if ( empty( $network_id ) ) { 339 $network_id = get_current_network_id(); 340 } 341 342 $core_options = array( 'site_name', 'siteurl', 'active_sitewide_plugins', '_site_transient_timeout_theme_roots', '_site_transient_theme_roots', 'site_admins', 'can_compress_scripts', 'global_terms_enabled', 'ms_files_rewriting' ); 343 344 $core_options_in = "'" . implode( "', '", $core_options ) . "'"; 345 $options = $wpdb->get_results( $wpdb->prepare( "SELECT meta_key, meta_value FROM $wpdb->sitemeta WHERE meta_key IN ($core_options_in) AND site_id = %d", $network_id ) ); 346 347 foreach ( $options as $option ) { 348 $key = $option->meta_key; 349 $cache_key = "{$network_id}:$key"; 350 $option->meta_value = maybe_unserialize( $option->meta_value ); 351 352 wp_cache_set( $cache_key, $option->meta_value, 'site-options' ); 353 } 354 } 355 356 /** 357 * Updates the value of an option that was already added. 358 * 359 * You do not need to serialize values. If the value needs to be serialized, 360 * then it will be serialized before it is inserted into the database. 361 * Remember, resources cannot be serialized or added as an option. 362 * 363 * If the option does not exist, it will be created. 364 365 * This function is designed to work with or without a logged-in user. In terms of security, 366 * plugin developers should check the current user's capabilities before updating any options. 367 * 368 * @since 1.0.0 369 * @since 4.2.0 The `$autoload` parameter was added. 370 * 371 * @global wpdb $wpdb WordPress database abstraction object. 372 * 373 * @param string $option Name of the option to update. Expected to not be SQL-escaped. 374 * @param mixed $value Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped. 375 * @param string|bool $autoload Optional. Whether to load the option when WordPress starts up. For existing options, 376 * `$autoload` can only be updated using `update_option()` if `$value` is also changed. 377 * Accepts 'yes'|true to enable or 'no'|false to disable. For non-existent options, 378 * the default value is 'yes'. Default null. 379 * @return bool True if the value was updated, false otherwise. 380 */ 381 function update_option( $option, $value, $autoload = null ) { 382 global $wpdb; 383 384 if ( is_scalar( $option ) ) { 385 $option = trim( $option ); 386 } 387 388 if ( empty( $option ) ) { 389 return false; 390 } 391 392 /* 393 * Until a proper _deprecated_option() function can be introduced, 394 * redirect requests to deprecated keys to the new, correct ones. 395 */ 396 $deprecated_keys = array( 397 'blacklist_keys' => 'disallowed_keys', 398 'comment_whitelist' => 'comment_previously_approved', 399 ); 400 401 if ( ! wp_installing() && isset( $deprecated_keys[ $option ] ) ) { 402 _deprecated_argument( 403 __FUNCTION__, 404 '5.5.0', 405 sprintf( 406 /* translators: 1: Deprecated option key, 2: New option key. */ 407 __( 'The "%1$s" option key has been renamed to "%2$s".' ), 408 $option, 409 $deprecated_keys[ $option ] 410 ) 411 ); 412 return update_option( $deprecated_keys[ $option ], $value, $autoload ); 413 } 414 415 wp_protect_special_option( $option ); 416 417 if ( is_object( $value ) ) { 418 $value = clone $value; 419 } 420 421 $value = sanitize_option( $option, $value ); 422 $old_value = get_option( $option ); 423 424 /** 425 * Filters a specific option before its value is (maybe) serialized and updated. 426 * 427 * The dynamic portion of the hook name, `$option`, refers to the option name. 428 * 429 * @since 2.6.0 430 * @since 4.4.0 The `$option` parameter was added. 431 * 432 * @param mixed $value The new, unserialized option value. 433 * @param mixed $old_value The old option value. 434 * @param string $option Option name. 435 */ 436 $value = apply_filters( "pre_update_option_{$option}", $value, $old_value, $option ); 437 438 /** 439 * Filters an option before its value is (maybe) serialized and updated. 440 * 441 * @since 3.9.0 442 * 443 * @param mixed $value The new, unserialized option value. 444 * @param string $option Name of the option. 445 * @param mixed $old_value The old option value. 446 */ 447 $value = apply_filters( 'pre_update_option', $value, $option, $old_value ); 448 449 /* 450 * If the new and old values are the same, no need to update. 451 * 452 * Unserialized values will be adequate in most cases. If the unserialized 453 * data differs, the (maybe) serialized data is checked to avoid 454 * unnecessary database calls for otherwise identical object instances. 455 * 456 * See https://core.trac.wordpress.org/ticket/38903 457 */ 458 if ( $value === $old_value || maybe_serialize( $value ) === maybe_serialize( $old_value ) ) { 459 return false; 460 } 461 462 /** This filter is documented in wp-includes/option.php */ 463 if ( apply_filters( "default_option_{$option}", false, $option, false ) === $old_value ) { 464 // Default setting for new options is 'yes'. 465 if ( null === $autoload ) { 466 $autoload = 'yes'; 467 } 468 469 return add_option( $option, $value, '', $autoload ); 470 } 471 472 $serialized_value = maybe_serialize( $value ); 473 474 /** 475 * Fires immediately before an option value is updated. 476 * 477 * @since 2.9.0 478 * 479 * @param string $option Name of the option to update. 480 * @param mixed $old_value The old option value. 481 * @param mixed $value The new option value. 482 */ 483 do_action( 'update_option', $option, $old_value, $value ); 484 485 $update_args = array( 486 'option_value' => $serialized_value, 487 ); 488 489 if ( null !== $autoload ) { 490 $update_args['autoload'] = ( 'no' === $autoload || false === $autoload ) ? 'no' : 'yes'; 491 } 492 493 $result = $wpdb->update( $wpdb->options, $update_args, array( 'option_name' => $option ) ); 494 if ( ! $result ) { 495 return false; 496 } 497 498 $notoptions = wp_cache_get( 'notoptions', 'options' ); 499 500 if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) { 501 unset( $notoptions[ $option ] ); 502 wp_cache_set( 'notoptions', $notoptions, 'options' ); 503 } 504 505 if ( ! wp_installing() ) { 506 $alloptions = wp_load_alloptions( true ); 507 if ( isset( $alloptions[ $option ] ) ) { 508 $alloptions[ $option ] = $serialized_value; 509 wp_cache_set( 'alloptions', $alloptions, 'options' ); 510 } else { 511 wp_cache_set( $option, $serialized_value, 'options' ); 512 } 513 } 514 515 /** 516 * Fires after the value of a specific option has been successfully updated. 517 * 518 * The dynamic portion of the hook name, `$option`, refers to the option name. 519 * 520 * @since 2.0.1 521 * @since 4.4.0 The `$option` parameter was added. 522 * 523 * @param mixed $old_value The old option value. 524 * @param mixed $value The new option value. 525 * @param string $option Option name. 526 */ 527 do_action( "update_option_{$option}", $old_value, $value, $option ); 528 529 /** 530 * Fires after the value of an option has been successfully updated. 531 * 532 * @since 2.9.0 533 * 534 * @param string $option Name of the updated option. 535 * @param mixed $old_value The old option value. 536 * @param mixed $value The new option value. 537 */ 538 do_action( 'updated_option', $option, $old_value, $value ); 539 540 return true; 541 } 542 543 /** 544 * Adds a new option. 545 * 546 * You do not need to serialize values. If the value needs to be serialized, 547 * then it will be serialized before it is inserted into the database. 548 * Remember, resources cannot be serialized or added as an option. 549 * 550 * You can create options without values and then update the values later. 551 * Existing options will not be updated and checks are performed to ensure that you 552 * aren't adding a protected WordPress option. Care should be taken to not name 553 * options the same as the ones which are protected. 554 * 555 * @since 1.0.0 556 * 557 * @global wpdb $wpdb WordPress database abstraction object. 558 * 559 * @param string $option Name of the option to add. Expected to not be SQL-escaped. 560 * @param mixed $value Optional. Option value. Must be serializable if non-scalar. 561 * Expected to not be SQL-escaped. 562 * @param string $deprecated Optional. Description. Not used anymore. 563 * @param string|bool $autoload Optional. Whether to load the option when WordPress starts up. 564 * Default is enabled. Accepts 'no' to disable for legacy reasons. 565 * @return bool True if the option was added, false otherwise. 566 */ 567 function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' ) { 568 global $wpdb; 569 570 if ( ! empty( $deprecated ) ) { 571 _deprecated_argument( __FUNCTION__, '2.3.0' ); 572 } 573 574 if ( is_scalar( $option ) ) { 575 $option = trim( $option ); 576 } 577 578 if ( empty( $option ) ) { 579 return false; 580 } 581 582 /* 583 * Until a proper _deprecated_option() function can be introduced, 584 * redirect requests to deprecated keys to the new, correct ones. 585 */ 586 $deprecated_keys = array( 587 'blacklist_keys' => 'disallowed_keys', 588 'comment_whitelist' => 'comment_previously_approved', 589 ); 590 591 if ( ! wp_installing() && isset( $deprecated_keys[ $option ] ) ) { 592 _deprecated_argument( 593 __FUNCTION__, 594 '5.5.0', 595 sprintf( 596 /* translators: 1: Deprecated option key, 2: New option key. */ 597 __( 'The "%1$s" option key has been renamed to "%2$s".' ), 598 $option, 599 $deprecated_keys[ $option ] 600 ) 601 ); 602 return add_option( $deprecated_keys[ $option ], $value, $deprecated, $autoload ); 603 } 604 605 wp_protect_special_option( $option ); 606 607 if ( is_object( $value ) ) { 608 $value = clone $value; 609 } 610 611 $value = sanitize_option( $option, $value ); 612 613 // Make sure the option doesn't already exist. 614 // We can check the 'notoptions' cache before we ask for a DB query. 615 $notoptions = wp_cache_get( 'notoptions', 'options' ); 616 617 if ( ! is_array( $notoptions ) || ! isset( $notoptions[ $option ] ) ) { 618 /** This filter is documented in wp-includes/option.php */ 619 if ( apply_filters( "default_option_{$option}", false, $option, false ) !== get_option( $option ) ) { 620 return false; 621 } 622 } 623 624 $serialized_value = maybe_serialize( $value ); 625 $autoload = ( 'no' === $autoload || false === $autoload ) ? 'no' : 'yes'; 626 627 /** 628 * Fires before an option is added. 629 * 630 * @since 2.9.0 631 * 632 * @param string $option Name of the option to add. 633 * @param mixed $value Value of the option. 634 */ 635 do_action( 'add_option', $option, $value ); 636 637 $result = $wpdb->query( $wpdb->prepare( "INSERT INTO `$wpdb->options` (`option_name`, `option_value`, `autoload`) VALUES (%s, %s, %s) ON DUPLICATE KEY UPDATE `option_name` = VALUES(`option_name`), `option_value` = VALUES(`option_value`), `autoload` = VALUES(`autoload`)", $option, $serialized_value, $autoload ) ); 638 if ( ! $result ) { 639 return false; 640 } 641 642 if ( ! wp_installing() ) { 643 if ( 'yes' === $autoload ) { 644 $alloptions = wp_load_alloptions( true ); 645 $alloptions[ $option ] = $serialized_value; 646 wp_cache_set( 'alloptions', $alloptions, 'options' ); 647 } else { 648 wp_cache_set( $option, $serialized_value, 'options' ); 649 } 650 } 651 652 // This option exists now. 653 $notoptions = wp_cache_get( 'notoptions', 'options' ); // Yes, again... we need it to be fresh. 654 655 if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) { 656 unset( $notoptions[ $option ] ); 657 wp_cache_set( 'notoptions', $notoptions, 'options' ); 658 } 659 660 /** 661 * Fires after a specific option has been added. 662 * 663 * The dynamic portion of the hook name, `$option`, refers to the option name. 664 * 665 * @since 2.5.0 As "add_option_{$name}" 666 * @since 3.0.0 667 * 668 * @param string $option Name of the option to add. 669 * @param mixed $value Value of the option. 670 */ 671 do_action( "add_option_{$option}", $option, $value ); 672 673 /** 674 * Fires after an option has been added. 675 * 676 * @since 2.9.0 677 * 678 * @param string $option Name of the added option. 679 * @param mixed $value Value of the option. 680 */ 681 do_action( 'added_option', $option, $value ); 682 683 return true; 684 } 685 686 /** 687 * Removes option by name. Prevents removal of protected WordPress options. 688 * 689 * @since 1.2.0 690 * 691 * @global wpdb $wpdb WordPress database abstraction object. 692 * 693 * @param string $option Name of the option to delete. Expected to not be SQL-escaped. 694 * @return bool True if the option was deleted, false otherwise. 695 */ 696 function delete_option( $option ) { 697 global $wpdb; 698 699 if ( is_scalar( $option ) ) { 700 $option = trim( $option ); 701 } 702 703 if ( empty( $option ) ) { 704 return false; 705 } 706 707 wp_protect_special_option( $option ); 708 709 // Get the ID, if no ID then return. 710 $row = $wpdb->get_row( $wpdb->prepare( "SELECT autoload FROM $wpdb->options WHERE option_name = %s", $option ) ); 711 if ( is_null( $row ) ) { 712 return false; 713 } 714 715 /** 716 * Fires immediately before an option is deleted. 717 * 718 * @since 2.9.0 719 * 720 * @param string $option Name of the option to delete. 721 */ 722 do_action( 'delete_option', $option ); 723 724 $result = $wpdb->delete( $wpdb->options, array( 'option_name' => $option ) ); 725 726 if ( ! wp_installing() ) { 727 if ( 'yes' === $row->autoload ) { 728 $alloptions = wp_load_alloptions( true ); 729 if ( is_array( $alloptions ) && isset( $alloptions[ $option ] ) ) { 730 unset( $alloptions[ $option ] ); 731 wp_cache_set( 'alloptions', $alloptions, 'options' ); 732 } 733 } else { 734 wp_cache_delete( $option, 'options' ); 735 } 736 } 737 738 if ( $result ) { 739 740 /** 741 * Fires after a specific option has been deleted. 742 * 743 * The dynamic portion of the hook name, `$option`, refers to the option name. 744 * 745 * @since 3.0.0 746 * 747 * @param string $option Name of the deleted option. 748 */ 749 do_action( "delete_option_{$option}", $option ); 750 751 /** 752 * Fires after an option has been deleted. 753 * 754 * @since 2.9.0 755 * 756 * @param string $option Name of the deleted option. 757 */ 758 do_action( 'deleted_option', $option ); 759 760 return true; 761 } 762 763 return false; 764 } 765 766 /** 767 * Deletes a transient. 768 * 769 * @since 2.8.0 770 * 771 * @param string $transient Transient name. Expected to not be SQL-escaped. 772 * @return bool True if the transient was deleted, false otherwise. 773 */ 774 function delete_transient( $transient ) { 775 776 /** 777 * Fires immediately before a specific transient is deleted. 778 * 779 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 780 * 781 * @since 3.0.0 782 * 783 * @param string $transient Transient name. 784 */ 785 do_action( "delete_transient_{$transient}", $transient ); 786 787 if ( wp_using_ext_object_cache() ) { 788 $result = wp_cache_delete( $transient, 'transient' ); 789 } else { 790 $option_timeout = '_transient_timeout_' . $transient; 791 $option = '_transient_' . $transient; 792 $result = delete_option( $option ); 793 794 if ( $result ) { 795 delete_option( $option_timeout ); 796 } 797 } 798 799 if ( $result ) { 800 801 /** 802 * Fires after a transient is deleted. 803 * 804 * @since 3.0.0 805 * 806 * @param string $transient Deleted transient name. 807 */ 808 do_action( 'deleted_transient', $transient ); 809 } 810 811 return $result; 812 } 813 814 /** 815 * Retrieves the value of a transient. 816 * 817 * If the transient does not exist, does not have a value, or has expired, 818 * then the return value will be false. 819 * 820 * @since 2.8.0 821 * 822 * @param string $transient Transient name. Expected to not be SQL-escaped. 823 * @return mixed Value of transient. 824 */ 825 function get_transient( $transient ) { 826 827 /** 828 * Filters the value of an existing transient before it is retrieved. 829 * 830 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 831 * 832 * Returning a truthy value from the filter will effectively short-circuit retrieval 833 * and return the passed value instead. 834 * 835 * @since 2.8.0 836 * @since 4.4.0 The `$transient` parameter was added 837 * 838 * @param mixed $pre_transient The default value to return if the transient does not exist. 839 * Any value other than false will short-circuit the retrieval 840 * of the transient, and return that value. 841 * @param string $transient Transient name. 842 */ 843 $pre = apply_filters( "pre_transient_{$transient}", false, $transient ); 844 845 if ( false !== $pre ) { 846 return $pre; 847 } 848 849 if ( wp_using_ext_object_cache() ) { 850 $value = wp_cache_get( $transient, 'transient' ); 851 } else { 852 $transient_option = '_transient_' . $transient; 853 if ( ! wp_installing() ) { 854 // If option is not in alloptions, it is not autoloaded and thus has a timeout. 855 $alloptions = wp_load_alloptions(); 856 if ( ! isset( $alloptions[ $transient_option ] ) ) { 857 $transient_timeout = '_transient_timeout_' . $transient; 858 $timeout = get_option( $transient_timeout ); 859 if ( false !== $timeout && $timeout < time() ) { 860 delete_option( $transient_option ); 861 delete_option( $transient_timeout ); 862 $value = false; 863 } 864 } 865 } 866 867 if ( ! isset( $value ) ) { 868 $value = get_option( $transient_option ); 869 } 870 } 871 872 /** 873 * Filters an existing transient's value. 874 * 875 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 876 * 877 * @since 2.8.0 878 * @since 4.4.0 The `$transient` parameter was added 879 * 880 * @param mixed $value Value of transient. 881 * @param string $transient Transient name. 882 */ 883 return apply_filters( "transient_{$transient}", $value, $transient ); 884 } 885 886 /** 887 * Sets/updates the value of a transient. 888 * 889 * You do not need to serialize values. If the value needs to be serialized, 890 * then it will be serialized before it is set. 891 * 892 * @since 2.8.0 893 * 894 * @param string $transient Transient name. Expected to not be SQL-escaped. 895 * Must be 172 characters or fewer in length. 896 * @param mixed $value Transient value. Must be serializable if non-scalar. 897 * Expected to not be SQL-escaped. 898 * @param int $expiration Optional. Time until expiration in seconds. Default 0 (no expiration). 899 * @return bool True if the value was set, false otherwise. 900 */ 901 function set_transient( $transient, $value, $expiration = 0 ) { 902 903 $expiration = (int) $expiration; 904 905 /** 906 * Filters a specific transient before its value is set. 907 * 908 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 909 * 910 * @since 3.0.0 911 * @since 4.2.0 The `$expiration` parameter was added. 912 * @since 4.4.0 The `$transient` parameter was added. 913 * 914 * @param mixed $value New value of transient. 915 * @param int $expiration Time until expiration in seconds. 916 * @param string $transient Transient name. 917 */ 918 $value = apply_filters( "pre_set_transient_{$transient}", $value, $expiration, $transient ); 919 920 /** 921 * Filters the expiration for a transient before its value is set. 922 * 923 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 924 * 925 * @since 4.4.0 926 * 927 * @param int $expiration Time until expiration in seconds. Use 0 for no expiration. 928 * @param mixed $value New value of transient. 929 * @param string $transient Transient name. 930 */ 931 $expiration = apply_filters( "expiration_of_transient_{$transient}", $expiration, $value, $transient ); 932 933 if ( wp_using_ext_object_cache() ) { 934 $result = wp_cache_set( $transient, $value, 'transient', $expiration ); 935 } else { 936 $transient_timeout = '_transient_timeout_' . $transient; 937 $transient_option = '_transient_' . $transient; 938 939 if ( false === get_option( $transient_option ) ) { 940 $autoload = 'yes'; 941 if ( $expiration ) { 942 $autoload = 'no'; 943 add_option( $transient_timeout, time() + $expiration, '', 'no' ); 944 } 945 $result = add_option( $transient_option, $value, '', $autoload ); 946 } else { 947 // If expiration is requested, but the transient has no timeout option, 948 // delete, then re-create transient rather than update. 949 $update = true; 950 951 if ( $expiration ) { 952 if ( false === get_option( $transient_timeout ) ) { 953 delete_option( $transient_option ); 954 add_option( $transient_timeout, time() + $expiration, '', 'no' ); 955 $result = add_option( $transient_option, $value, '', 'no' ); 956 $update = false; 957 } else { 958 update_option( $transient_timeout, time() + $expiration ); 959 } 960 } 961 962 if ( $update ) { 963 $result = update_option( $transient_option, $value ); 964 } 965 } 966 } 967 968 if ( $result ) { 969 970 /** 971 * Fires after the value for a specific transient has been set. 972 * 973 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 974 * 975 * @since 3.0.0 976 * @since 3.6.0 The `$value` and `$expiration` parameters were added. 977 * @since 4.4.0 The `$transient` parameter was added. 978 * 979 * @param mixed $value Transient value. 980 * @param int $expiration Time until expiration in seconds. 981 * @param string $transient The name of the transient. 982 */ 983 do_action( "set_transient_{$transient}", $value, $expiration, $transient ); 984 985 /** 986 * Fires after the value for a transient has been set. 987 * 988 * @since 3.0.0 989 * @since 3.6.0 The `$value` and `$expiration` parameters were added. 990 * 991 * @param string $transient The name of the transient. 992 * @param mixed $value Transient value. 993 * @param int $expiration Time until expiration in seconds. 994 */ 995 do_action( 'setted_transient', $transient, $value, $expiration ); 996 } 997 998 return $result; 999 } 1000 1001 /** 1002 * Deletes all expired transients. 1003 * 1004 * The multi-table delete syntax is used to delete the transient record 1005 * from table a, and the corresponding transient_timeout record from table b. 1006 * 1007 * @since 4.9.0 1008 * 1009 * @param bool $force_db Optional. Force cleanup to run against the database even when an external object cache is used. 1010 */ 1011 function delete_expired_transients( $force_db = false ) { 1012 global $wpdb; 1013 1014 if ( ! $force_db && wp_using_ext_object_cache() ) { 1015 return; 1016 } 1017 1018 $wpdb->query( 1019 $wpdb->prepare( 1020 "DELETE a, b FROM {$wpdb->options} a, {$wpdb->options} b 1021 WHERE a.option_name LIKE %s 1022 AND a.option_name NOT LIKE %s 1023 AND b.option_name = CONCAT( '_transient_timeout_', SUBSTRING( a.option_name, 12 ) ) 1024 AND b.option_value < %d", 1025 $wpdb->esc_like( '_transient_' ) . '%', 1026 $wpdb->esc_like( '_transient_timeout_' ) . '%', 1027 time() 1028 ) 1029 ); 1030 1031 if ( ! is_multisite() ) { 1032 // Single site stores site transients in the options table. 1033 $wpdb->query( 1034 $wpdb->prepare( 1035 "DELETE a, b FROM {$wpdb->options} a, {$wpdb->options} b 1036 WHERE a.option_name LIKE %s 1037 AND a.option_name NOT LIKE %s 1038 AND b.option_name = CONCAT( '_site_transient_timeout_', SUBSTRING( a.option_name, 17 ) ) 1039 AND b.option_value < %d", 1040 $wpdb->esc_like( '_site_transient_' ) . '%', 1041 $wpdb->esc_like( '_site_transient_timeout_' ) . '%', 1042 time() 1043 ) 1044 ); 1045 } elseif ( is_multisite() && is_main_site() && is_main_network() ) { 1046 // Multisite stores site transients in the sitemeta table. 1047 $wpdb->query( 1048 $wpdb->prepare( 1049 "DELETE a, b FROM {$wpdb->sitemeta} a, {$wpdb->sitemeta} b 1050 WHERE a.meta_key LIKE %s 1051 AND a.meta_key NOT LIKE %s 1052 AND b.meta_key = CONCAT( '_site_transient_timeout_', SUBSTRING( a.meta_key, 17 ) ) 1053 AND b.meta_value < %d", 1054 $wpdb->esc_like( '_site_transient_' ) . '%', 1055 $wpdb->esc_like( '_site_transient_timeout_' ) . '%', 1056 time() 1057 ) 1058 ); 1059 } 1060 } 1061 1062 /** 1063 * Saves and restores user interface settings stored in a cookie. 1064 * 1065 * Checks if the current user-settings cookie is updated and stores it. When no 1066 * cookie exists (different browser used), adds the last saved cookie restoring 1067 * the settings. 1068 * 1069 * @since 2.7.0 1070 */ 1071 function wp_user_settings() { 1072 1073 if ( ! is_admin() || wp_doing_ajax() ) { 1074 return; 1075 } 1076 1077 $user_id = get_current_user_id(); 1078 if ( ! $user_id ) { 1079 return; 1080 } 1081 1082 if ( ! is_user_member_of_blog() ) { 1083 return; 1084 } 1085 1086 $settings = (string) get_user_option( 'user-settings', $user_id ); 1087 1088 if ( isset( $_COOKIE[ 'wp-settings-' . $user_id ] ) ) { 1089 $cookie = preg_replace( '/[^A-Za-z0-9=&_]/', '', $_COOKIE[ 'wp-settings-' . $user_id ] ); 1090 1091 // No change or both empty. 1092 if ( $cookie == $settings ) { 1093 return; 1094 } 1095 1096 $last_saved = (int) get_user_option( 'user-settings-time', $user_id ); 1097 $current = isset( $_COOKIE[ 'wp-settings-time-' . $user_id ] ) ? preg_replace( '/[^0-9]/', '', $_COOKIE[ 'wp-settings-time-' . $user_id ] ) : 0; 1098 1099 // The cookie is newer than the saved value. Update the user_option and leave the cookie as-is. 1100 if ( $current > $last_saved ) { 1101 update_user_option( $user_id, 'user-settings', $cookie, false ); 1102 update_user_option( $user_id, 'user-settings-time', time() - 5, false ); 1103 return; 1104 } 1105 } 1106 1107 // The cookie is not set in the current browser or the saved value is newer. 1108 $secure = ( 'https' === parse_url( admin_url(), PHP_URL_SCHEME ) ); 1109 setcookie( 'wp-settings-' . $user_id, $settings, time() + YEAR_IN_SECONDS, SITECOOKIEPATH, null, $secure ); 1110 setcookie( 'wp-settings-time-' . $user_id, time(), time() + YEAR_IN_SECONDS, SITECOOKIEPATH, null, $secure ); 1111 $_COOKIE[ 'wp-settings-' . $user_id ] = $settings; 1112 } 1113 1114 /** 1115 * Retrieves user interface setting value based on setting name. 1116 * 1117 * @since 2.7.0 1118 * 1119 * @param string $name The name of the setting. 1120 * @param string|false $default Optional. Default value to return when $name is not set. Default false. 1121 * @return mixed The last saved user setting or the default value/false if it doesn't exist. 1122 */ 1123 function get_user_setting( $name, $default = false ) { 1124 $all_user_settings = get_all_user_settings(); 1125 1126 return isset( $all_user_settings[ $name ] ) ? $all_user_settings[ $name ] : $default; 1127 } 1128 1129 /** 1130 * Adds or updates user interface setting. 1131 * 1132 * Both $name and $value can contain only ASCII letters, numbers, hyphens, and underscores. 1133 * 1134 * This function has to be used before any output has started as it calls setcookie(). 1135 * 1136 * @since 2.8.0 1137 * 1138 * @param string $name The name of the setting. 1139 * @param string $value The value for the setting. 1140 * @return bool|null True if set successfully, false otherwise. 1141 * Null if the current user is not a member of the site. 1142 */ 1143 function set_user_setting( $name, $value ) { 1144 if ( headers_sent() ) { 1145 return false; 1146 } 1147 1148 $all_user_settings = get_all_user_settings(); 1149 $all_user_settings[ $name ] = $value; 1150 1151 return wp_set_all_user_settings( $all_user_settings ); 1152 } 1153 1154 /** 1155 * Deletes user interface settings. 1156 * 1157 * Deleting settings would reset them to the defaults. 1158 * 1159 * This function has to be used before any output has started as it calls setcookie(). 1160 * 1161 * @since 2.7.0 1162 * 1163 * @param string $names The name or array of names of the setting to be deleted. 1164 * @return bool|null True if deleted successfully, false otherwise. 1165 * Null if the current user is not a member of the site. 1166 */ 1167 function delete_user_setting( $names ) { 1168 if ( headers_sent() ) { 1169 return false; 1170 } 1171 1172 $all_user_settings = get_all_user_settings(); 1173 $names = (array) $names; 1174 $deleted = false; 1175 1176 foreach ( $names as $name ) { 1177 if ( isset( $all_user_settings[ $name ] ) ) { 1178 unset( $all_user_settings[ $name ] ); 1179 $deleted = true; 1180 } 1181 } 1182 1183 if ( $deleted ) { 1184 return wp_set_all_user_settings( $all_user_settings ); 1185 } 1186 1187 return false; 1188 } 1189 1190 /** 1191 * Retrieves all user interface settings. 1192 * 1193 * @since 2.7.0 1194 * 1195 * @global array $_updated_user_settings 1196 * 1197 * @return array The last saved user settings or empty array. 1198 */ 1199 function get_all_user_settings() { 1200 global $_updated_user_settings; 1201 1202 $user_id = get_current_user_id(); 1203 if ( ! $user_id ) { 1204 return array(); 1205 } 1206 1207 if ( isset( $_updated_user_settings ) && is_array( $_updated_user_settings ) ) { 1208 return $_updated_user_settings; 1209 } 1210 1211 $user_settings = array(); 1212 1213 if ( isset( $_COOKIE[ 'wp-settings-' . $user_id ] ) ) { 1214 $cookie = preg_replace( '/[^A-Za-z0-9=&_-]/', '', $_COOKIE[ 'wp-settings-' . $user_id ] ); 1215 1216 if ( strpos( $cookie, '=' ) ) { // '=' cannot be 1st char. 1217 parse_str( $cookie, $user_settings ); 1218 } 1219 } else { 1220 $option = get_user_option( 'user-settings', $user_id ); 1221 1222 if ( $option && is_string( $option ) ) { 1223 parse_str( $option, $user_settings ); 1224 } 1225 } 1226 1227 $_updated_user_settings = $user_settings; 1228 return $user_settings; 1229 } 1230 1231 /** 1232 * Private. Sets all user interface settings. 1233 * 1234 * @since 2.8.0 1235 * @access private 1236 * 1237 * @global array $_updated_user_settings 1238 * 1239 * @param array $user_settings User settings. 1240 * @return bool|null True if set successfully, false if the current user could not be found. 1241 * Null if the current user is not a member of the site. 1242 */ 1243 function wp_set_all_user_settings( $user_settings ) { 1244 global $_updated_user_settings; 1245 1246 $user_id = get_current_user_id(); 1247 if ( ! $user_id ) { 1248 return false; 1249 } 1250 1251 if ( ! is_user_member_of_blog() ) { 1252 return; 1253 } 1254 1255 $settings = ''; 1256 foreach ( $user_settings as $name => $value ) { 1257 $_name = preg_replace( '/[^A-Za-z0-9_-]+/', '', $name ); 1258 $_value = preg_replace( '/[^A-Za-z0-9_-]+/', '', $value ); 1259 1260 if ( ! empty( $_name ) ) { 1261 $settings .= $_name . '=' . $_value . '&'; 1262 } 1263 } 1264 1265 $settings = rtrim( $settings, '&' ); 1266 parse_str( $settings, $_updated_user_settings ); 1267 1268 update_user_option( $user_id, 'user-settings', $settings, false ); 1269 update_user_option( $user_id, 'user-settings-time', time(), false ); 1270 1271 return true; 1272 } 1273 1274 /** 1275 * Deletes the user settings of the current user. 1276 * 1277 * @since 2.7.0 1278 */ 1279 function delete_all_user_settings() { 1280 $user_id = get_current_user_id(); 1281 if ( ! $user_id ) { 1282 return; 1283 } 1284 1285 update_user_option( $user_id, 'user-settings', '', false ); 1286 setcookie( 'wp-settings-' . $user_id, ' ', time() - YEAR_IN_SECONDS, SITECOOKIEPATH ); 1287 } 1288 1289 /** 1290 * Retrieve an option value for the current network based on name of option. 1291 * 1292 * @since 2.8.0 1293 * @since 4.4.0 The `$use_cache` parameter was deprecated. 1294 * @since 4.4.0 Modified into wrapper for get_network_option() 1295 * 1296 * @see get_network_option() 1297 * 1298 * @param string $option Name of the option to retrieve. Expected to not be SQL-escaped. 1299 * @param mixed $default Optional. Value to return if the option doesn't exist. Default false. 1300 * @param bool $deprecated Whether to use cache. Multisite only. Always set to true. 1301 * @return mixed Value set for the option. 1302 */ 1303 function get_site_option( $option, $default = false, $deprecated = true ) { 1304 return get_network_option( null, $option, $default ); 1305 } 1306 1307 /** 1308 * Adds a new option for the current network. 1309 * 1310 * Existing options will not be updated. Note that prior to 3.3 this wasn't the case. 1311 * 1312 * @since 2.8.0 1313 * @since 4.4.0 Modified into wrapper for add_network_option() 1314 * 1315 * @see add_network_option() 1316 * 1317 * @param string $option Name of the option to add. Expected to not be SQL-escaped. 1318 * @param mixed $value Option value, can be anything. Expected to not be SQL-escaped. 1319 * @return bool True if the option was added, false otherwise. 1320 */ 1321 function add_site_option( $option, $value ) { 1322 return add_network_option( null, $option, $value ); 1323 } 1324 1325 /** 1326 * Removes a option by name for the current network. 1327 * 1328 * @since 2.8.0 1329 * @since 4.4.0 Modified into wrapper for delete_network_option() 1330 * 1331 * @see delete_network_option() 1332 * 1333 * @param string $option Name of the option to delete. Expected to not be SQL-escaped. 1334 * @return bool True if the option was deleted, false otherwise. 1335 */ 1336 function delete_site_option( $option ) { 1337 return delete_network_option( null, $option ); 1338 } 1339 1340 /** 1341 * Updates the value of an option that was already added for the current network. 1342 * 1343 * @since 2.8.0 1344 * @since 4.4.0 Modified into wrapper for update_network_option() 1345 * 1346 * @see update_network_option() 1347 * 1348 * @param string $option Name of the option. Expected to not be SQL-escaped. 1349 * @param mixed $value Option value. Expected to not be SQL-escaped. 1350 * @return bool True if the value was updated, false otherwise. 1351 */ 1352 function update_site_option( $option, $value ) { 1353 return update_network_option( null, $option, $value ); 1354 } 1355 1356 /** 1357 * Retrieves a network's option value based on the option name. 1358 * 1359 * @since 4.4.0 1360 * 1361 * @see get_option() 1362 * 1363 * @global wpdb $wpdb WordPress database abstraction object. 1364 * 1365 * @param int $network_id ID of the network. Can be null to default to the current network ID. 1366 * @param string $option Name of the option to retrieve. Expected to not be SQL-escaped. 1367 * @param mixed $default Optional. Value to return if the option doesn't exist. Default false. 1368 * @return mixed Value set for the option. 1369 */ 1370 function get_network_option( $network_id, $option, $default = false ) { 1371 global $wpdb; 1372 1373 if ( $network_id && ! is_numeric( $network_id ) ) { 1374 return false; 1375 } 1376 1377 $network_id = (int) $network_id; 1378 1379 // Fallback to the current network if a network ID is not specified. 1380 if ( ! $network_id ) { 1381 $network_id = get_current_network_id(); 1382 } 1383 1384 /** 1385 * Filters the value of an existing network option before it is retrieved. 1386 * 1387 * The dynamic portion of the hook name, `$option`, refers to the option name. 1388 * 1389 * Returning a truthy value from the filter will effectively short-circuit retrieval 1390 * and return the passed value instead. 1391 * 1392 * @since 2.9.0 As 'pre_site_option_' . $key 1393 * @since 3.0.0 1394 * @since 4.4.0 The `$option` parameter was added. 1395 * @since 4.7.0 The `$network_id` parameter was added. 1396 * @since 4.9.0 The `$default` parameter was added. 1397 * 1398 * @param mixed $pre_option The value to return instead of the option value. This differs 1399 * from `$default`, which is used as the fallback value in the event 1400 * the option doesn't exist elsewhere in get_network_option(). 1401 * Default false (to skip past the short-circuit). 1402 * @param string $option Option name. 1403 * @param int $network_id ID of the network. 1404 * @param mixed $default The fallback value to return if the option does not exist. 1405 * Default false. 1406 */ 1407 $pre = apply_filters( "pre_site_option_{$option}", false, $option, $network_id, $default ); 1408 1409 if ( false !== $pre ) { 1410 return $pre; 1411 } 1412 1413 // Prevent non-existent options from triggering multiple queries. 1414 $notoptions_key = "$network_id:notoptions"; 1415 $notoptions = wp_cache_get( $notoptions_key, 'site-options' ); 1416 1417 if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) { 1418 1419 /** 1420 * Filters a specific default network option. 1421 * 1422 * The dynamic portion of the hook name, `$option`, refers to the option name. 1423 * 1424 * @since 3.4.0 1425 * @since 4.4.0 The `$option` parameter was added. 1426 * @since 4.7.0 The `$network_id` parameter was added. 1427 * 1428 * @param mixed $default The value to return if the site option does not exist 1429 * in the database. 1430 * @param string $option Option name. 1431 * @param int $network_id ID of the network. 1432 */ 1433 return apply_filters( "default_site_option_{$option}", $default, $option, $network_id ); 1434 } 1435 1436 if ( ! is_multisite() ) { 1437 /** This filter is documented in wp-includes/option.php */ 1438 $default = apply_filters( 'default_site_option_' . $option, $default, $option, $network_id ); 1439 $value = get_option( $option, $default ); 1440 } else { 1441 $cache_key = "$network_id:$option"; 1442 $value = wp_cache_get( $cache_key, 'site-options' ); 1443 1444 if ( ! isset( $value ) || false === $value ) { 1445 $row = $wpdb->get_row( $wpdb->prepare( "SELECT meta_value FROM $wpdb->sitemeta WHERE meta_key = %s AND site_id = %d", $option, $network_id ) ); 1446 1447 // Has to be get_row() instead of get_var() because of funkiness with 0, false, null values. 1448 if ( is_object( $row ) ) { 1449 $value = $row->meta_value; 1450 $value = maybe_unserialize( $value ); 1451 wp_cache_set( $cache_key, $value, 'site-options' ); 1452 } else { 1453 if ( ! is_array( $notoptions ) ) { 1454 $notoptions = array(); 1455 } 1456 1457 $notoptions[ $option ] = true; 1458 wp_cache_set( $notoptions_key, $notoptions, 'site-options' ); 1459 1460 /** This filter is documented in wp-includes/option.php */ 1461 $value = apply_filters( 'default_site_option_' . $option, $default, $option, $network_id ); 1462 } 1463 } 1464 } 1465 1466 if ( ! is_array( $notoptions ) ) { 1467 $notoptions = array(); 1468 wp_cache_set( $notoptions_key, $notoptions, 'site-options' ); 1469 } 1470 1471 /** 1472 * Filters the value of an existing network option. 1473 * 1474 * The dynamic portion of the hook name, `$option`, refers to the option name. 1475 * 1476 * @since 2.9.0 As 'site_option_' . $key 1477 * @since 3.0.0 1478 * @since 4.4.0 The `$option` parameter was added. 1479 * @since 4.7.0 The `$network_id` parameter was added. 1480 * 1481 * @param mixed $value Value of network option. 1482 * @param string $option Option name. 1483 * @param int $network_id ID of the network. 1484 */ 1485 return apply_filters( "site_option_{$option}", $value, $option, $network_id ); 1486 } 1487 1488 /** 1489 * Adds a new network option. 1490 * 1491 * Existing options will not be updated. 1492 * 1493 * @since 4.4.0 1494 * 1495 * @see add_option() 1496 * 1497 * @global wpdb $wpdb WordPress database abstraction object. 1498 * 1499 * @param int $network_id ID of the network. Can be null to default to the current network ID. 1500 * @param string $option Name of the option to add. Expected to not be SQL-escaped. 1501 * @param mixed $value Option value, can be anything. Expected to not be SQL-escaped. 1502 * @return bool True if the option was added, false otherwise. 1503 */ 1504 function add_network_option( $network_id, $option, $value ) { 1505 global $wpdb; 1506 1507 if ( $network_id && ! is_numeric( $network_id ) ) { 1508 return false; 1509 } 1510 1511 $network_id = (int) $network_id; 1512 1513 // Fallback to the current network if a network ID is not specified. 1514 if ( ! $network_id ) { 1515 $network_id = get_current_network_id(); 1516 } 1517 1518 wp_protect_special_option( $option ); 1519 1520 /** 1521 * Filters the value of a specific network option before it is added. 1522 * 1523 * The dynamic portion of the hook name, `$option`, refers to the option name. 1524 * 1525 * @since 2.9.0 As 'pre_add_site_option_' . $key 1526 * @since 3.0.0 1527 * @since 4.4.0 The `$option` parameter was added. 1528 * @since 4.7.0 The `$network_id` parameter was added. 1529 * 1530 * @param mixed $value Value of network option. 1531 * @param string $option Option name. 1532 * @param int $network_id ID of the network. 1533 */ 1534 $value = apply_filters( "pre_add_site_option_{$option}", $value, $option, $network_id ); 1535 1536 $notoptions_key = "$network_id:notoptions"; 1537 1538 if ( ! is_multisite() ) { 1539 $result = add_option( $option, $value, '', 'no' ); 1540 } else { 1541 $cache_key = "$network_id:$option"; 1542 1543 // Make sure the option doesn't already exist. 1544 // We can check the 'notoptions' cache before we ask for a DB query. 1545 $notoptions = wp_cache_get( $notoptions_key, 'site-options' ); 1546 1547 if ( ! is_array( $notoptions ) || ! isset( $notoptions[ $option ] ) ) { 1548 if ( false !== get_network_option( $network_id, $option, false ) ) { 1549 return false; 1550 } 1551 } 1552 1553 $value = sanitize_option( $option, $value ); 1554 1555 $serialized_value = maybe_serialize( $value ); 1556 $result = $wpdb->insert( 1557 $wpdb->sitemeta, 1558 array( 1559 'site_id' => $network_id, 1560 'meta_key' => $option, 1561 'meta_value' => $serialized_value, 1562 ) 1563 ); 1564 1565 if ( ! $result ) { 1566 return false; 1567 } 1568 1569 wp_cache_set( $cache_key, $value, 'site-options' ); 1570 1571 // This option exists now. 1572 $notoptions = wp_cache_get( $notoptions_key, 'site-options' ); // Yes, again... we need it to be fresh. 1573 1574 if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) { 1575 unset( $notoptions[ $option ] ); 1576 wp_cache_set( $notoptions_key, $notoptions, 'site-options' ); 1577 } 1578 } 1579 1580 if ( $result ) { 1581 1582 /** 1583 * Fires after a specific network option has been successfully added. 1584 * 1585 * The dynamic portion of the hook name, `$option`, refers to the option name. 1586 * 1587 * @since 2.9.0 As "add_site_option_{$key}" 1588 * @since 3.0.0 1589 * @since 4.7.0 The `$network_id` parameter was added. 1590 * 1591 * @param string $option Name of the network option. 1592 * @param mixed $value Value of the network option. 1593 * @param int $network_id ID of the network. 1594 */ 1595 do_action( "add_site_option_{$option}", $option, $value, $network_id ); 1596 1597 /** 1598 * Fires after a network option has been successfully added. 1599 * 1600 * @since 3.0.0 1601 * @since 4.7.0 The `$network_id` parameter was added. 1602 * 1603 * @param string $option Name of the network option. 1604 * @param mixed $value Value of the network option. 1605 * @param int $network_id ID of the network. 1606 */ 1607 do_action( 'add_site_option', $option, $value, $network_id ); 1608 1609 return true; 1610 } 1611 1612 return false; 1613 } 1614 1615 /** 1616 * Removes a network option by name. 1617 * 1618 * @since 4.4.0 1619 * 1620 * @see delete_option() 1621 * 1622 * @global wpdb $wpdb WordPress database abstraction object. 1623 * 1624 * @param int $network_id ID of the network. Can be null to default to the current network ID. 1625 * @param string $option Name of the option to delete. Expected to not be SQL-escaped. 1626 * @return bool True if the option was deleted, false otherwise. 1627 */ 1628 function delete_network_option( $network_id, $option ) { 1629 global $wpdb; 1630 1631 if ( $network_id && ! is_numeric( $network_id ) ) { 1632 return false; 1633 } 1634 1635 $network_id = (int) $network_id; 1636 1637 // Fallback to the current network if a network ID is not specified. 1638 if ( ! $network_id ) { 1639 $network_id = get_current_network_id(); 1640 } 1641 1642 /** 1643 * Fires immediately before a specific network option is deleted. 1644 * 1645 * The dynamic portion of the hook name, `$option`, refers to the option name. 1646 * 1647 * @since 3.0.0 1648 * @since 4.4.0 The `$option` parameter was added. 1649 * @since 4.7.0 The `$network_id` parameter was added. 1650 * 1651 * @param string $option Option name. 1652 * @param int $network_id ID of the network. 1653 */ 1654 do_action( "pre_delete_site_option_{$option}", $option, $network_id ); 1655 1656 if ( ! is_multisite() ) { 1657 $result = delete_option( $option ); 1658 } else { 1659 $row = $wpdb->get_row( $wpdb->prepare( "SELECT meta_id FROM {$wpdb->sitemeta} WHERE meta_key = %s AND site_id = %d", $option, $network_id ) ); 1660 if ( is_null( $row ) || ! $row->meta_id ) { 1661 return false; 1662 } 1663 $cache_key = "$network_id:$option"; 1664 wp_cache_delete( $cache_key, 'site-options' ); 1665 1666 $result = $wpdb->delete( 1667 $wpdb->sitemeta, 1668 array( 1669 'meta_key' => $option, 1670 'site_id' => $network_id, 1671 ) 1672 ); 1673 } 1674 1675 if ( $result ) { 1676 1677 /** 1678 * Fires after a specific network option has been deleted. 1679 * 1680 * The dynamic portion of the hook name, `$option`, refers to the option name. 1681 * 1682 * @since 2.9.0 As "delete_site_option_{$key}" 1683 * @since 3.0.0 1684 * @since 4.7.0 The `$network_id` parameter was added. 1685 * 1686 * @param string $option Name of the network option. 1687 * @param int $network_id ID of the network. 1688 */ 1689 do_action( "delete_site_option_{$option}", $option, $network_id ); 1690 1691 /** 1692 * Fires after a network option has been deleted. 1693 * 1694 * @since 3.0.0 1695 * @since 4.7.0 The `$network_id` parameter was added. 1696 * 1697 * @param string $option Name of the network option. 1698 * @param int $network_id ID of the network. 1699 */ 1700 do_action( 'delete_site_option', $option, $network_id ); 1701 1702 return true; 1703 } 1704 1705 return false; 1706 } 1707 1708 /** 1709 * Updates the value of a network option that was already added. 1710 * 1711 * @since 4.4.0 1712 * 1713 * @see update_option() 1714 * 1715 * @global wpdb $wpdb WordPress database abstraction object. 1716 * 1717 * @param int $network_id ID of the network. Can be null to default to the current network ID. 1718 * @param string $option Name of the option. Expected to not be SQL-escaped. 1719 * @param mixed $value Option value. Expected to not be SQL-escaped. 1720 * @return bool True if the value was updated, false otherwise. 1721 */ 1722 function update_network_option( $network_id, $option, $value ) { 1723 global $wpdb; 1724 1725 if ( $network_id && ! is_numeric( $network_id ) ) { 1726 return false; 1727 } 1728 1729 $network_id = (int) $network_id; 1730 1731 // Fallback to the current network if a network ID is not specified. 1732 if ( ! $network_id ) { 1733 $network_id = get_current_network_id(); 1734 } 1735 1736 wp_protect_special_option( $option ); 1737 1738 $old_value = get_network_option( $network_id, $option, false ); 1739 1740 /** 1741 * Filters a specific network option before its value is updated. 1742 * 1743 * The dynamic portion of the hook name, `$option`, refers to the option name. 1744 * 1745 * @since 2.9.0 As 'pre_update_site_option_' . $key 1746 * @since 3.0.0 1747 * @since 4.4.0 The `$option` parameter was added. 1748 * @since 4.7.0 The `$network_id` parameter was added. 1749 * 1750 * @param mixed $value New value of the network option. 1751 * @param mixed $old_value Old value of the network option. 1752 * @param string $option Option name. 1753 * @param int $network_id ID of the network. 1754 */ 1755 $value = apply_filters( "pre_update_site_option_{$option}", $value, $old_value, $option, $network_id ); 1756 1757 /* 1758 * If the new and old values are the same, no need to update. 1759 * 1760 * Unserialized values will be adequate in most cases. If the unserialized 1761 * data differs, the (maybe) serialized data is checked to avoid 1762 * unnecessary database calls for otherwise identical object instances. 1763 * 1764 * See https://core.trac.wordpress.org/ticket/44956 1765 */ 1766 if ( $value === $old_value || maybe_serialize( $value ) === maybe_serialize( $old_value ) ) { 1767 return false; 1768 } 1769 1770 if ( false === $old_value ) { 1771 return add_network_option( $network_id, $option, $value ); 1772 } 1773 1774 $notoptions_key = "$network_id:notoptions"; 1775 $notoptions = wp_cache_get( $notoptions_key, 'site-options' ); 1776 1777 if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) { 1778 unset( $notoptions[ $option ] ); 1779 wp_cache_set( $notoptions_key, $notoptions, 'site-options' ); 1780 } 1781 1782 if ( ! is_multisite() ) { 1783 $result = update_option( $option, $value, 'no' ); 1784 } else { 1785 $value = sanitize_option( $option, $value ); 1786 1787 $serialized_value = maybe_serialize( $value ); 1788 $result = $wpdb->update( 1789 $wpdb->sitemeta, 1790 array( 'meta_value' => $serialized_value ), 1791 array( 1792 'site_id' => $network_id, 1793 'meta_key' => $option, 1794 ) 1795 ); 1796 1797 if ( $result ) { 1798 $cache_key = "$network_id:$option"; 1799 wp_cache_set( $cache_key, $value, 'site-options' ); 1800 } 1801 } 1802 1803 if ( $result ) { 1804 1805 /** 1806 * Fires after the value of a specific network option has been successfully updated. 1807 * 1808 * The dynamic portion of the hook name, `$option`, refers to the option name. 1809 * 1810 * @since 2.9.0 As "update_site_option_{$key}" 1811 * @since 3.0.0 1812 * @since 4.7.0 The `$network_id` parameter was added. 1813 * 1814 * @param string $option Name of the network option. 1815 * @param mixed $value Current value of the network option. 1816 * @param mixed $old_value Old value of the network option. 1817 * @param int $network_id ID of the network. 1818 */ 1819 do_action( "update_site_option_{$option}", $option, $value, $old_value, $network_id ); 1820 1821 /** 1822 * Fires after the value of a network option has been successfully updated. 1823 * 1824 * @since 3.0.0 1825 * @since 4.7.0 The `$network_id` parameter was added. 1826 * 1827 * @param string $option Name of the network option. 1828 * @param mixed $value Current value of the network option. 1829 * @param mixed $old_value Old value of the network option. 1830 * @param int $network_id ID of the network. 1831 */ 1832 do_action( 'update_site_option', $option, $value, $old_value, $network_id ); 1833 1834 return true; 1835 } 1836 1837 return false; 1838 } 1839 1840 /** 1841 * Deletes a site transient. 1842 * 1843 * @since 2.9.0 1844 * 1845 * @param string $transient Transient name. Expected to not be SQL-escaped. 1846 * @return bool True if the transient was deleted, false otherwise. 1847 */ 1848 function delete_site_transient( $transient ) { 1849 1850 /** 1851 * Fires immediately before a specific site transient is deleted. 1852 * 1853 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 1854 * 1855 * @since 3.0.0 1856 * 1857 * @param string $transient Transient name. 1858 */ 1859 do_action( "delete_site_transient_{$transient}", $transient ); 1860 1861 if ( wp_using_ext_object_cache() ) { 1862 $result = wp_cache_delete( $transient, 'site-transient' ); 1863 } else { 1864 $option_timeout = '_site_transient_timeout_' . $transient; 1865 $option = '_site_transient_' . $transient; 1866 $result = delete_site_option( $option ); 1867 1868 if ( $result ) { 1869 delete_site_option( $option_timeout ); 1870 } 1871 } 1872 1873 if ( $result ) { 1874 1875 /** 1876 * Fires after a transient is deleted. 1877 * 1878 * @since 3.0.0 1879 * 1880 * @param string $transient Deleted transient name. 1881 */ 1882 do_action( 'deleted_site_transient', $transient ); 1883 } 1884 1885 return $result; 1886 } 1887 1888 /** 1889 * Retrieves the value of a site transient. 1890 * 1891 * If the transient does not exist, does not have a value, or has expired, 1892 * then the return value will be false. 1893 * 1894 * @since 2.9.0 1895 * 1896 * @see get_transient() 1897 * 1898 * @param string $transient Transient name. Expected to not be SQL-escaped. 1899 * @return mixed Value of transient. 1900 */ 1901 function get_site_transient( $transient ) { 1902 1903 /** 1904 * Filters the value of an existing site transient before it is retrieved. 1905 * 1906 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 1907 * 1908 * Returning a truthy value from the filter will effectively short-circuit retrieval 1909 * and return the passed value instead. 1910 * 1911 * @since 2.9.0 1912 * @since 4.4.0 The `$transient` parameter was added. 1913 * 1914 * @param mixed $pre_site_transient The default value to return if the site transient does not exist. 1915 * Any value other than false will short-circuit the retrieval 1916 * of the transient, and return that value. 1917 * @param string $transient Transient name. 1918 */ 1919 $pre = apply_filters( "pre_site_transient_{$transient}", false, $transient ); 1920 1921 if ( false !== $pre ) { 1922 return $pre; 1923 } 1924 1925 if ( wp_using_ext_object_cache() ) { 1926 $value = wp_cache_get( $transient, 'site-transient' ); 1927 } else { 1928 // Core transients that do not have a timeout. Listed here so querying timeouts can be avoided. 1929 $no_timeout = array( 'update_core', 'update_plugins', 'update_themes' ); 1930 $transient_option = '_site_transient_' . $transient; 1931 if ( ! in_array( $transient, $no_timeout, true ) ) { 1932 $transient_timeout = '_site_transient_timeout_' . $transient; 1933 $timeout = get_site_option( $transient_timeout ); 1934 if ( false !== $timeout && $timeout < time() ) { 1935 delete_site_option( $transient_option ); 1936 delete_site_option( $transient_timeout ); 1937 $value = false; 1938 } 1939 } 1940 1941 if ( ! isset( $value ) ) { 1942 $value = get_site_option( $transient_option ); 1943 } 1944 } 1945 1946 /** 1947 * Filters the value of an existing site transient. 1948 * 1949 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 1950 * 1951 * @since 2.9.0 1952 * @since 4.4.0 The `$transient` parameter was added. 1953 * 1954 * @param mixed $value Value of site transient. 1955 * @param string $transient Transient name. 1956 */ 1957 return apply_filters( "site_transient_{$transient}", $value, $transient ); 1958 } 1959 1960 /** 1961 * Sets/updates the value of a site transient. 1962 * 1963 * You do not need to serialize values. If the value needs to be serialized, 1964 * then it will be serialized before it is set. 1965 * 1966 * @since 2.9.0 1967 * 1968 * @see set_transient() 1969 * 1970 * @param string $transient Transient name. Expected to not be SQL-escaped. Must be 1971 * 167 characters or fewer in length. 1972 * @param mixed $value Transient value. Expected to not be SQL-escaped. 1973 * @param int $expiration Optional. Time until expiration in seconds. Default 0 (no expiration). 1974 * @return bool True if the value was set, false otherwise. 1975 */ 1976 function set_site_transient( $transient, $value, $expiration = 0 ) { 1977 1978 /** 1979 * Filters the value of a specific site transient before it is set. 1980 * 1981 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 1982 * 1983 * @since 3.0.0 1984 * @since 4.4.0 The `$transient` parameter was added. 1985 * 1986 * @param mixed $value New value of site transient. 1987 * @param string $transient Transient name. 1988 */ 1989 $value = apply_filters( "pre_set_site_transient_{$transient}", $value, $transient ); 1990 1991 $expiration = (int) $expiration; 1992 1993 /** 1994 * Filters the expiration for a site transient before its value is set. 1995 * 1996 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 1997 * 1998 * @since 4.4.0 1999 * 2000 * @param int $expiration Time until expiration in seconds. Use 0 for no expiration. 2001 * @param mixed $value New value of site transient. 2002 * @param string $transient Transient name. 2003 */ 2004 $expiration = apply_filters( "expiration_of_site_transient_{$transient}", $expiration, $value, $transient ); 2005 2006 if ( wp_using_ext_object_cache() ) { 2007 $result = wp_cache_set( $transient, $value, 'site-transient', $expiration ); 2008 } else { 2009 $transient_timeout = '_site_transient_timeout_' . $transient; 2010 $option = '_site_transient_' . $transient; 2011 2012 if ( false === get_site_option( $option ) ) { 2013 if ( $expiration ) { 2014 add_site_option( $transient_timeout, time() + $expiration ); 2015 } 2016 $result = add_site_option( $option, $value ); 2017 } else { 2018 if ( $expiration ) { 2019 update_site_option( $transient_timeout, time() + $expiration ); 2020 } 2021 $result = update_site_option( $option, $value ); 2022 } 2023 } 2024 2025 if ( $result ) { 2026 2027 /** 2028 * Fires after the value for a specific site transient has been set. 2029 * 2030 * The dynamic portion of the hook name, `$transient`, refers to the transient name. 2031 * 2032 * @since 3.0.0 2033 * @since 4.4.0 The `$transient` parameter was added 2034 * 2035 * @param mixed $value Site transient value. 2036 * @param int $expiration Time until expiration in seconds. 2037 * @param string $transient Transient name. 2038 */ 2039 do_action( "set_site_transient_{$transient}", $value, $expiration, $transient ); 2040 2041 /** 2042 * Fires after the value for a site transient has been set. 2043 * 2044 * @since 3.0.0 2045 * 2046 * @param string $transient The name of the site transient. 2047 * @param mixed $value Site transient value. 2048 * @param int $expiration Time until expiration in seconds. 2049 */ 2050 do_action( 'setted_site_transient', $transient, $value, $expiration ); 2051 } 2052 2053 return $result; 2054 } 2055 2056 /** 2057 * Registers default settings available in WordPress. 2058 * 2059 * The settings registered here are primarily useful for the REST API, so this 2060 * does not encompass all settings available in WordPress. 2061 * 2062 * @since 4.7.0 2063 */ 2064 function register_initial_settings() { 2065 register_setting( 2066 'general', 2067 'blogname', 2068 array( 2069 'show_in_rest' => array( 2070 'name' => 'title', 2071 ), 2072 'type' => 'string', 2073 'description' => __( 'Site title.' ), 2074 ) 2075 ); 2076 2077 register_setting( 2078 'general', 2079 'blogdescription', 2080 array( 2081 'show_in_rest' => array( 2082 'name' => 'description', 2083 ), 2084 'type' => 'string', 2085 'description' => __( 'Site tagline.' ), 2086 ) 2087 ); 2088 2089 if ( ! is_multisite() ) { 2090 register_setting( 2091 'general', 2092 'siteurl', 2093 array( 2094 'show_in_rest' => array( 2095 'name' => 'url', 2096 'schema' => array( 2097 'format' => 'uri', 2098 ), 2099 ), 2100 'type' => 'string', 2101 'description' => __( 'Site URL.' ), 2102 ) 2103 ); 2104 } 2105 2106 if ( ! is_multisite() ) { 2107 register_setting( 2108 'general', 2109 'admin_email', 2110 array( 2111 'show_in_rest' => array( 2112 'name' => 'email', 2113 'schema' => array( 2114 'format' => 'email', 2115 ), 2116 ), 2117 'type' => 'string', 2118 'description' => __( 'This address is used for admin purposes, like new user notification.' ), 2119 ) 2120 ); 2121 } 2122 2123 register_setting( 2124 'general', 2125 'timezone_string', 2126 array( 2127 'show_in_rest' => array( 2128 'name' => 'timezone', 2129 ), 2130 'type' => 'string', 2131 'description' => __( 'A city in the same timezone as you.' ), 2132 ) 2133 ); 2134 2135 register_setting( 2136 'general', 2137 'date_format', 2138 array( 2139 'show_in_rest' => true, 2140 'type' => 'string', 2141 'description' => __( 'A date format for all date strings.' ), 2142 ) 2143 ); 2144 2145 register_setting( 2146 'general', 2147 'time_format', 2148 array( 2149 'show_in_rest' => true, 2150 'type' => 'string', 2151 'description' => __( 'A time format for all time strings.' ), 2152 ) 2153 ); 2154 2155 register_setting( 2156 'general', 2157 'start_of_week', 2158 array( 2159 'show_in_rest' => true, 2160 'type' => 'integer', 2161 'description' => __( 'A day number of the week that the week should start on.' ), 2162 ) 2163 ); 2164 2165 register_setting( 2166 'general', 2167 'WPLANG', 2168 array( 2169 'show_in_rest' => array( 2170 'name' => 'language', 2171 ), 2172 'type' => 'string', 2173 'description' => __( 'WordPress locale code.' ), 2174 'default' => 'en_US', 2175 ) 2176 ); 2177 2178 register_setting( 2179 'writing', 2180 'use_smilies', 2181 array( 2182 'show_in_rest' => true, 2183 'type' => 'boolean', 2184 'description' => __( 'Convert emoticons like :-) and :-P to graphics on display.' ), 2185 'default' => true, 2186 ) 2187 ); 2188 2189 register_setting( 2190 'writing', 2191 'default_category', 2192 array( 2193 'show_in_rest' => true, 2194 'type' => 'integer', 2195 'description' => __( 'Default post category.' ), 2196 ) 2197 ); 2198 2199 register_setting( 2200 'writing', 2201 'default_post_format', 2202 array( 2203 'show_in_rest' => true, 2204 'type' => 'string', 2205 'description' => __( 'Default post format.' ), 2206 ) 2207 ); 2208 2209 register_setting( 2210 'reading', 2211 'posts_per_page', 2212 array( 2213 'show_in_rest' => true, 2214 'type' => 'integer', 2215 'description' => __( 'Blog pages show at most.' ), 2216 'default' => 10, 2217 ) 2218 ); 2219 2220 register_setting( 2221 'discussion', 2222 'default_ping_status', 2223 array( 2224 'show_in_rest' => array( 2225 'schema' => array( 2226 'enum' => array( 'open', 'closed' ), 2227 ), 2228 ), 2229 'type' => 'string', 2230 'description' => __( 'Allow link notifications from other blogs (pingbacks and trackbacks) on new articles.' ), 2231 ) 2232 ); 2233 2234 register_setting( 2235 'discussion', 2236 'default_comment_status', 2237 array( 2238 'show_in_rest' => array( 2239 'schema' => array( 2240 'enum' => array( 'open', 'closed' ), 2241 ), 2242 ), 2243 'type' => 'string', 2244 'description' => __( 'Allow people to submit comments on new posts.' ), 2245 ) 2246 ); 2247 } 2248 2249 /** 2250 * Registers a setting and its data. 2251 * 2252 * @since 2.7.0 2253 * @since 3.0.0 The `misc` option group was deprecated. 2254 * @since 3.5.0 The `privacy` option group was deprecated. 2255 * @since 4.7.0 `$args` can be passed to set flags on the setting, similar to `register_meta()`. 2256 * @since 5.5.0 `$new_whitelist_options` was renamed to `$new_allowed_options`. 2257 * Please consider writing more inclusive code. 2258 * 2259 * @global array $new_allowed_options 2260 * @global array $wp_registered_settings 2261 * 2262 * @param string $option_group A settings group name. Should correspond to an allowed option key name. 2263 * Default allowed option key names include 'general', 'discussion', 'media', 2264 * 'reading', 'writing', and 'options'. 2265 * @param string $option_name The name of an option to sanitize and save. 2266 * @param array $args { 2267 * Data used to describe the setting when registered. 2268 * 2269 * @type string $type The type of data associated with this setting. 2270 * Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'. 2271 * @type string $description A description of the data attached to this setting. 2272 * @type callable $sanitize_callback A callback function that sanitizes the option's value. 2273 * @type bool|array $show_in_rest Whether data associated with this setting should be included in the REST API. 2274 * When registering complex settings, this argument may optionally be an 2275 * array with a 'schema' key. 2276 * @type mixed $default Default value when calling `get_option()`. 2277 * } 2278 */ 2279 function register_setting( $option_group, $option_name, $args = array() ) { 2280 global $new_allowed_options, $wp_registered_settings; 2281 2282 /* 2283 * In 5.5.0, the `$new_whitelist_options` global variable was renamed to `$new_allowed_options`. 2284 * Please consider writing more inclusive code. 2285 */ 2286 $GLOBALS['new_whitelist_options'] = &$new_allowed_options; 2287 2288 $defaults = array( 2289 'type' => 'string', 2290 'group' => $option_group, 2291 'description' => '', 2292 'sanitize_callback' => null, 2293 'show_in_rest' => false, 2294 ); 2295 2296 // Back-compat: old sanitize callback is added. 2297 if ( is_callable( $args ) ) { 2298 $args = array( 2299 'sanitize_callback' => $args, 2300 ); 2301 } 2302 2303 /** 2304 * Filters the registration arguments when registering a setting. 2305 * 2306 * @since 4.7.0 2307 * 2308 * @param array $args Array of setting registration arguments. 2309 * @param array $defaults Array of default arguments. 2310 * @param string $option_group Setting group. 2311 * @param string $option_name Setting name. 2312 */ 2313 $args = apply_filters( 'register_setting_args', $args, $defaults, $option_group, $option_name ); 2314 2315 $args = wp_parse_args( $args, $defaults ); 2316 2317 // Require an item schema when registering settings with an array type. 2318 if ( false !== $args['show_in_rest'] && 'array' === $args['type'] && ( ! is_array( $args['show_in_rest'] ) || ! isset( $args['show_in_rest']['schema']['items'] ) ) ) { 2319 _doing_it_wrong( __FUNCTION__, __( 'When registering an "array" setting to show in the REST API, you must specify the schema for each array item in "show_in_rest.schema.items".' ), '5.4.0' ); 2320 } 2321 2322 if ( ! is_array( $wp_registered_settings ) ) { 2323 $wp_registered_settings = array(); 2324 } 2325 2326 if ( 'misc' === $option_group ) { 2327 _deprecated_argument( 2328 __FUNCTION__, 2329 '3.0.0', 2330 sprintf( 2331 /* translators: %s: misc */ 2332 __( 'The "%s" options group has been removed. Use another settings group.' ), 2333 'misc' 2334 ) 2335 ); 2336 $option_group = 'general'; 2337 } 2338 2339 if ( 'privacy' === $option_group ) { 2340 _deprecated_argument( 2341 __FUNCTION__, 2342 '3.5.0', 2343 sprintf( 2344 /* translators: %s: privacy */ 2345 __( 'The "%s" options group has been removed. Use another settings group.' ), 2346 'privacy' 2347 ) 2348 ); 2349 $option_group = 'reading'; 2350 } 2351 2352 $new_allowed_options[ $option_group ][] = $option_name; 2353 2354 if ( ! empty( $args['sanitize_callback'] ) ) { 2355 add_filter( "sanitize_option_{$option_name}", $args['sanitize_callback'] ); 2356 } 2357 if ( array_key_exists( 'default', $args ) ) { 2358 add_filter( "default_option_{$option_name}", 'filter_default_option', 10, 3 ); 2359 } 2360 2361 /** 2362 * Fires immediately before the setting is registered but after its filters are in place. 2363 * 2364 * @since 5.5.0 2365 * 2366 * @param string $option_group Setting group. 2367 * @param string $option_name Setting name. 2368 * @param array $args Array of setting registration arguments. 2369 */ 2370 do_action( 'register_setting', $option_group, $option_name, $args ); 2371 2372 $wp_registered_settings[ $option_name ] = $args; 2373 } 2374 2375 /** 2376 * Unregisters a setting. 2377 * 2378 * @since 2.7.0 2379 * @since 4.7.0 `$sanitize_callback` was deprecated. The callback from `register_setting()` is now used instead. 2380 * @since 5.5.0 `$new_whitelist_options` was renamed to `$new_allowed_options`. 2381 * Please consider writing more inclusive code. 2382 * 2383 * @global array $new_allowed_options 2384 * @global array $wp_registered_settings 2385 * 2386 * @param string $option_group The settings group name used during registration. 2387 * @param string $option_name The name of the option to unregister. 2388 * @param callable|string $deprecated Deprecated. 2389 */ 2390 function unregister_setting( $option_group, $option_name, $deprecated = '' ) { 2391 global $new_allowed_options, $wp_registered_settings; 2392 2393 /* 2394 * In 5.5.0, the `$new_whitelist_options` global variable was renamed to `$new_allowed_options`. 2395 * Please consider writing more inclusive code. 2396 */ 2397 $GLOBALS['new_whitelist_options'] = &$new_allowed_options; 2398 2399 if ( 'misc' === $option_group ) { 2400 _deprecated_argument( 2401 __FUNCTION__, 2402 '3.0.0', 2403 sprintf( 2404 /* translators: %s: misc */ 2405 __( 'The "%s" options group has been removed. Use another settings group.' ), 2406 'misc' 2407 ) 2408 ); 2409 $option_group = 'general'; 2410 } 2411 2412 if ( 'privacy' === $option_group ) { 2413 _deprecated_argument( 2414 __FUNCTION__, 2415 '3.5.0', 2416 sprintf( 2417 /* translators: %s: privacy */ 2418 __( 'The "%s" options group has been removed. Use another settings group.' ), 2419 'privacy' 2420 ) 2421 ); 2422 $option_group = 'reading'; 2423 } 2424 2425 $pos = array_search( $option_name, (array) $new_allowed_options[ $option_group ], true ); 2426 2427 if ( false !== $pos ) { 2428 unset( $new_allowed_options[ $option_group ][ $pos ] ); 2429 } 2430 2431 if ( '' !== $deprecated ) { 2432 _deprecated_argument( 2433 __FUNCTION__, 2434 '4.7.0', 2435 sprintf( 2436 /* translators: 1: $sanitize_callback, 2: register_setting() */ 2437 __( '%1$s is deprecated. The callback from %2$s is used instead.' ), 2438 '<code>$sanitize_callback</code>', 2439 '<code>register_setting()</code>' 2440 ) 2441 ); 2442 remove_filter( "sanitize_option_{$option_name}", $deprecated ); 2443 } 2444 2445 if ( isset( $wp_registered_settings[ $option_name ] ) ) { 2446 // Remove the sanitize callback if one was set during registration. 2447 if ( ! empty( $wp_registered_settings[ $option_name ]['sanitize_callback'] ) ) { 2448 remove_filter( "sanitize_option_{$option_name}", $wp_registered_settings[ $option_name ]['sanitize_callback'] ); 2449 } 2450 2451 // Remove the default filter if a default was provided during registration. 2452 if ( array_key_exists( 'default', $wp_registered_settings[ $option_name ] ) ) { 2453 remove_filter( "default_option_{$option_name}", 'filter_default_option', 10 ); 2454 } 2455 2456 /** 2457 * Fires immediately before the setting is unregistered and after its filters have been removed. 2458 * 2459 * @since 5.5.0 2460 * 2461 * @param string $option_group Setting group. 2462 * @param string $option_name Setting name. 2463 */ 2464 do_action( 'unregister_setting', $option_group, $option_name ); 2465 2466 unset( $wp_registered_settings[ $option_name ] ); 2467 } 2468 } 2469 2470 /** 2471 * Retrieves an array of registered settings. 2472 * 2473 * @since 4.7.0 2474 * 2475 * @global array $wp_registered_settings 2476 * 2477 * @return array List of registered settings, keyed by option name. 2478 */ 2479 function get_registered_settings() { 2480 global $wp_registered_settings; 2481 2482 if ( ! is_array( $wp_registered_settings ) ) { 2483 return array(); 2484 } 2485 2486 return $wp_registered_settings; 2487 } 2488 2489 /** 2490 * Filters the default value for the option. 2491 * 2492 * For settings which register a default setting in `register_setting()`, this 2493 * function is added as a filter to `default_option_{$option}`. 2494 * 2495 * @since 4.7.0 2496 * 2497 * @param mixed $default Existing default value to return. 2498 * @param string $option Option name. 2499 * @param bool $passed_default Was `get_option()` passed a default value? 2500 * @return mixed Filtered default value. 2501 */ 2502 function filter_default_option( $default, $option, $passed_default ) { 2503 if ( $passed_default ) { 2504 return $default; 2505 } 2506 2507 $registered = get_registered_settings(); 2508 if ( empty( $registered[ $option ] ) ) { 2509 return $default; 2510 } 2511 2512 return $registered[ $option ]['default']; 2513 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Wed Sep 22 01:00:04 2021 | Cross-referenced by PHPXref 0.7.1 |