Page MenuHomeWickedGov Phorge
Files F1427178

FileSource.php
No OneTemporary
Actions

Size
5 KB
Referenced Files
None
Subscribers
None

FileSource.php
View Options

<?php
namespace MediaWiki\Settings\Source;
use MediaWiki\Settings\Cache\CacheableSource;
use MediaWiki\Settings\SettingsBuilderException;
use MediaWiki\Settings\Source\Format\JsonFormat;
use MediaWiki\Settings\Source\Format\SettingsFormat;
use MediaWiki\Settings\Source\Format\YamlFormat;
use Stringable;
use UnexpectedValueException;
use Wikimedia\AtEase\AtEase;
/**
* Settings loaded from a local file path.
*
* @since 1.38
*/
class FileSource implements Stringable, CacheableSource, SettingsIncludeLocator {
private const BUILT_IN_FORMATS = [
JsonFormat::class,
YamlFormat::class,
];
/**
* Cache expiry TTL for file sources (24 hours).
*
* @see getExpiryTtl()
* @see CacheableSource::getExpiryTtl()
*/
private const EXPIRY_TTL = 60 * 60 * 24;
/**
* Early expiry weight. This value influences the margin by which
* processes are selected to expire cached local-file settings early to
* avoid cache stampedes. Changes to this value are not likely to be
* necessary as time spent loading from local files should not have much
* variation and should already be well served by the default early expiry
* calculation.
*
* @see getExpiryWeight()
* @see CacheableSource::getExpiryWeight()
*/
private const EXPIRY_WEIGHT = 1.0;
/**
* Format to use for reading the file, if given.
*
* @var ?SettingsFormat
*/
private $format;
/**
* Path to local file.
* @var string
*/
private $path;
/**
* Constructs a new FileSource for the given path and possibly a custom format
* to decode the contents. If no format is given, the built-in formats will be
* tried and the first one that supports the file extension will be used.
*
* Built-in formats:
* - JsonFormat
* - YamlFormat
*
* <code>
* <?php
* $source = new FileSource( 'my/settings.json' );
* $source->load();
* </code>
*
* While a specialized caller may want to pass a specialized format
*
* <code>
* <?php
* $source = new FileSource(
* 'my/settings.toml',
* new TomlFormat()
* );
* $source->load();
* </code>
*
* @param string $path
* @param SettingsFormat|null $format
*/
public function __construct( string $path, ?SettingsFormat $format = null ) {
$this->path = $path;
$this->format = $format;
}
/**
* Disallow stale results from file sources in the case of load failure as
* failing to read from disk would be quite catastrophic and worthy of
* propagation.
*
* @return bool
*/
public function allowsStaleLoad(): bool {
return false;
}
/**
* Loads contents from the file and decodes them using the first format
* to claim support for the file's extension.
*
* @throws SettingsBuilderException
* @return array
*/
public function load(): array {
$ext = pathinfo( $this->path, PATHINFO_EXTENSION );
// If there's only one format, don't bother to match the file
// extension.
if ( $this->format ) {
return $this->readAndDecode( $this->format );
}
foreach ( self::BUILT_IN_FORMATS as $format ) {
if ( call_user_func( [ $format, 'supportsFileExtension' ], $ext ) ) {
return $this->readAndDecode( new $format() );
}
}
throw new SettingsBuilderException(
"None of the built-in formats are suitable for '{path}'",
[
'path' => $this->path,
]
);
}
/**
* The cache expiry TTL (in seconds) for this file source.
*
* @return int
*/
public function getExpiryTtl(): int {
return self::EXPIRY_TTL;
}
/**
* Coefficient used in determining early expiration of cached settings to
* avoid stampedes.
*
* @return float
*/
public function getExpiryWeight(): float {
return self::EXPIRY_WEIGHT;
}
/**
* Returns a hash key computed from the file's inode, size, and last
* modified timestamp.
*
* @return string
*/
public function getHashKey(): string {
$stat = stat( $this->path );
if ( $stat === false ) {
throw new SettingsBuilderException(
"Failed to stat file '{path}'",
[ 'path' => $this->path ]
);
}
return sprintf( '%x-%x-%x', $stat['ino'], $stat['size'], $stat['mtime'] );
}
/**
* Returns this file source as a string.
*
* @return string
*/
public function __toString(): string {
return $this->path;
}
/**
* Reads and decodes the file contents using the given format.
*
* @param SettingsFormat $format
*
* @return array
* @throws SettingsBuilderException
*/
private function readAndDecode( SettingsFormat $format ): array {
$contents = AtEase::quietCall( 'file_get_contents', $this->path );
if ( $contents === false ) {
if ( !is_readable( $this->path ) ) {
throw new SettingsBuilderException(
"File '{path}' is not readable",
[ 'path' => $this->path ]
);
}
if ( is_dir( $this->path ) ) {
throw new SettingsBuilderException(
"'{path}' is a directory, not a file",
[ 'path' => $this->path ]
);
}
throw new SettingsBuilderException(
"Failed to read file '{path}'",
[ 'path' => $this->path ]
);
}
try {
return $format->decode( $contents );
} catch ( UnexpectedValueException $e ) {
throw new SettingsBuilderException(
"Failed to decode file '{path}': {message}",
[
'path' => $this->path,
'message' => $e->getMessage()
]
);
}
}
public function locateInclude( string $location ): string {
return SettingsFileUtils::resolveRelativeLocation( $location, dirname( $this->path ) );
}
}

File Metadata

Mime Type
text/x-php
Expires
Sat, May 16, 14:18 (1 d, 9 h)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
fe/fb/4bdc6dbe377453ced432465fdef2
Default Alt Text
FileSource.php (5 KB)

Event Timeline