9cb8bb611b
* Remove redundant file-level description and ensure the class desc and ingroup tag are on the class block instead. Ref https://gerrit.wikimedia.org/r/q/owner:Krinkle+message:ingroup * Widen `@covers` annotations in unit tests. Ref https://gerrit.wikimedia.org/r/q/owner:krinkle+is:merged+message:covers * Create "Debug" documentation group, covering the debug/ directory. This will show up on doc.wikimedia.org under "Modules", where each class is listed, and the class page will also link back to the group as part of its breadcrumb navigation. Test with `php maintenance/mwdocgen.php --file docs/,includes/debug/` and then view /w/docs/html/ * Improve docs of various classes and explain relationships better. In particular, reformat to ensure each class has a oneline description that captures its essential function. Change-Id: I5d1143a9244b7fd888e1dc31f0fd7965272aa900
97 lines
2.5 KiB
PHP
97 lines
2.5 KiB
PHP
<?php
|
|
|
|
namespace MediaWiki\Debug;
|
|
|
|
use ArrayAccess;
|
|
|
|
/**
|
|
* ArrayAccess with support for deprecating access to certain offsets.
|
|
*
|
|
* It behaves mostly as a normal array, however in order to avoid instantiating
|
|
* deprecated properties by default, a callable initializer can be set to the property.
|
|
* It will be executed upon 'get'.
|
|
* @note Setting properties does not emit deprecation warnings.
|
|
*
|
|
* @newable
|
|
* @since 1.35
|
|
*/
|
|
class DeprecatablePropertyArray implements ArrayAccess {
|
|
|
|
/** @var array */
|
|
private $container;
|
|
|
|
/** @var array Map of deprecated property names to deprecation versions */
|
|
private $deprecatedProperties;
|
|
|
|
/** @var string */
|
|
private $name;
|
|
|
|
/** @var string|null */
|
|
private $component;
|
|
|
|
/**
|
|
* @param array $initializer Initial value of the array.
|
|
* @param array $deprecatedProperties Map of deprecated property names to versions.
|
|
* @param string $name Descriptive identifier for the array
|
|
* @param string|null $component Component to which array belongs.
|
|
* If not provided, assumed to be MW Core
|
|
*/
|
|
public function __construct(
|
|
array $initializer,
|
|
array $deprecatedProperties,
|
|
string $name,
|
|
string $component = null
|
|
) {
|
|
$this->container = $initializer;
|
|
$this->deprecatedProperties = $deprecatedProperties;
|
|
$this->name = $name;
|
|
$this->component = $component;
|
|
}
|
|
|
|
public function offsetExists( $offset ): bool {
|
|
$this->checkDeprecatedAccess( $offset, 'exists' );
|
|
return isset( $this->container[$offset] );
|
|
}
|
|
|
|
#[\ReturnTypeWillChange]
|
|
public function offsetGet( $offset ) {
|
|
if ( $this->checkDeprecatedAccess( $offset, 'get' ) ) {
|
|
if ( is_callable( $this->container[$offset] ) ) {
|
|
$this->container[$offset] = call_user_func( $this->container[$offset] );
|
|
}
|
|
}
|
|
return $this->container[$offset] ?? null;
|
|
}
|
|
|
|
public function offsetSet( $offset, $value ): void {
|
|
if ( $offset === null ) {
|
|
$this->container[] = $value;
|
|
} else {
|
|
$this->container[$offset] = $value;
|
|
}
|
|
}
|
|
|
|
public function offsetUnset( $offset ): void {
|
|
$this->checkDeprecatedAccess( $offset, 'unset' );
|
|
unset( $this->container[$offset] );
|
|
}
|
|
|
|
/**
|
|
* @param string|int $offset
|
|
* @param string $fname
|
|
* @return bool
|
|
*/
|
|
private function checkDeprecatedAccess( $offset, string $fname ): bool {
|
|
if ( array_key_exists( $offset, $this->deprecatedProperties ) ) {
|
|
$deprecatedVersion = $this->deprecatedProperties[$offset];
|
|
wfDeprecated(
|
|
"{$this->name} {$fname} '{$offset}'",
|
|
$deprecatedVersion,
|
|
$this->component ?? false,
|
|
3
|
|
);
|
|
return true;
|
|
}
|
|
return false;
|
|
}
|
|
}
|