MediaWiki REL1_30
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

A parser extension that adds two tags, <ref> and <references> for adding citations to pages. More...

Collaboration diagram for Cite:
Collaboration graph
[legend]

Public Member Functions

 checkAnyCalls (&$output)
 Hook for the InlineEditor extension.
 
 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, $parse='parse')
 Return an error message based on an error ID.
 
 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)
 
 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.
 
 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.
 
 referenceText ( $key, $text)
 Returns formatted reference text.
 
 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=null, $group, $follow, array $call)
 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

 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.
 
static recursiveFetchRefsFromDB (Title $title, DatabaseBase $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.
 
 referencesFormatEntryNumericBacklinkLabel ( $base, $offset, $max)
 Generate a numeric backlink given a base number and an offset, e.g.
 
 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)
 

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

A parser extension that adds two tags, <ref> and <references> for adding citations to pages.

Documentation definition in HTML http://www.w3.org/TR/html4/struct/text.html#edef-CITE definition in XHTML 2.0 http://www.w3.org/TR/2005/WD-xhtml2-20050527/mod-text.html#edef_text_cite bug 1. Ævar Arnfjörð Bjarmason avara.nosp@m.b@gm.nosp@m.ail.c.nosp@m.om Copyright © 2005, Ævar Arnfjörð Bjarmason http://www.gnu.org/copyleft/gpl.html GNU General Public License 2.0 or later WARNING: MediaWiki core hardcodes this class name to check if the Cite extension is installed. See T89151.

Definition at line 29 of file Cite.php.

Member Function Documentation

◆ checkAnyCalls()

Cite::checkAnyCalls ( & $output)

Hook for the InlineEditor extension.

If any ref or reference reference tag is in the text, the entire page should be reparsed, so we return false in that case.

Parameters
$output
Returns
bool

Definition at line 1250 of file Cite.php.

References $wgParser.

◆ 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
Returns
bool

Definition at line 1154 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
Returns
bool

Definition at line 1095 of file Cite.php.

References $parser.

◆ cloneState()

Cite::cloneState ( Parser $parser)

Gets run when the parser is cloned.

Parameters
Parser$parser
Returns
bool

Definition at line 1123 of file Cite.php.

References $parser.

◆ error()

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

Return an error message based on an error ID.

Parameters
string$keyMessage name for the error
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 1290 of file Cite.php.

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

◆ 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 1064 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 1078 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$offsetThe offset
string$groupThe group name
string$labelThe text to use if there's no message for them.
Returns
string

Definition at line 944 of file Cite.php.

References error, and genLinkLabels().

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$keyThe key
Returns
string A key for use in wikitext

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

References $cache, $dbr, 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$strRaw content of the <ref> tag.
string[]$argvArguments
Parser$parser
string$default_group
Exceptions
Exception
Returns
string

Definition at line 240 of file Cite.php.

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

Referenced by guardedReferences(), and ref().

◆ guardedReferences()

Cite::guardedReferences ( $str,
array $argv,
Parser $parser,
$group = self::DEFAULT_GROUP )
private
Parameters
string | null$strRaw content of the <references> tag.
string[]$argv
Parser$parser
string$group
Returns
string

Definition at line 642 of file Cite.php.

References $argv, $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.

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

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

Referenced by stack().

◆ listToText()

Cite::listToText ( $arr)
staticprivate

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

Definition at line 1044 of file Cite.php.

References $t, and wfMessage().

Referenced by referencesFormatEntry().

◆ recursiveFetchRefsFromDB()

static Cite::recursiveFetchRefsFromDB ( Title $title,
DatabaseBase $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
DatabaseBase$dbr
string$string
int$i
Returns
array|false

Definition at line 1408 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$strRaw content of the <ref> tag.
string[]$argvArguments
Parser$parser
PPFrame$frame
Returns
string

Definition at line 204 of file Cite.php.

References $argv, $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.

Parameters
string[]$argvThe argument vector
Returns
mixed false on invalid input, a string on valid input and null on no input

Definition at line 390 of file Cite.php.

References $argv, and false.

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

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

◆ referencesFormat()

Cite::referencesFormat ( $group,
$responsive )
private

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

Parameters
string$group
bool$responsive
Returns
string HTML ready for output

Definition at line 733 of file Cite.php.

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

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

References listToText(), 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$offsetThe offset
Returns
string

Definition at line 920 of file Cite.php.

References error, and genBacklinkLabels().

Referenced by referencesFormatEntry().

◆ referencesFormatEntryNumericBacklinkLabel()

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

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$baseThe base
int$offsetThe offset
int$maxMaximum value expected.
Returns
string

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

References error, and warning().

Referenced by referencesFormatEntry().

◆ refKey()

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

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$keyThe key
int$numThe number of the key
Returns
string A key for use in wikitext

Definition at line 973 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 562 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
$group

Definition at line 1214 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
Returns
bool

Definition at line 1263 of file Cite.php.

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

◆ stack()

Cite::stack ( $str,
$key = null,
$group,
$follow,
array $call )
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
Exceptions
Exception
Returns
string

Definition at line 447 of file Cite.php.

References $mOutCnt, error, linkRef(), 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 1333 of file Cite.php.

References $dir, $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 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

array 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 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.

◆ 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: