| 1 |
<?php |
| 2 |
/** |
| 3 |
* CMB2 Base - Base object functionality. |
| 4 |
* |
| 5 |
* @category WordPress_Plugin |
| 6 |
* @package CMB2 |
| 7 |
* @author CMB2 team |
| 8 |
* @license GPL-2.0+ |
| 9 |
* @link https://cmb2.io |
| 10 |
* |
| 11 |
* @property-read $args The objects array of properties/arguments. |
| 12 |
* @property-read $meta_box The objects array of properties/arguments. |
| 13 |
* @property-read $properties The objects array of properties/arguments. |
| 14 |
* @property-read $cmb_id Current CMB2 instance ID |
| 15 |
* @property-read $object_id Object ID |
| 16 |
* @property-read $object_type Type of object being handled. (e.g., post, user, comment, or term) |
| 17 |
*/ |
| 18 |
#[AllowDynamicProperties] // phpcs:ignore PHPCompatibility.Attributes.NewAttributes -- Back-compat: allow dynamic props (PHP 8.2+) on this class + subclasses. |
| 19 |
abstract class CMB2_Base { |
| 20 |
|
| 21 |
/** |
| 22 |
* Current CMB2 instance ID |
| 23 |
* |
| 24 |
* @var string |
| 25 |
* @since 2.2.3 |
| 26 |
*/ |
| 27 |
protected $cmb_id = ''; |
| 28 |
|
| 29 |
/** |
| 30 |
* The object properties name. |
| 31 |
* |
| 32 |
* @var string |
| 33 |
* @since 2.2.3 |
| 34 |
*/ |
| 35 |
protected $properties_name = 'meta_box'; |
| 36 |
|
| 37 |
/** |
| 38 |
* Object ID |
| 39 |
* |
| 40 |
* @var mixed |
| 41 |
* @since 2.2.3 |
| 42 |
*/ |
| 43 |
protected $object_id = 0; |
| 44 |
|
| 45 |
/** |
| 46 |
* Type of object being handled. (e.g., post, user, comment, or term) |
| 47 |
* |
| 48 |
* @var string |
| 49 |
* @since 2.2.3 |
| 50 |
*/ |
| 51 |
protected $object_type = ''; |
| 52 |
|
| 53 |
/** |
| 54 |
* Array of key => value data for saving. Likely $_POST data. |
| 55 |
* |
| 56 |
* @var array |
| 57 |
* @since 2.2.3 |
| 58 |
*/ |
| 59 |
public $data_to_save = array(); |
| 60 |
|
| 61 |
/** |
| 62 |
* Array of field param callback results |
| 63 |
* |
| 64 |
* @var array |
| 65 |
* @since 2.0.0 |
| 66 |
*/ |
| 67 |
protected $callback_results = array(); |
| 68 |
|
| 69 |
/** |
| 70 |
* The deprecated_param method deprecated param message signature. |
| 71 |
*/ |
| 72 |
const DEPRECATED_PARAM = 1; |
| 73 |
|
| 74 |
/** |
| 75 |
* The deprecated_param method deprecated callback param message signature. |
| 76 |
*/ |
| 77 |
const DEPRECATED_CB_PARAM = 2; |
| 78 |
|
| 79 |
/** |
| 80 |
* Get started |
| 81 |
* |
| 82 |
* @since 2.2.3 |
| 83 |
* @param array $args Object properties array. |
| 84 |
*/ |
| 85 |
public function __construct( $args = array() ) { |
| 86 |
if ( ! empty( $args ) ) { |
| 87 |
foreach ( array( |
| 88 |
'cmb_id', |
| 89 |
'properties_name', |
| 90 |
'object_id', |
| 91 |
'object_type', |
| 92 |
'data_to_save', |
| 93 |
) as $object_prop ) { |
| 94 |
if ( isset( $args[ $object_prop ] ) ) { |
| 95 |
$this->{$object_prop} = $args[ $object_prop ]; |
| 96 |
} |
| 97 |
} |
| 98 |
} |
| 99 |
} |
| 100 |
|
| 101 |
/** |
| 102 |
* Returns the object ID |
| 103 |
* |
| 104 |
* @since 2.2.3 |
| 105 |
* @param integer $object_id Object ID. |
| 106 |
* @return integer Object ID |
| 107 |
*/ |
| 108 |
public function object_id( $object_id = 0 ) { |
| 109 |
if ( $object_id ) { |
| 110 |
$this->object_id = $object_id; |
| 111 |
} |
| 112 |
|
| 113 |
return $this->object_id; |
| 114 |
} |
| 115 |
|
| 116 |
/** |
| 117 |
* Returns the object type |
| 118 |
* |
| 119 |
* @since 2.2.3 |
| 120 |
* @param string $object_type Object Type. |
| 121 |
* @return string Object type |
| 122 |
*/ |
| 123 |
public function object_type( $object_type = '' ) { |
| 124 |
if ( $object_type ) { |
| 125 |
$this->object_type = $object_type; |
| 126 |
} |
| 127 |
|
| 128 |
return $this->object_type; |
| 129 |
} |
| 130 |
|
| 131 |
/** |
| 132 |
* Get the object type for the current page, based on the $pagenow global. |
| 133 |
* |
| 134 |
* @since 2.2.2 |
| 135 |
* @return string Page object type name. |
| 136 |
*/ |
| 137 |
public function current_object_type() { |
| 138 |
global $pagenow; |
| 139 |
$type = 'post'; |
| 140 |
|
| 141 |
if ( in_array( $pagenow, array( 'user-edit.php', 'profile.php', 'user-new.php' ), true ) ) { |
| 142 |
$type = 'user'; |
| 143 |
} |
| 144 |
|
| 145 |
if ( in_array( $pagenow, array( 'edit-comments.php', 'comment.php' ), true ) ) { |
| 146 |
$type = 'comment'; |
| 147 |
} |
| 148 |
|
| 149 |
if ( in_array( $pagenow, array( 'edit-tags.php', 'term.php' ), true ) ) { |
| 150 |
$type = 'term'; |
| 151 |
} |
| 152 |
|
| 153 |
return $type; |
| 154 |
} |
| 155 |
|
| 156 |
/** |
| 157 |
* Set object property. |
| 158 |
* |
| 159 |
* @since 2.2.2 |
| 160 |
* @param string $property Metabox config property to retrieve. |
| 161 |
* @param mixed $value Value to set if no value found. |
| 162 |
* @return mixed Metabox config property value or false. |
| 163 |
*/ |
| 164 |
public function set_prop( $property, $value ) { |
| 165 |
$this->{$this->properties_name}[ $property ] = $value; |
| 166 |
|
| 167 |
return $this->prop( $property ); |
| 168 |
} |
| 169 |
|
| 170 |
/** |
| 171 |
* Get object property and optionally set a fallback |
| 172 |
* |
| 173 |
* @since 2.0.0 |
| 174 |
* @param string $property Metabox config property to retrieve. |
| 175 |
* @param mixed $fallback Fallback value to set if no value found. |
| 176 |
* @return mixed Metabox config property value or false |
| 177 |
*/ |
| 178 |
public function prop( $property, $fallback = null ) { |
| 179 |
if ( array_key_exists( $property, $this->{$this->properties_name} ) ) { |
| 180 |
return $this->{$this->properties_name}[ $property ]; |
| 181 |
} elseif ( $fallback ) { |
| 182 |
return $this->{$this->properties_name}[ $property ] = $fallback; |
| 183 |
} |
| 184 |
} |
| 185 |
|
| 186 |
/** |
| 187 |
* Get default field arguments specific to this CMB2 object. |
| 188 |
* |
| 189 |
* @since 2.2.0 |
| 190 |
* @param array $field_args Metabox field config array. |
| 191 |
* @param CMB2_Field $field_group (optional) CMB2_Field object (group parent). |
| 192 |
* @return array Array of field arguments. |
| 193 |
*/ |
| 194 |
protected function get_default_args( $field_args, $field_group = null ) { |
| 195 |
if ( $field_group ) { |
| 196 |
$args = array( |
| 197 |
'field_args' => $field_args, |
| 198 |
'group_field' => $field_group, |
| 199 |
); |
| 200 |
} else { |
| 201 |
$args = array( |
| 202 |
'field_args' => $field_args, |
| 203 |
'object_type' => $this->object_type(), |
| 204 |
'object_id' => $this->object_id(), |
| 205 |
'cmb_id' => $this->cmb_id, |
| 206 |
); |
| 207 |
} |
| 208 |
|
| 209 |
return $args; |
| 210 |
} |
| 211 |
|
| 212 |
/** |
| 213 |
* Get a new field object specific to this CMB2 object. |
| 214 |
* |
| 215 |
* @since 2.2.0 |
| 216 |
* @param array $field_args Metabox field config array. |
| 217 |
* @param CMB2_Field $field_group (optional) CMB2_Field object (group parent). |
| 218 |
* @return CMB2_Field CMB2_Field object |
| 219 |
*/ |
| 220 |
protected function get_new_field( $field_args, $field_group = null ) { |
| 221 |
return new CMB2_Field( $this->get_default_args( $field_args, $field_group ) ); |
| 222 |
} |
| 223 |
|
| 224 |
/** |
| 225 |
* Determine whether this cmb object should show, based on the 'show_on_cb' callback. |
| 226 |
* |
| 227 |
* @since 2.0.9 |
| 228 |
* |
| 229 |
* @return bool Whether this cmb should be shown. |
| 230 |
*/ |
| 231 |
public function should_show() { |
| 232 |
// Default to showing this cmb |
| 233 |
$show = true; |
| 234 |
|
| 235 |
// Use the callback to determine showing the cmb, if it exists. |
| 236 |
if ( is_callable( $this->prop( 'show_on_cb' ) ) ) { |
| 237 |
$show = (bool) call_user_func( $this->prop( 'show_on_cb' ), $this ); |
| 238 |
} |
| 239 |
|
| 240 |
return $show; |
| 241 |
} |
| 242 |
|
| 243 |
/** |
| 244 |
* Displays the results of the param callbacks. |
| 245 |
* |
| 246 |
* @since 2.0.0 |
| 247 |
* @param string $param Field parameter. |
| 248 |
*/ |
| 249 |
public function peform_param_callback( $param ) { |
| 250 |
echo $this->get_param_callback_result( $param ); |
| 251 |
} |
| 252 |
|
| 253 |
/** |
| 254 |
* Store results of the param callbacks for continual access |
| 255 |
* |
| 256 |
* @since 2.0.0 |
| 257 |
* @param string $param Field parameter. |
| 258 |
* @return mixed Results of param/param callback |
| 259 |
*/ |
| 260 |
public function get_param_callback_result( $param ) { |
| 261 |
|
| 262 |
// If we've already retrieved this param's value. |
| 263 |
if ( array_key_exists( $param, $this->callback_results ) ) { |
| 264 |
|
| 265 |
// Send it back. |
| 266 |
return $this->callback_results[ $param ]; |
| 267 |
} |
| 268 |
|
| 269 |
// Check if parameter has registered a callback. |
| 270 |
if ( $cb = $this->maybe_callback( $param ) ) { |
| 271 |
|
| 272 |
// Ok, callback is good, let's run it and store the result. |
| 273 |
ob_start(); |
| 274 |
$returned = $this->do_callback( $cb ); |
| 275 |
|
| 276 |
// Grab the result from the output buffer and store it. |
| 277 |
$echoed = ob_get_clean(); |
| 278 |
|
| 279 |
// This checks if the user returned or echoed their callback. |
| 280 |
// Defaults to using the echoed value. |
| 281 |
$this->callback_results[ $param ] = $echoed ? $echoed : $returned; |
| 282 |
|
| 283 |
} else { |
| 284 |
|
| 285 |
// Otherwise just get whatever is there. |
| 286 |
$this->callback_results[ $param ] = isset( $this->{$this->properties_name}[ $param ] ) ? $this->{$this->properties_name}[ $param ] : false; |
| 287 |
} |
| 288 |
|
| 289 |
return $this->callback_results[ $param ]; |
| 290 |
} |
| 291 |
|
| 292 |
/** |
| 293 |
* Unset the cached results of the param callback. |
| 294 |
* |
| 295 |
* @since 2.2.6 |
| 296 |
* @param string $param Field parameter. |
| 297 |
* @return CMB2_Base |
| 298 |
*/ |
| 299 |
public function unset_param_callback_cache( $param ) { |
| 300 |
if ( isset( $this->callback_results[ $param ] ) ) { |
| 301 |
unset( $this->callback_results[ $param ] ); |
| 302 |
} |
| 303 |
|
| 304 |
return $this; |
| 305 |
} |
| 306 |
|
| 307 |
/** |
| 308 |
* Handles the parameter callbacks, and passes this object as parameter. |
| 309 |
* |
| 310 |
* @since 2.2.3 |
| 311 |
* @param callable $cb The callback method/function/closure. |
| 312 |
* @param mixed $additional_params Any additoinal parameters which should be passed to the callback. |
| 313 |
* @return mixed Return of the callback function. |
| 314 |
*/ |
| 315 |
protected function do_callback( $cb, $additional_params = null ) { |
| 316 |
return call_user_func( $cb, $this->{$this->properties_name}, $this, $additional_params ); |
| 317 |
} |
| 318 |
|
| 319 |
/** |
| 320 |
* Checks if field has a callback value |
| 321 |
* |
| 322 |
* @since 1.0.1 |
| 323 |
* @param string $cb Callback string. |
| 324 |
* @return mixed NULL, false for NO validation, or $cb string if it exists. |
| 325 |
*/ |
| 326 |
public function maybe_callback( $cb ) { |
| 327 |
$args = $this->{$this->properties_name}; |
| 328 |
if ( ! isset( $args[ $cb ] ) ) { |
| 329 |
return null; |
| 330 |
} |
| 331 |
|
| 332 |
// Check if requesting explicitly false. |
| 333 |
$cb = false !== $args[ $cb ] && 'false' !== $args[ $cb ] ? $args[ $cb ] : false; |
| 334 |
|
| 335 |
// If requesting NO validation, return false. |
| 336 |
if ( ! $cb ) { |
| 337 |
return false; |
| 338 |
} |
| 339 |
|
| 340 |
if ( is_callable( $cb ) ) { |
| 341 |
return $cb; |
| 342 |
} |
| 343 |
|
| 344 |
return null; |
| 345 |
} |
| 346 |
|
| 347 |
/** |
| 348 |
* Checks if this object has parameter corresponding to the given filter |
| 349 |
* which is callable. If so, it registers the callback, and if not, |
| 350 |
* converts the maybe-modified $val to a boolean for return. |
| 351 |
* |
| 352 |
* The registered handlers will have a parameter name which matches the filter, except: |
| 353 |
* - The 'cmb2_api' prefix will be removed |
| 354 |
* - A '_cb' suffix will be added (to stay inline with other '*_cb' parameters). |
| 355 |
* |
| 356 |
* @since 2.2.3 |
| 357 |
* |
| 358 |
* @param string $hook_name The hook name. |
| 359 |
* @param bool $val The default value. |
| 360 |
* @param string $hook_function The hook function. Default: 'add_filter'. |
| 361 |
* |
| 362 |
* @return null|bool Null if hook is registered, or bool for value. |
| 363 |
*/ |
| 364 |
public function maybe_hook_parameter( $hook_name, $val = null, $hook_function = 'add_filter' ) { |
| 365 |
|
| 366 |
// Remove filter prefix, add param suffix. |
| 367 |
$parameter = substr( $hook_name, strlen( 'cmb2_api_' ) ) . '_cb'; |
| 368 |
|
| 369 |
return self::maybe_hook( |
| 370 |
$this->prop( $parameter, $val ), |
| 371 |
$hook_name, |
| 372 |
$hook_function |
| 373 |
); |
| 374 |
} |
| 375 |
|
| 376 |
/** |
| 377 |
* Checks if given value is callable, and registers the callback. |
| 378 |
* If is non-callable, converts the $val to a boolean for return. |
| 379 |
* |
| 380 |
* @since 2.2.3 |
| 381 |
* |
| 382 |
* @param bool $val The default value. |
| 383 |
* @param string $hook_name The hook name. |
| 384 |
* @param string $hook_function The hook function. |
| 385 |
* |
| 386 |
* @return null|bool Null if hook is registered, or bool for value. |
| 387 |
*/ |
| 388 |
public static function maybe_hook( $val, $hook_name, $hook_function ) { |
| 389 |
if ( is_callable( $val ) ) { |
| 390 |
call_user_func( $hook_function, $hook_name, $val, 10, 2 ); |
| 391 |
return null; |
| 392 |
} |
| 393 |
|
| 394 |
// Cast to bool. |
| 395 |
return ! ! $val; |
| 396 |
} |
| 397 |
|
| 398 |
/** |
| 399 |
* Mark a param as deprecated and inform when it has been used. |
| 400 |
* |
| 401 |
* There is a default WordPress hook deprecated_argument_run that will be called |
| 402 |
* that can be used to get the backtrace up to what file and function used the |
| 403 |
* deprecated argument. |
| 404 |
* |
| 405 |
* The current behavior is to trigger a user error if WP_DEBUG is true. |
| 406 |
* |
| 407 |
* @since 2.2.3 |
| 408 |
* |
| 409 |
* @param string $function The function that was called. |
| 410 |
* @param string $version The version of CMB2 that deprecated the argument used. |
| 411 |
* @param string $message Optional. A message regarding the change, or numeric |
| 412 |
* key to generate message from additional arguments. |
| 413 |
* Default null. |
| 414 |
*/ |
| 415 |
protected function deprecated_param( $function, $version, $message = null ) { |
| 416 |
|
| 417 |
$args = func_get_args(); |
| 418 |
|
| 419 |
if ( is_numeric( $message ) ) { |
| 420 |
|
| 421 |
switch ( $message ) { |
| 422 |
|
| 423 |
case self::DEPRECATED_PARAM: |
| 424 |
// translators: 1: deprecated field parameter name, 2: replacement parameter name. |
| 425 |
$message = sprintf( __( 'The "%1$s" field parameter has been deprecated in favor of the "%2$s" parameter.', 'cmb2' ), $args[3], $args[4] ); |
| 426 |
break; |
| 427 |
|
| 428 |
case self::DEPRECATED_CB_PARAM: |
| 429 |
// translators: 1: deprecated callback parameter name, 2: replacement parameter name. |
| 430 |
$message = sprintf( __( 'Using the "%1$s" field parameter as a callback has been deprecated in favor of the "%2$s" parameter.', 'cmb2' ), $args[3], $args[4] ); |
| 431 |
break; |
| 432 |
|
| 433 |
default: |
| 434 |
$message = null; |
| 435 |
break; |
| 436 |
} |
| 437 |
} |
| 438 |
|
| 439 |
/** |
| 440 |
* Fires when a deprecated argument is called. This is a WP core action. |
| 441 |
* |
| 442 |
* @since 2.2.3 |
| 443 |
* |
| 444 |
* @param string $function The function that was called. |
| 445 |
* @param string $message A message regarding the change. |
| 446 |
* @param string $version The version of CMB2 that deprecated the argument used. |
| 447 |
*/ |
| 448 |
do_action( 'deprecated_argument_run', $function, $message, $version ); |
| 449 |
|
| 450 |
/** |
| 451 |
* Filters whether to trigger an error for deprecated arguments. This is a WP core filter. |
| 452 |
* |
| 453 |
* @since 2.2.3 |
| 454 |
* |
| 455 |
* @param bool $trigger Whether to trigger the error for deprecated arguments. Default true. |
| 456 |
*/ |
| 457 |
if ( defined( 'WP_DEBUG' ) && WP_DEBUG && apply_filters( 'deprecated_argument_trigger_error', true ) ) { |
| 458 |
if ( function_exists( '__' ) ) { |
| 459 |
if ( ! is_null( $message ) ) { |
| 460 |
// translators: 1: function name, 2: version number, 3: additional message. |
| 461 |
trigger_error( sprintf( __( '%1$s was called with a parameter that is <strong>deprecated</strong> since version %2$s! %3$s', 'cmb2' ), $function, $version, $message ) ); |
| 462 |
} else { |
| 463 |
// translators: 1: function name, 2: version number. |
| 464 |
trigger_error( sprintf( __( '%1$s was called with a parameter that is <strong>deprecated</strong> since version %2$s with no alternative available.', 'cmb2' ), $function, $version ) ); |
| 465 |
} |
| 466 |
} else { |
| 467 |
if ( ! is_null( $message ) ) { |
| 468 |
trigger_error( sprintf( '%1$s was called with a parameter that is <strong>deprecated</strong> since version %2$s! %3$s', $function, $version, $message ) ); |
| 469 |
} else { |
| 470 |
trigger_error( sprintf( '%1$s was called with a parameter that is <strong>deprecated</strong> since version %2$s with no alternative available.', $function, $version ) ); |
| 471 |
} |
| 472 |
} |
| 473 |
} |
| 474 |
} |
| 475 |
|
| 476 |
/** |
| 477 |
* Magic getter for our object. |
| 478 |
* |
| 479 |
* @param string $field Requested property. |
| 480 |
* @throws Exception Throws an exception if the field is invalid. |
| 481 |
* @return mixed |
| 482 |
*/ |
| 483 |
public function __get( $field ) { |
| 484 |
switch ( $field ) { |
| 485 |
case 'args': |
| 486 |
case 'meta_box': |
| 487 |
if ( $field === $this->properties_name ) { |
| 488 |
return $this->{$this->properties_name}; |
| 489 |
} |
| 490 |
// no break |
| 491 |
case 'properties': |
| 492 |
return $this->{$this->properties_name}; |
| 493 |
case 'cmb_id': |
| 494 |
case 'object_id': |
| 495 |
case 'object_type': |
| 496 |
return $this->{$field}; |
| 497 |
default: |
| 498 |
// translators: 1: class name, 2: property name. |
| 499 |
throw new Exception( sprintf( esc_html__( 'Invalid %1$s property: %2$s', 'cmb2' ), __CLASS__, $field ) ); |
| 500 |
} |
| 501 |
} |
| 502 |
|
| 503 |
/** |
| 504 |
* Allows overloading the object with methods... Whooaaa oooh it's magic, y'knoooow. |
| 505 |
* |
| 506 |
* @since 1.0.0 |
| 507 |
* @throws Exception Invalid method exception. |
| 508 |
* |
| 509 |
* @param string $method Non-existent method. |
| 510 |
* @param array $args All arguments passed to the method. |
| 511 |
* @return mixed |
| 512 |
*/ |
| 513 |
public function __call( $method, $args ) { |
| 514 |
$object_class = strtolower( get_class( $this ) ); |
| 515 |
|
| 516 |
if ( ! has_filter( "{$object_class}_inherit_{$method}" ) ) { |
| 517 |
// translators: 1: class name, 2: method name. |
| 518 |
throw new Exception( sprintf( esc_html__( 'Invalid %1$s method: %2$s', 'cmb2' ), get_class( $this ), $method ) ); |
| 519 |
} |
| 520 |
|
| 521 |
array_unshift( $args, $this ); |
| 522 |
|
| 523 |
/** |
| 524 |
* Allows overloading the object (CMB2 or CMB2_Field) with additional capabilities |
| 525 |
* by registering hook callbacks. |
| 526 |
* |
| 527 |
* The first dynamic portion of the hook name, $object_class, refers to the object class, |
| 528 |
* either cmb2 or cmb2_field. |
| 529 |
* |
| 530 |
* The second dynamic portion of the hook name, $method, is the non-existent method being |
| 531 |
* called on the object. To avoid possible future methods encroaching on your hooks, |
| 532 |
* use a unique method (aka, $cmb->prefix_my_method()). |
| 533 |
* |
| 534 |
* When registering your callback, you will need to ensure that you register the correct |
| 535 |
* number of `$accepted_args`, accounting for this object instance being the first argument. |
| 536 |
* |
| 537 |
* @param array $args The arguments to be passed to the hook. |
| 538 |
* The first argument will always be this object instance. |
| 539 |
*/ |
| 540 |
return apply_filters_ref_array( "{$object_class}_inherit_{$method}", $args ); |
| 541 |
} |
| 542 |
} |
| 543 |
|
