Settings loaded from a local file path. More...

Inheritance diagram for MediaWiki\Settings\Source\FileSource:

[legend]

Collaboration diagram for MediaWiki\Settings\Source\FileSource:

[legend]

Public Member Functions
	__construct (string $path, SettingsFormat $format=null)
	Constructs a new FileSource for the given path and possibly a custom format to decode the contents. More...

	__toString ()
	Returns this file source as a string. More...

	allowsStaleLoad ()
	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. More...

	getExpiryTtl ()
	The cache expiry TTL (in seconds) for this file source. More...

	getExpiryWeight ()
	Coefficient used in determining early expiration of cached settings to avoid stampedes. More...

	getHashKey ()
	Returns a hash key computed from the file's inode, size, and last modified timestamp. More...

	load ()
	Loads contents from the file and decodes them using the first format to claim support for the file's extension. More...

	locateInclude (string $location)
	This method defines how a relative reference to the location of another settings source is interpreted. More...

Private Member Functions
	readAndDecode (SettingsFormat $format)
	Reads and decodes the file contents using the given format. More...

Private Attributes
SettingsFormat	$format
	Format to use for reading the file, if given. More...

string	$path
	Path to local file. More...

const	BUILT_IN_FORMATS

const	EXPIRY_TTL = 60 * 60 * 24
	Cache expiry TTL for file sources (24 hours). More...

const	EXPIRY_WEIGHT = 1.0
	Early expiry weight. More...

Detailed Description

Settings loaded from a local file path.

Since: 1.38

Definition at line 18 of file FileSource.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Settings\Source\FileSource::__construct	(	string	$path,
		SettingsFormat	$format = `null`
	)

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

<?php $source = new FileSource( 'my/settings.json' ); $source->load();

While a specialized caller may want to pass a specialized format

<?php $source = new FileSource( 'my/settings.toml', new TomlFormat() ); $source->load();

Parameters

string	$path
SettingsFormat \| null	$format

Definition at line 87 of file FileSource.php.

References MediaWiki\Settings\Source\FileSource\$format, and MediaWiki\Settings\Source\FileSource\$path.

Member Function Documentation

◆ __toString()

MediaWiki\Settings\Source\FileSource::__toString ( )

Returns this file source as a string.

Returns: string

Definition at line 176 of file FileSource.php.

◆ allowsStaleLoad()

MediaWiki\Settings\Source\FileSource::allowsStaleLoad ( )

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.

Returns: bool

Implements MediaWiki\Settings\Cache\CacheableSource.

Definition at line 99 of file FileSource.php.

◆ getExpiryTtl()

MediaWiki\Settings\Source\FileSource::getExpiryTtl ( )

The cache expiry TTL (in seconds) for this file source.

Returns: int

Implements MediaWiki\Settings\Cache\CacheableSource.

Definition at line 138 of file FileSource.php.

◆ getExpiryWeight()

MediaWiki\Settings\Source\FileSource::getExpiryWeight ( )

Coefficient used in determining early expiration of cached settings to avoid stampedes.

Returns: float

Implements MediaWiki\Settings\Cache\CacheableSource.

Definition at line 148 of file FileSource.php.

◆ getHashKey()

MediaWiki\Settings\Source\FileSource::getHashKey ( )

Returns a hash key computed from the file's inode, size, and last modified timestamp.

Returns: string

Implements MediaWiki\Settings\Cache\CacheableSource.

Definition at line 158 of file FileSource.php.

◆ load()

MediaWiki\Settings\Source\FileSource::load ( )

Loads contents from the file and decodes them using the first format to claim support for the file's extension.

Exceptions

SettingsBuilderException

Returns: array

Implements MediaWiki\Settings\Source\SettingsSource.

Definition at line 110 of file FileSource.php.

◆ locateInclude()

MediaWiki\Settings\Source\FileSource::locateInclude ( string $location )

This method defines how a relative reference to the location of another settings source is interpreted.

It tries to make $location absolute by interpreting it as relative to the location of the SettingsSource it originates from.

Implementation are "best effort". If a location cannot be made absolute, it may be returned as-is. Implementations are also free to throw a SettingsBuilderException to indicate that the given include location is not supported in this context.

Parameters

string $location

Returns: string

Exceptions

SettingsBuilderException if the given location cannot be used as an include by the current source.

Implements MediaWiki\Settings\Source\SettingsIncludeLocator.

Definition at line 225 of file FileSource.php.

◆ readAndDecode()

MediaWiki\Settings\Source\FileSource::readAndDecode ( SettingsFormat $format )

private

Reads and decodes the file contents using the given format.

Parameters

SettingsFormat $format

Returns: array

Exceptions

SettingsBuilderException

Definition at line 188 of file FileSource.php.

Member Data Documentation

◆ $format

SettingsFormat MediaWiki\Settings\Source\FileSource::$format

private

Format to use for reading the file, if given.

Definition at line 50 of file FileSource.php.

Referenced by MediaWiki\Settings\Source\FileSource\__construct().

◆ $path

string MediaWiki\Settings\Source\FileSource::$path

private

Path to local file.

Definition at line 56 of file FileSource.php.

Referenced by MediaWiki\Settings\Source\FileSource\__construct().

◆ BUILT_IN_FORMATS

const MediaWiki\Settings\Source\FileSource::BUILT_IN_FORMATS

private

Initial value:

= [
        JsonFormat::class,
        YamlFormat::class,
    ]

Definition at line 19 of file FileSource.php.

◆ EXPIRY_TTL

const MediaWiki\Settings\Source\FileSource::EXPIRY_TTL = 60 * 60 * 24

private

Cache expiry TTL for file sources (24 hours).

See also: getExpiryTtl(); CacheableSource::getExpiryTtl()

Definition at line 30 of file FileSource.php.

◆ EXPIRY_WEIGHT

const MediaWiki\Settings\Source\FileSource::EXPIRY_WEIGHT = 1.0

private

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 also: getExpiryWeight(); CacheableSource::getExpiryWeight()

Definition at line 43 of file FileSource.php.

The documentation for this class was generated from the following file:

includes/Settings/Source/FileSource.php

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ __toString()

◆ allowsStaleLoad()

◆ getExpiryTtl()

◆ getExpiryWeight()

◆ getHashKey()

◆ load()

◆ locateInclude()

◆ readAndDecode()

Member Data Documentation

◆ $format

◆ $path

◆ BUILT_IN_FORMATS

◆ EXPIRY_TTL

◆ EXPIRY_WEIGHT