WARNING: MediaWiki core hardcodes this class name to check if the Cite extension is installed. More...

Collaboration diagram for Cite:

[legend]

Public Member Functions
	checkRefsNoReferences ( $afterParse, $parser, &$text)
	Called at the end of page processing to append a default references section, if refs were used without a main references tag.

	clearState (Parser $parser)
	Gets run when Parser::clearState() gets run, since we don't want the counts to transcend pages and other instances.

	cloneState (Parser $parser)
	Gets run when the parser is cloned.

	ref ( $str, array $argv, Parser $parser, PPFrame $frame)
	Callback function for <ref>

	references ( $str, array $argv, Parser $parser, PPFrame $frame)
	Callback function for <references>

Static Public Member Functions
static	getReferencesKey ( $key)
	Return an id for use in wikitext output based on a key and optionally the number of it, used in <ref>, not <references> (since otherwise it would link to itself)

static	getStoredReferences (Title $title)
	Fetch references stored for the given title in page_props For performance, results are cached.

static	setHooks (Parser $parser)
	Initialize the parser hooks.

Public Attributes
boolean	$mInCite = false
	True when a <ref> tag is being processed.

boolean	$mInReferences = false
	True when a <references> tag is being processed.

const	CACHE_DURATION_ONFETCH = 18000
	Cache duration set when fetching references from db.

const	CACHE_DURATION_ONPARSE = 3600
	Cache duration set when parsing a page with references.

const	DATA_VERSION_NUMBER = 1
	Version number in case we change the data structure in the future.

const	DEFAULT_GROUP = ''

const	EXT_DATA_KEY = 'Cite:References'
	Key used for storage in parser output's ExtensionData and ObjectCache.

const	MAX_STORAGE_LENGTH = 65535
	Maximum storage capacity for pp_value field of page_props table.

Private Member Functions
	error ( $key, $param=null)
	Return an error message based on an error ID and parses it.

	genBacklinkLabels ()
	Generate the labels to pass to the 'cite_references_link_many_format' message, the format is an arbitrary number of tokens separated by [\t\n ].

	genLinkLabels ( $group, $message)
	Generate the labels to pass to the 'cite_reference_link' message instead of numbers, the format is an arbitrary number of tokens separated by [\t\n ].

	getLinkLabel ( $offset, $group, $label)
	Generate a custom format link for a group given an offset, e.g.

	guardedRef ( $str, array $argv, Parser $parser, $default_group=self::DEFAULT_GROUP)

	guardedReferences ( $str, array $argv, Parser $parser, $group=self::DEFAULT_GROUP)
	Must only be called from references().

	linkRef ( $group, $key, $count=null, $label=null, $subkey='')
	Generate a link (<sup ...) for the <ref> element from a key and return XHTML ready for output.

	listToText ( $arr)
	This does approximately the same thing as Language::listToText() but due to this being used for a slightly different purpose (people might not want , as the first separator and not 'and' as the second, and this has to use messages from the content language) I'm rolling my own.

	normalizeKey ( $key)
	Normalizes and sanitizes a reference key.

	plainError ( $key, $param=null)
	Return an error message based on an error ID as unescaped plaintext.

	refArg (array $argv)
	Parse the arguments to the <ref> tag.

	referencesFormat ( $group, $responsive)
	Make output to be returned from the references() function.

	referencesFormatEntry ( $key, $val)
	Format a single entry for the referencesFormat() function.

	referencesFormatEntryAlternateBacklinkLabel ( $offset)
	Generate a custom format backlink given an offset, e.g.

	referencesFormatEntryNumericBacklinkLabel ( $base, $offset, $max)
	Generate a numeric backlink given a base number and an offset, e.g.

	referenceText ( $key, $text)
	Returns formatted reference text.

	refKey ( $key, $num=null)
	Return an id for use in wikitext output based on a key and optionally the number of it, used in <references>, not <ref> (since otherwise it would link to itself)

	rollbackRef ( $type, $key, $group, $index)
	Partially undoes the effect of calls to stack()

	saveReferencesData ( $group=self::DEFAULT_GROUP)
	Saves references in parser extension data This is called by each <references> tag, and by checkRefsNoReferences Assumes $this->mRefs[$group] is set.

	stack ( $str, $key, $group, $follow, array $call, $dir, Parser $parser)
	Populate $this->mRefs based on input and arguments to <ref>

	warning ( $key, $param=null, $parse='parse')
	Return a warning message based on a warning ID.

Static Private Member Functions
static	recursiveFetchRefsFromDB (Title $title, IDatabase $dbr, $string='', $i=1)
	Reconstructs compressed json by successively retrieving the properties references-1, -2, etc It attempts the next step when a decoding error occurs.

Private Attributes
string[]	$mBacklinkLabels
	The backlinks, in order, to pass as $3 to 'cite_references_link_many_format', defined in 'cite_references_link_many_format_backlink_labels.

bool	$mBumpRefData = false

int	$mCallCnt = 0
	Counter to track the total number of (useful) calls to either the ref or references tag hook.

int[]	$mGroupCnt = []

boolean	$mHaveAfterParse = false
	True when the ParserAfterParse hook has been called.

array	$mLinkLabels = []
	The links to use per group, in order.

int	$mOutCnt = 0
	Count for user displayed output (ref[1], ref[2], ...)

Parser	$mParser

array	$mRefCallStack = []
	<ref> call stack Used to cleanup out of sequence ref calls created by #tag See description of function rollbackRef.

string[]	$mReferencesErrors = []
	Error stack used when defining refs in <references>

string	$mReferencesGroup = ''
	Group used when in <references> block.

array[]	$mRefs = []
	Datastructure representing <ref> input, in the format of: `[ 'user supplied' => [ 'text' => 'user supplied reference & key', 'count' => 1, // occurs twice 'number' => 1, // The first reference, we want // all occourances of it to // use the same number ], 0 => 'Anonymous reference', 1 => 'Another anonymous reference', 'some key' => [ 'text' => 'this one occurs once' 'count' => 0, 'number' => 4 ], 3 => 'more stuff' ];`

Static Private Attributes
static Boolean	$hooksInstalled = false
	Did we install us into $wgHooks yet?

Detailed Description

WARNING: MediaWiki core hardcodes this class name to check if the Cite extension is installed.

See T89151.

Definition at line 33 of file Cite.php.

Member Function Documentation

◆ checkRefsNoReferences()

Cite::checkRefsNoReferences	(		$afterParse,
			$parser,
		&	$text )

Called at the end of page processing to append a default references section, if refs were used without a main references tag.

If there are references in a custom group, and there is no references tag for it, show an error message for that group. If we are processing a section preview, this adds the missing references tags and does not add the errors.

Parameters

bool	$afterParse	True if called from the ParserAfterParse hook
Parser	$parser
string	&$text

Definition at line 1198 of file Cite.php.

References $parser, $s, error, referencesFormat(), saveReferencesData(), and wfMessage().

◆ clearState()

Cite::clearState ( Parser $parser )

Gets run when Parser::clearState() gets run, since we don't want the counts to transcend pages and other instances.

Parameters

Parser $parser

Definition at line 1145 of file Cite.php.

References $parser.

◆ cloneState()

Cite::cloneState ( Parser $parser )

Gets run when the parser is cloned.

Parameters

Parser $parser

Definition at line 1170 of file Cite.php.

References $parser.

◆ error()

Cite::error	(		$key,
			$param = null )

private

Return an error message based on an error ID and parses it.

Parameters

string	$key	Message name for the error
string[] \| string \| null	$param	Parameter to pass to the message

Returns: string HTML ready for output

Definition at line 1318 of file Cite.php.

References plainError().

◆ genBacklinkLabels()

Cite::genBacklinkLabels ( )

private

Generate the labels to pass to the 'cite_references_link_many_format' message, the format is an arbitrary number of tokens separated by [\t\n ].

Definition at line 1116 of file Cite.php.

References wfMessage().

Referenced by referencesFormatEntryAlternateBacklinkLabel().

◆ genLinkLabels()

Cite::genLinkLabels	(		$group,
			$message )

private

Generate the labels to pass to the 'cite_reference_link' message instead of numbers, the format is an arbitrary number of tokens separated by [\t\n ].

Parameters

string	$group
string	$message

Definition at line 1130 of file Cite.php.

References wfMessage().

Referenced by getLinkLabel().

◆ getLinkLabel()

Cite::getLinkLabel	(	$offset,
		$group,
		$label )

private

Generate a custom format link for a group given an offset, e.g.

the second <ref group="foo"> is b if $this->mLinkLabels["foo"] = [ 'a', 'b', 'c', ...]. Return an error if the offset > the # of array items

Parameters

int	$offset
string	$group	The group name
string	$label	The text to use if there's no message for them.

Returns: string

Definition at line 983 of file Cite.php.

References genLinkLabels(), and plainError().

Referenced by linkRef().

◆ getReferencesKey()

static Cite::getReferencesKey ( $key )

static

Return an id for use in wikitext output based on a key and optionally the number of it, used in <ref>, not <references> (since otherwise it would link to itself)

Parameters

string $key

Returns: string A key for use in wikitext

Definition at line 1029 of file Cite.php.

References wfMessage().

Referenced by ApiQueryReferences\execute().

◆ getStoredReferences()

static Cite::getStoredReferences ( Title $title )

static

Fetch references stored for the given title in page_props For performance, results are cached.

Parameters

Title $title

Returns: array|false

Definition at line 1412 of file Cite.php.

References $cache, $dbr, array(), DB_REPLICA, recursiveFetchRefsFromDB(), and wfGetDB().

Referenced by ApiQueryReferences\execute().

◆ guardedRef()

Cite::guardedRef	(		$str,
		array	$argv,
		Parser	$parser,
			$default_group = self::DEFAULT_GROUP )

private

Parameters

string \| null	$str	Raw content of the <ref> tag.
string[]	$argv	Arguments
Parser	$parser
string	$default_group

Exceptions

Exception

Returns: string

Definition at line 242 of file Cite.php.

References $mReferencesGroup, $parser, error, list, plainError(), refArg(), serialize(), and stack().

Referenced by guardedReferences(), and ref().

◆ guardedReferences()

Cite::guardedReferences	(		$str,
		array	$argv,
		Parser	$parser,
			$group = self::DEFAULT_GROUP )

private

Must only be called from references().

Use that to prevent recursion.

Parameters

string \| null	$str	Raw content of the <references> tag.
string[]	$argv
Parser	$parser
string	$group

Returns: string

Definition at line 678 of file Cite.php.

References $parser, $s, $type, error, guardedRef(), list, referencesFormat(), and rollbackRef().

Referenced by references().

◆ linkRef()

Cite::linkRef	(	$group,
		$key,
		$count = null,
		$label = null,
		$subkey = '' )

private

Generate a link (<sup ...) for the <ref> element from a key and return XHTML ready for output.

@suppress SecurityCheck-DoubleEscaped

Parameters

string	$group
string	$key	The key for the link
int	$count	The index of the key, used for distinguishing multiple occurrences of the same key
int	$label	The label to use for the link, I want to use the same label for all occourances of the same named reference.
string	$subkey

Returns: string

Definition at line 1052 of file Cite.php.

References $wgContLang, getLinkLabel(), normalizeKey(), refKey(), and wfMessage().

Referenced by stack().

◆ listToText()

Cite::listToText ( $arr )

private

This does approximately the same thing as Language::listToText() but due to this being used for a slightly different purpose (people might not want , as the first separator and not 'and' as the second, and this has to use messages from the content language) I'm rolling my own.

Parameters

array $arr The array to format

Returns: string

Definition at line 1096 of file Cite.php.

References $t, and wfMessage().

Referenced by referencesFormatEntry().

◆ normalizeKey()

Cite::normalizeKey ( $key )

private

Normalizes and sanitizes a reference key.

Parameters

string $key

Returns: string

Definition at line 1079 of file Cite.php.

Referenced by linkRef(), and referencesFormatEntry().

◆ plainError()

Cite::plainError	(		$key,
			$param = null )

private

Return an error message based on an error ID as unescaped plaintext.

Parameters

string	$key	Message name for the error
string[] \| string \| null	$param	Parameter to pass to the message

Returns: string wikitext ready for output; -taint tainted

Definition at line 1331 of file Cite.php.

References $lang, $ret, plain, and wfMessage().

Referenced by error(), getLinkLabel(), guardedRef(), referencesFormatEntryAlternateBacklinkLabel(), referenceText(), and stack().

◆ recursiveFetchRefsFromDB()

static Cite::recursiveFetchRefsFromDB	(	Title	$title,
		IDatabase	$dbr,
			$string = '',
			$i = 1 )

staticprivate

Reconstructs compressed json by successively retrieving the properties references-1, -2, etc It attempts the next step when a decoding error occurs.

Returns json_decoded uncompressed string, with validation of json

Parameters

Title	$title
IDatabase	$dbr
string	$string
int	$i

Returns: array|false

Definition at line 1445 of file Cite.php.

References $dbr, $result, recursiveFetchRefsFromDB(), and wfDebug().

Referenced by getStoredReferences(), and recursiveFetchRefsFromDB().

◆ ref()

Cite::ref	(		$str,
		array	$argv,
		Parser	$parser,
		PPFrame	$frame )

Callback function for <ref>

Parameters

string \| null	$str	Raw content of the <ref> tag.
string[]	$argv	Arguments
Parser	$parser
PPFrame	$frame

Returns: string

Definition at line 208 of file Cite.php.

References $parser, $ret, guardedRef(), and PPFrame\setVolatile().

◆ refArg()

Cite::refArg ( array $argv )

private

Parse the arguments to the <ref> tag.

"name" : Key of the reference. "group" : Group to which it belongs. Needs to be passed to <references > too. "follow" : If the current reference is the continuation of another, key of that reference. "dir" : set direction of text (ltr/rtl)

Parameters

string[] $argv The argument vector

Returns: mixed false on invalid input, a string on valid input and null on no input; -taint tainted

Definition at line 404 of file Cite.php.

References false.

Referenced by guardedRef().

◆ references()

Cite::references	(		$str,
		array	$argv,
		Parser	$parser,
		PPFrame	$frame )

Callback function for <references>

Parameters

string \| null	$str	Raw content of the <references> tag.
string[]	$argv	Arguments
Parser	$parser
PPFrame	$frame

Returns: string

Definition at line 654 of file Cite.php.

References $parser, $ret, guardedReferences(), and PPFrame\setVolatile().

◆ referencesFormat()

Cite::referencesFormat	(		$group,
			$responsive )

private

Make output to be returned from the references() function.

If called outside of references(), caller is responsible for ensuring mInReferences is enabled before the call and disabled after call.

Parameters

string	$group
bool	$responsive

Returns: string HTML ready for output

Definition at line 772 of file Cite.php.

References $ret, referencesFormatEntry(), and saveReferencesData().

Referenced by checkRefsNoReferences(), and guardedReferences().

◆ referencesFormatEntry()

Cite::referencesFormatEntry	(		$key,
			$val )

private

Format a single entry for the referencesFormat() function.

Parameters

string	$key	The key of the reference
mixed	$val	The value of the reference, string for anonymous references, array for user-suppplied

Returns: string Wikitext

Definition at line 821 of file Cite.php.

References listToText(), normalizeKey(), referencesFormatEntryAlternateBacklinkLabel(), referencesFormatEntryNumericBacklinkLabel(), referenceText(), refKey(), and wfMessage().

Referenced by referencesFormat().

◆ referencesFormatEntryAlternateBacklinkLabel()

Cite::referencesFormatEntryAlternateBacklinkLabel ( $offset )

private

Generate a custom format backlink given an offset, e.g.

$offset = 2; = c if $this->mBacklinkLabels = [ 'a', 'b', 'c', ...]. Return an error if the offset > the # of array items

Parameters

int $offset

Returns: string

Definition at line 959 of file Cite.php.

References genBacklinkLabels(), and plainError().

Referenced by referencesFormatEntry().

◆ referencesFormatEntryNumericBacklinkLabel()

Cite::referencesFormatEntryNumericBacklinkLabel	(	$base,
		$offset,
		$max )

private

Generate a numeric backlink given a base number and an offset, e.g.

$base = 1, $offset = 2; = 1.2 Since bug #5525, it correctly does 1.9 -> 1.10 as well as 1.099 -> 1.100

Parameters

int	$base
int	$offset
int	$max	Maximum value expected.

Returns: string

Definition at line 940 of file Cite.php.

References $base, $ret, and $wgContLang.

Referenced by referencesFormatEntry().

◆ referenceText()

Cite::referenceText	(		$key,
			$text )

private

Returns formatted reference text.

Parameters

String	$key
String	$text

Returns: String

Definition at line 920 of file Cite.php.

References plainError(), and warning().

Referenced by referencesFormatEntry().

◆ refKey()

Cite::refKey	(		$key,
			$num = null )

private

Return an id for use in wikitext output based on a key and optionally the number of it, used in <references>, not <ref> (since otherwise it would link to itself)

Parameters

string	$key
int	$num	The number of the key

Returns: string A key for use in wikitext

Definition at line 1010 of file Cite.php.

References wfMessage().

Referenced by linkRef(), and referencesFormatEntry().

◆ rollbackRef()

Cite::rollbackRef	(	$type,
		$key,
		$group,
		$index )

private

Partially undoes the effect of calls to stack()

Called by guardedReferences()

The option to define <ref> within <references> makes the behavior of <ref> context dependent. This is normally fine but certain operations (especially #tag) lead to out-of-order parser evaluation with the <ref> tags being processed before their containing <reference> element is read. This leads to stack corruption that this function works to fix.

This function is not a total rollback since some internal counters remain incremented. Doing so prevents accidentally corrupting certain links.

Parameters

string	$type
string \| null	$key
string	$group
int	$index

Definition at line 599 of file Cite.php.

References $type.

Referenced by guardedReferences().

◆ saveReferencesData()

Cite::saveReferencesData ( $group = self::DEFAULT_GROUP )

private

Saves references in parser extension data This is called by each <references> tag, and by checkRefsNoReferences Assumes $this->mRefs[$group] is set.

Parameters

string $group

Definition at line 1263 of file Cite.php.

References DATA_VERSION_NUMBER.

Referenced by checkRefsNoReferences(), and referencesFormat().

◆ setHooks()

static Cite::setHooks ( Parser $parser )

static

Initialize the parser hooks.

Parameters

Parser $parser

Definition at line 1295 of file Cite.php.

References $parser, $wgHooks, false, and true.

◆ stack()

Cite::stack	(		$str,
			$key,
			$group,
			$follow,
		array	$call,
			$dir,
		Parser	$parser )

private

Populate $this->mRefs based on input and arguments to <ref>

Parameters

string	$str	Input from the <ref> tag
string \| null	$key	Argument to the <ref> tag as returned by $this->refArg()
string	$group
string \| null	$follow
string[]	$call
string	$dir	ref direction
Parser	$parser

Exceptions

Exception

Returns: string

Definition at line 474 of file Cite.php.

References $mOutCnt, $parser, linkRef(), plainError(), and serialize().

Referenced by guardedRef().

◆ warning()

Cite::warning	(	$key,
		$param = null,
		$parse = 'parse' )

private

Return a warning message based on a warning ID.

Parameters

string	$key	Message name for the warning. Name should start with cite_warning_
string \| null	$param	Parameter to pass to the message
string	$parse	Whether to parse the message ('parse') or not ('noparse')

Returns: string XHTML or wikitext ready for output

Definition at line 1370 of file Cite.php.

References $lang, $ret, plain, and wfMessage().

Referenced by referenceText().

Member Data Documentation

◆ $hooksInstalled

Boolean Cite::$hooksInstalled = false

staticprivate

Did we install us into $wgHooks yet?

Definition at line 196 of file Cite.php.

◆ $mBacklinkLabels

string [] Cite::$mBacklinkLabels

private

The backlinks, in order, to pass as $3 to 'cite_references_link_many_format', defined in 'cite_references_link_many_format_backlink_labels.

Definition at line 126 of file Cite.php.

◆ $mBumpRefData

bool Cite::$mBumpRefData = false

private

Definition at line 190 of file Cite.php.

◆ $mCallCnt

int Cite::$mCallCnt = 0

private

Counter to track the total number of (useful) calls to either the ref or references tag hook.

Definition at line 117 of file Cite.php.

◆ $mGroupCnt

int [] Cite::$mGroupCnt = []

private

Definition at line 109 of file Cite.php.

◆ $mHaveAfterParse

boolean Cite::$mHaveAfterParse = false

private

True when the ParserAfterParse hook has been called.

Used to avoid doing anything in ParserBeforeTidy.

Definition at line 146 of file Cite.php.

◆ $mInCite

boolean Cite::$mInCite = false

True when a <ref> tag is being processed.

Used to avoid infinite recursion

Definition at line 154 of file Cite.php.

◆ $mInReferences

boolean Cite::$mInReferences = false

True when a <references> tag is being processed.

Used to detect the use of <references> to define refs

Definition at line 162 of file Cite.php.

◆ $mLinkLabels

array Cite::$mLinkLabels = []

private

The links to use per group, in order.

Definition at line 133 of file Cite.php.

◆ $mOutCnt

int Cite::$mOutCnt = 0

private

Count for user displayed output (ref[1], ref[2], ...)

Definition at line 104 of file Cite.php.

Referenced by stack().

◆ $mParser

Parser Cite::$mParser

private

Definition at line 138 of file Cite.php.

◆ $mRefCallStack

array Cite::$mRefCallStack = []

private

<ref> call stack Used to cleanup out of sequence ref calls created by #tag See description of function rollbackRef.

Definition at line 185 of file Cite.php.

◆ $mReferencesErrors

string [] Cite::$mReferencesErrors = []

private

Error stack used when defining refs in <references>

Definition at line 169 of file Cite.php.

◆ $mReferencesGroup

string Cite::$mReferencesGroup = ''

private

Group used when in <references> block.

Definition at line 176 of file Cite.php.

Referenced by guardedRef().

◆ $mRefs

array [] Cite::$mRefs = []

private

Datastructure representing <ref> input, in the format of: [ 'user supplied' => [ 'text' => 'user supplied reference & key', 'count' => 1, // occurs twice 'number' => 1, // The first reference, we want // all occourances of it to // use the same number ], 0 => 'Anonymous reference', 1 => 'Another anonymous reference', 'some key' => [ 'text' => 'this one occurs once' 'count' => 0, 'number' => 4 ], 3 => 'more stuff' ];

This works because:

PHP's datastructures are guaranteed to be returned in the order that things are inserted into them (unless you mess with that)
User supplied keys can't be integers, therefore avoiding conflict with anonymous keys

Public Member Functions

Static Public Member Functions

Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Function Documentation

◆ checkRefsNoReferences()

◆ clearState()

◆ cloneState()

◆ error()

◆ genBacklinkLabels()

◆ genLinkLabels()

◆ getLinkLabel()

◆ getReferencesKey()

◆ getStoredReferences()

◆ guardedRef()

◆ guardedReferences()

◆ linkRef()

◆ listToText()

◆ normalizeKey()

◆ plainError()

◆ recursiveFetchRefsFromDB()

◆ ref()

◆ refArg()

◆ references()

◆ referencesFormat()

◆ referencesFormatEntry()

◆ referencesFormatEntryAlternateBacklinkLabel()

◆ referencesFormatEntryNumericBacklinkLabel()

◆ referenceText()

◆ refKey()

◆ rollbackRef()

◆ saveReferencesData()

◆ setHooks()

◆ stack()

◆ warning()

Member Data Documentation

◆ $hooksInstalled

◆ $mBacklinkLabels

◆ $mBumpRefData

◆ $mCallCnt

◆ $mGroupCnt

◆ $mHaveAfterParse

◆ $mInCite

◆ $mInReferences

◆ $mLinkLabels

◆ $mOutCnt

◆ $mParser

◆ $mRefCallStack

◆ $mReferencesErrors

◆ $mReferencesGroup

◆ $mRefs

◆ CACHE_DURATION_ONFETCH

◆ CACHE_DURATION_ONPARSE

◆ DATA_VERSION_NUMBER

◆ DEFAULT_GROUP

◆ EXT_DATA_KEY

◆ MAX_STORAGE_LENGTH