MediaWiki REL1_34
Public Member Functions | Static Public Member Functions | Public Attributes | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | List of all members
Cite Class Reference
Collaboration diagram for Cite:
Collaboration graph
[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 whitespace.
 
 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 whitespace.
 
 getLinkLabel ( $offset, $group, $label)
 Generate a custom format link for a group given an offset, e.g.
 
 guardedRef ( $str, array $argv, Parser $parser)
 
 guardedReferences ( $str, array $argv, Parser $parser)
 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.
 
string[] false[] $mLinkLabels = []
 The links to use per group, in order.
 
int $mOutCnt = 0
 Count for user displayed output (ref[1], ref[2], ...)
 
Parser $mParser
 
array false[] $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

Definition at line 29 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$afterParseTrue if called from the ParserAfterParse hook
Parser$parser
string&$text

Definition at line 1188 of file Cite.php.

References $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 1135 of file Cite.php.

References Parser\clearState().

◆ cloneState()

Cite::cloneState ( Parser $parser)

Gets run when the parser is cloned.

Parameters
Parser$parser

Definition at line 1160 of file Cite.php.

References Parser\clearState(), and Parser\setHook().

◆ error()

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

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

Parameters
string$keyMessage name for the error
string[] | string | null$paramParameter to pass to the message
Returns
string HTML ready for output

Definition at line 1308 of file Cite.php.

References plainError().

Referenced by checkRefsNoReferences(), guardedRef(), and guardedReferences().

◆ 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 whitespace.

Definition at line 1106 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 whitespace.

Parameters
string$group
string$message

Definition at line 1120 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$groupThe group name
string$labelThe text to use if there's no message for them.
Returns
string

Definition at line 971 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 1017 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 1402 of file Cite.php.

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

Referenced by ApiQueryReferences\execute().

◆ guardedRef()

Cite::guardedRef ( $str,
array $argv,
Parser $parser )
private
Parameters
string | null$strRaw content of the <ref> tag.
string[]$argvArguments
Parser$parser
Exceptions
Exception
Returns
string

Definition at line 237 of file Cite.php.

References $mReferencesGroup, DEFAULT_GROUP, error(), Parser\getOptions(), plainError(), refArg(), serialize(), and stack().

Referenced by guardedReferences(), and ref().

◆ guardedReferences()

Cite::guardedReferences ( $str,
array $argv,
Parser $parser )
private

Must only be called from references().

Use that to prevent recursion.

Parameters
string | null$strRaw content of the <references> tag.
string[]$argv
Parser$parser
Returns
string

Definition at line 666 of file Cite.php.

References $s, $type, DEFAULT_GROUP, error(), guardedRef(), Parser\recursiveTagParse(), 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.

SecurityCheck-DoubleEscaped

Parameters
string$group
string$keyThe key for the link
int | null$countThe index of the key, used for distinguishing multiple occurrences of the same key
int | null$labelThe 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 1040 of file Cite.php.

References 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
string[]$arrThe array to format
Returns
string

Definition at line 1088 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 1070 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$keyMessage name for the error
string[] | string | null$paramParameter to pass to the message
Returns
string wikitext ready for output
-taint tainted

Definition at line 1321 of file Cite.php.

References $lang, 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 1435 of file Cite.php.

References $dbr, $title, 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$strRaw content of the <ref> tag.
string[]$argvArguments
Parser$parser
PPFrame$frame
Returns
string

Definition at line 204 of file Cite.php.

References Parser\getOutput(), 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[]$argvThe argument vector
Returns
(string|false|null)[] An array with exactly four elements, where each is a string on valid input, false on invalid input, or null on no input.
-taint tainted

Definition at line 398 of file Cite.php.

Referenced by guardedRef().

◆ references()

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

Callback function for <references>

Parameters
string | null$strRaw content of the <references> tag.
string[]$argvArguments
Parser$parser
PPFrame$frame
Returns
string

Definition at line 642 of file Cite.php.

References 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 761 of file Cite.php.

References referencesFormatEntry(), and saveReferencesData().

Referenced by checkRefsNoReferences(), and guardedReferences().

◆ referencesFormatEntry()

Cite::referencesFormatEntry ( $key,
$val )
private

Format a single entry for the referencesFormat() function.

Parameters
string$keyThe key of the reference
mixed$valThe value of the reference, string for anonymous references, array for user-suppplied
Returns
string Wikitext

Definition at line 810 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 947 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$maxMaximum value expected.
Returns
string

Definition at line 929 of file Cite.php.

References $base.

Referenced by referencesFormatEntry().

◆ referenceText()

Cite::referenceText ( $key,
$text )
private

Returns formatted reference text.

Parameters
string$key
string | null$text
Returns
string

Definition at line 909 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 | null$numThe number of the key
Returns
string A key for use in wikitext

Definition at line 998 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 587 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 1253 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 1285 of file Cite.php.

References $wgHooks, Parser\setHook(), 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$strInput from the <ref> tag
string | null$keyArgument to the <ref> tag as returned by $this->refArg()
string$group
string | null$follow
string[]$call
string$dirref direction
Parser$parser
Exceptions
Exception
Returns
string

Definition at line 462 of file Cite.php.

References $mOutCnt, 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$keyMessage name for the warning. Name should start with cite_warning_
string | null$paramParameter to pass to the message
string$parseWhether to parse the message ('parse') or not ('noparse')
Returns
string XHTML or wikitext ready for output

Definition at line 1360 of file Cite.php.

References $lang, and wfMessage().

Referenced by referenceText().

Member Data Documentation

◆ $hooksInstalled

Boolean Cite::$hooksInstalled = false
staticprivate

Did we install us into $wgHooks yet?

Definition at line 192 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 122 of file Cite.php.

◆ $mBumpRefData

bool Cite::$mBumpRefData = false
private

Definition at line 186 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 113 of file Cite.php.

◆ $mGroupCnt

int [] Cite::$mGroupCnt = []
private

Definition at line 105 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 142 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 150 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 158 of file Cite.php.

◆ $mLinkLabels

string [] false [] Cite::$mLinkLabels = []
private

The links to use per group, in order.

Definition at line 129 of file Cite.php.

◆ $mOutCnt

int Cite::$mOutCnt = 0
private

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

Definition at line 100 of file Cite.php.

Referenced by stack().

◆ $mParser

Parser Cite::$mParser
private

Definition at line 134 of file Cite.php.

◆ $mRefCallStack

array false [] 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 181 of file Cite.php.

◆ $mReferencesErrors

string [] Cite::$mReferencesErrors = []
private

Error stack used when defining refs in <references>

Definition at line 165 of file Cite.php.

◆ $mReferencesGroup

string Cite::$mReferencesGroup = ''
private

Group used when in <references> block.

Definition at line 172 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

Definition at line 93 of file Cite.php.

◆ CACHE_DURATION_ONFETCH

const Cite::CACHE_DURATION_ONFETCH = 18000

Cache duration set when fetching references from db.

Definition at line 60 of file Cite.php.

◆ CACHE_DURATION_ONPARSE

const Cite::CACHE_DURATION_ONPARSE = 3600

Cache duration set when parsing a page with references.

Definition at line 55 of file Cite.php.

Referenced by CiteHooks\onLinksUpdate().

◆ DATA_VERSION_NUMBER

const Cite::DATA_VERSION_NUMBER = 1

Version number in case we change the data structure in the future.

Definition at line 50 of file Cite.php.

Referenced by saveReferencesData().

◆ DEFAULT_GROUP

const Cite::DEFAULT_GROUP = ''
Todo
document

Definition at line 34 of file Cite.php.

Referenced by guardedRef(), and guardedReferences().

◆ EXT_DATA_KEY

const Cite::EXT_DATA_KEY = 'Cite:References'

Key used for storage in parser output's ExtensionData and ObjectCache.

Definition at line 45 of file Cite.php.

Referenced by CiteHooks\onLinksUpdate(), and CiteHooks\onLinksUpdateComplete().

◆ MAX_STORAGE_LENGTH

const Cite::MAX_STORAGE_LENGTH = 65535

Maximum storage capacity for pp_value field of page_props table.

Todo
Find a way to retrieve this information from the DBAL

Definition at line 40 of file Cite.php.

Referenced by CiteHooks\onLinksUpdate().

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