Cite.php

Go to the documentation of this file.

<?php
 
use MediaWiki\MediaWikiServices;
use Wikimedia\Rdbms\IDatabase;
use Wikimedia\Rdbms\Database;
 
class Cite {
 
    const DEFAULT_GROUP = '';
 
    const MAX_STORAGE_LENGTH = 65535; // Size of MySQL 'blob' field
 
    const EXT_DATA_KEY = 'Cite:References';
 
    const DATA_VERSION_NUMBER = 1;
 
    const CACHE_DURATION_ONPARSE = 3600; // 1 hour
 
    const CACHE_DURATION_ONFETCH = 18000; // 5 hours
 
    private $mRefs = [];
 
    private $mOutCnt = 0;
 
    private $mGroupCnt = [];
 
    private $mCallCnt = 0;
 
    private $mBacklinkLabels;
 
    private $mLinkLabels = [];
 
    private $mParser;
 
    private $mHaveAfterParse = false;
 
    public $mInCite = false;
 
    public $mInReferences = false;
 
    private $mReferencesErrors = [];
 
    private $mReferencesGroup = '';
 
    private $mRefCallStack = [];
 
    private $mBumpRefData = false;
 
    private static $hooksInstalled = false;
 
    public function ref( $str, array $argv, Parser $parser, PPFrame $frame ) {
        if ( $this->mInCite ) {
            return htmlspecialchars( "<ref>$str</ref>" );
        }
 
        $this->mCallCnt++;
        $this->mInCite = true;
 
        $ret = $this->guardedRef( $str, $argv, $parser );
 
        $this->mInCite = false;
 
        $parserOutput = $parser->getOutput();
        $parserOutput->addModules( 'ext.cite.ux-enhancements' );
        $parserOutput->addModuleStyles( 'ext.cite.styles' );
 
        $frame->setVolatile();
 
        // new <ref> tag, we may need to bump the ref data counter
        // to avoid overwriting a previous group
        $this->mBumpRefData = true;
 
        return $ret;
    }
 
    private function guardedRef(
        $str,
        array $argv,
        Parser $parser
    ) {
        $this->mParser = $parser;
 
        # The key here is the "name" attribute.
        list( $key, $group, $follow, $dir ) = $this->refArg( $argv );
        // empty string indicate invalid dir
        if ( $dir === '' && $str !== '' ) {
            $str .= $this->plainError( 'cite_error_ref_invalid_dir', $argv['dir'] );
        }
        # Split these into groups.
        if ( $group === null ) {
            if ( $this->mInReferences ) {
                $group = $this->mReferencesGroup;
            } else {
                $group = self::DEFAULT_GROUP;
            }
        }
 
        /*
         * This section deals with constructions of the form
         *
         * <references>
         * <ref name="foo"> BAR </ref>
         * </references>
         */
        if ( $this->mInReferences ) {
            $isSectionPreview = $parser->getOptions()->getIsSectionPreview();
            if ( $group != $this->mReferencesGroup ) {
                # <ref> and <references> have conflicting group attributes.
                $this->mReferencesErrors[] =
                    $this->error(
                        'cite_error_references_group_mismatch',
                        Sanitizer::safeEncodeAttribute( $group )
                    );
            } elseif ( $str !== '' ) {
                if ( !$isSectionPreview && !isset( $this->mRefs[$group] ) ) {
                    # Called with group attribute not defined in text.
                    $this->mReferencesErrors[] =
                        $this->error(
                            'cite_error_references_missing_group',
                            Sanitizer::safeEncodeAttribute( $group )
                        );
                } elseif ( $key === null || $key === '' ) {
                    # <ref> calls inside <references> must be named
                    $this->mReferencesErrors[] =
                        $this->error( 'cite_error_references_no_key' );
                } elseif ( !$isSectionPreview && !isset( $this->mRefs[$group][$key] ) ) {
                    # Called with name attribute not defined in text.
                    $this->mReferencesErrors[] =
                        $this->error( 'cite_error_references_missing_key', Sanitizer::safeEncodeAttribute( $key ) );
                } else {
                    if (
                        isset( $this->mRefs[$group][$key]['text'] ) &&
                        $str !== $this->mRefs[$group][$key]['text']
                    ) {
                        // two refs with same key and different content
                        // add error message to the original ref
                        $this->mRefs[$group][$key]['text'] .= ' ' . $this->plainError(
                            'cite_error_references_duplicate_key', $key
                        );
                    } else {
                        # Assign the text to corresponding ref
                        $this->mRefs[$group][$key]['text'] = $str;
                    }
                }
            } else {
                # <ref> called in <references> has no content.
                $this->mReferencesErrors[] =
                    $this->error( 'cite_error_empty_references_define', Sanitizer::safeEncodeAttribute( $key ) );
            }
            return '';
        }
 
        if ( $str === '' ) {
            # <ref ...></ref>.  This construct is  invalid if
            # it's a contentful ref, but OK if it's a named duplicate and should
            # be equivalent <ref ... />, for compatability with #tag.
            if ( is_string( $key ) && $key !== '' ) {
                $str = null;
            } else {
                $this->mRefCallStack[] = false;
 
                return $this->error( 'cite_error_ref_no_input' );
            }
        }
 
        if ( $key === false ) {
            # TODO: Comment this case; what does this condition mean?
            $this->mRefCallStack[] = false;
            return $this->error( 'cite_error_ref_too_many_keys' );
        }
 
        if ( $str === null && $key === null ) {
            # Something like <ref />; this makes no sense.
            $this->mRefCallStack[] = false;
            return $this->error( 'cite_error_ref_no_key' );
        }
 
        if ( is_string( $key ) && preg_match( '/^\d+$/', $key ) ||
            is_string( $follow ) && preg_match( '/^\d+$/', $follow )
        ) {
            # Numeric names mess up the resulting id's, potentially produ-
            # cing duplicate id's in the XHTML.  The Right Thing To Do
            # would be to mangle them, but it's not really high-priority
            # (and would produce weird id's anyway).
 
            $this->mRefCallStack[] = false;
            return $this->error( 'cite_error_ref_numeric_key' );
        }
 
        if ( preg_match(
            '/<ref\b[^<]*?>/',
            preg_replace( '#<([^ ]+?).*?>.*?</\\1 *>|<!--.*?-->#', '', $str )
        ) ) {
            # (bug T8199) This most likely implies that someone left off the
            # closing </ref> tag, which will cause the entire article to be
            # eaten up until the next <ref>.  So we bail out early instead.
            # The fancy regex above first tries chopping out anything that
            # looks like a comment or SGML tag, which is a crude way to avoid
            # false alarms for <nowiki>, <pre>, etc.
 
            # Possible improvement: print the warning, followed by the contents
            # of the <ref> tag.  This way no part of the article will be eaten
            # even temporarily.
 
            $this->mRefCallStack[] = false;
            return $this->error( 'cite_error_included_ref' );
        }
 
        if ( is_string( $key ) || is_string( $str ) ) {
            # We don't care about the content: if the key exists, the ref
            # is presumptively valid.  Either it stores a new ref, or re-
            # fers to an existing one.  If it refers to a nonexistent ref,
            # we'll figure that out later.  Likewise it's definitely valid
            # if there's any content, regardless of key.
 
            return $this->stack( $str, $key, $group, $follow, $argv, $dir, $parser );
        }
 
        # Not clear how we could get here, but something is probably
        # wrong with the types.  Let's fail fast.
        throw new Exception( 'Invalid $str and/or $key: ' . serialize( [ $str, $key ] ) );
    }
 
    private function refArg( array $argv ) {
        $group = null;
        $key = null;
        $follow = null;
        $dir = null;
 
        if ( isset( $argv['dir'] ) ) {
            // compare the dir attribute value against an explicit whitelist.
            $dir = '';
            $isValidDir = in_array( strtolower( $argv['dir'] ), [ 'ltr', 'rtl' ] );
            if ( $isValidDir ) {
                $dir = Html::expandAttributes( [ 'class' => 'mw-cite-dir-' . strtolower( $argv['dir'] ) ] );
            }
 
            unset( $argv['dir'] );
        }
 
        if ( $argv === [] ) {
            // No key
            return [ null, null, false, $dir ];
        }
 
        if ( isset( $argv['name'] ) && isset( $argv['follow'] ) ) {
            return [ false, false, false, false ];
        }
 
        if ( isset( $argv['name'] ) ) {
            // Key given.
            $key = trim( $argv['name'] );
            unset( $argv['name'] );
        }
        if ( isset( $argv['follow'] ) ) {
            // Follow given.
            $follow = trim( $argv['follow'] );
            unset( $argv['follow'] );
        }
        if ( isset( $argv['group'] ) ) {
            // Group given.
            $group = $argv['group'];
            unset( $argv['group'] );
        }
 
        if ( $argv !== [] ) {
            // Invalid key
            return [ false, false, false, false ];
        }
 
        return [ $key, $group, $follow, $dir ];
    }
 
    private function stack( $str, $key, $group, $follow, array $call, $dir, Parser $parser ) {
        if ( !isset( $this->mRefs[$group] ) ) {
            $this->mRefs[$group] = [];
        }
        if ( !isset( $this->mGroupCnt[$group] ) ) {
            $this->mGroupCnt[$group] = 0;
        }
        if ( $follow != null ) {
            if ( isset( $this->mRefs[$group][$follow] ) && is_array( $this->mRefs[$group][$follow] ) ) {
                // add text to the note that is being followed
                $this->mRefs[$group][$follow]['text'] .= ' ' . $str;
            } else {
                // insert part of note at the beginning of the group
                $groupsCount = count( $this->mRefs[$group] );
                for ( $k = 0; $k < $groupsCount; $k++ ) {
                    if ( !isset( $this->mRefs[$group][$k]['follow'] ) ) {
                        break;
                    }
                }
                array_splice( $this->mRefs[$group], $k, 0, [ [
                    'count' => -1,
                    'text' => $str,
                    'key' => ++$this->mOutCnt,
                    'follow' => $follow,
                    'dir' => $dir
                ] ] );
                array_splice( $this->mRefCallStack, $k, 0,
                    [ [ 'new', $call, $str, $key, $group, $this->mOutCnt ] ] );
            }
            // return an empty string : this is not a reference
            return '';
        }
 
        if ( $key === null ) {
            // No key
            // $this->mRefs[$group][] = $str;
 
            $this->mRefs[$group][] = [
                'count' => -1,
                'text' => $str,
                'key' => ++$this->mOutCnt,
                'dir' => $dir
            ];
            $this->mRefCallStack[] = [ 'new', $call, $str, $key, $group, $this->mOutCnt ];
 
            return $this->linkRef( $group, $this->mOutCnt );
        }
        if ( !is_string( $key ) ) {
            throw new Exception( 'Invalid stack key: ' . serialize( $key ) );
        }
 
        // Valid key
        if ( !isset( $this->mRefs[$group][$key] ) || !is_array( $this->mRefs[$group][$key] ) ) {
            // First occurrence
            $this->mRefs[$group][$key] = [
                'text' => $str,
                'count' => 0,
                'key' => ++$this->mOutCnt,
                'number' => ++$this->mGroupCnt[$group],
                'dir' => $dir
            ];
            $this->mRefCallStack[] = [ 'new', $call, $str, $key, $group, $this->mOutCnt ];
 
            return $this->linkRef(
                $group,
                $key,
                $this->mRefs[$group][$key]['key'] . "-" . $this->mRefs[$group][$key]['count'],
                $this->mRefs[$group][$key]['number'],
                "-" . $this->mRefs[$group][$key]['key']
            );
        }
 
        // We've been here before
        if ( $this->mRefs[$group][$key]['text'] === null && $str !== '' ) {
            // If no text found before, use this text
            $this->mRefs[$group][$key]['text'] = $str;
            // Use the dir parameter only from the full definition of a named ref tag
            $this->mRefs[$group][$key]['dir'] = $dir;
            $this->mRefCallStack[] = [ 'assign', $call, $str, $key, $group,
                $this->mRefs[$group][$key]['key'] ];
        } else {
            if ( $str != null && $str !== ''
                // T205803 different strip markers might hide the same text
                && $parser->mStripState->unstripBoth( $str )
                    !== $parser->mStripState->unstripBoth( $this->mRefs[$group][$key]['text'] )
            ) {
                // two refs with same key and different content
                // add error message to the original ref
                $this->mRefs[$group][$key]['text'] .= ' ' . $this->plainError(
                    'cite_error_references_duplicate_key', $key
                );
            }
            $this->mRefCallStack[] = [ 'increment', $call, $str, $key, $group,
                $this->mRefs[$group][$key]['key'] ];
        }
        return $this->linkRef(
            $group,
            $key,
            $this->mRefs[$group][$key]['key'] . "-" . ++$this->mRefs[$group][$key]['count'],
            $this->mRefs[$group][$key]['number'],
            "-" . $this->mRefs[$group][$key]['key']
        );
    }
 
    private function rollbackRef( $type, $key, $group, $index ) {
        if ( !isset( $this->mRefs[$group] ) ) {
            return;
        }
 
        if ( $key === null ) {
            foreach ( $this->mRefs[$group] as $k => $v ) {
                if ( $this->mRefs[$group][$k]['key'] === $index ) {
                    $key = $k;
                    break;
                }
            }
        }
 
        // Sanity checks that specified element exists.
        if ( $key === null ) {
            return;
        }
        if ( !isset( $this->mRefs[$group][$key] ) ) {
            return;
        }
        if ( $this->mRefs[$group][$key]['key'] != $index ) {
            return;
        }
 
        switch ( $type ) {
        case 'new':
            # Rollback the addition of new elements to the stack.
            unset( $this->mRefs[$group][$key] );
            if ( $this->mRefs[$group] === [] ) {
                unset( $this->mRefs[$group] );
                unset( $this->mGroupCnt[$group] );
            }
            break;
        case 'assign':
            # Rollback assignment of text to pre-existing elements.
            $this->mRefs[$group][$key]['text'] = null;
            # continue without break
        case 'increment':
            # Rollback increase in named ref occurrences.
            $this->mRefs[$group][$key]['count']--;
            break;
        }
    }
 
    public function references( $str, array $argv, Parser $parser, PPFrame $frame ) {
        if ( $this->mInCite || $this->mInReferences ) {
            if ( $str === null ) {
                return htmlspecialchars( "<references/>" );
            }
            return htmlspecialchars( "<references>$str</references>" );
        }
        $this->mCallCnt++;
        $this->mInReferences = true;
        $ret = $this->guardedReferences( $str, $argv, $parser );
        $this->mInReferences = false;
        $frame->setVolatile();
        return $ret;
    }
 
    private function guardedReferences(
        $str,
        array $argv,
        Parser $parser
    ) {
        global $wgCiteResponsiveReferences;
 
        $this->mParser = $parser;
 
        if ( isset( $argv['group'] ) ) {
            $group = $argv['group'];
            unset( $argv['group'] );
        } else {
            $group = self::DEFAULT_GROUP;
        }
 
        if ( strval( $str ) !== '' ) {
            $this->mReferencesGroup = $group;
 
            # Detect whether we were sent already rendered <ref>s.
            # Mostly a side effect of using #tag to call references.
            # The following assumes that the parsed <ref>s sent within
            # the <references> block were the most recent calls to
            # <ref>.  This assumption is true for all known use cases,
            # but not strictly enforced by the parser.  It is possible
            # that some unusual combination of #tag, <references> and
            # conditional parser functions could be created that would
            # lead to malformed references here.
            $count = substr_count( $str, Parser::MARKER_PREFIX . "-ref-" );
            $redoStack = [];
 
            # Undo effects of calling <ref> while unaware of containing <references>
            for ( $i = 1; $i <= $count; $i++ ) {
                if ( !$this->mRefCallStack ) {
                    break;
                }
 
                $call = array_pop( $this->mRefCallStack );
                $redoStack[] = $call;
                if ( $call !== false ) {
                    list( $type, $ref_argv, $ref_str,
                        $ref_key, $ref_group, $ref_index ) = $call;
                    $this->rollbackRef( $type, $ref_key, $ref_group, $ref_index );
                }
            }
 
            # Rerun <ref> call now that mInReferences is set.
            for ( $i = count( $redoStack ) - 1; $i >= 0; $i-- ) {
                $call = $redoStack[$i];
                if ( $call !== false ) {
                    list( $type, $ref_argv, $ref_str,
                        $ref_key, $ref_group, $ref_index ) = $call;
                    $this->guardedRef( $ref_str, $ref_argv, $parser );
                }
            }
 
            # Parse $str to process any unparsed <ref> tags.
            $parser->recursiveTagParse( $str );
 
            # Reset call stack
            $this->mRefCallStack = [];
        }
 
        if ( isset( $argv['responsive'] ) ) {
            $responsive = $argv['responsive'] !== '0';
            unset( $argv['responsive'] );
        } else {
            $responsive = $wgCiteResponsiveReferences;
        }
 
        // There are remaining parameters we don't recognise
        if ( $argv ) {
            return $this->error( 'cite_error_references_invalid_parameters' );
        }
 
        $s = $this->referencesFormat( $group, $responsive );
 
        # Append errors generated while processing <references>
        if ( $this->mReferencesErrors ) {
            $s .= "\n" . implode( "<br />\n", $this->mReferencesErrors );
            $this->mReferencesErrors = [];
        }
        return $s;
    }
 
    private function referencesFormat( $group, $responsive ) {
        if ( !$this->mRefs || !isset( $this->mRefs[$group] ) ) {
            return '';
        }
 
        $ent = [];
        foreach ( $this->mRefs[$group] as $k => $v ) {
            $ent[] = $this->referencesFormatEntry( $k, $v );
        }
 
        // Add new lines between the list items (ref entires) to avoid confusing tidy (T15073).
        // Note: This builds a string of wikitext, not html.
        $parserInput = Html::rawElement( 'ol', [ 'class' => [ 'references' ] ],
            "\n" . implode( "\n", $ent ) . "\n"
        );
 
        // Live hack: parse() adds two newlines on WM, can't reproduce it locally -ævar
        $ret = rtrim( $this->mParser->recursiveTagParse( $parserInput ), "\n" );
 
        if ( $responsive ) {
            // Use a DIV wrap because column-count on a list directly is broken in Chrome.
            // See https://bugs.chromium.org/p/chromium/issues/detail?id=498730.
            $wrapClasses = [ 'mw-references-wrap' ];
            if ( count( $this->mRefs[$group] ) > 10 ) {
                $wrapClasses[] = 'mw-references-columns';
            }
            $ret = Html::rawElement( 'div', [ 'class' => $wrapClasses ], $ret );
        }
 
        if ( !$this->mParser->getOptions()->getIsPreview() ) {
            // save references data for later use by LinksUpdate hooks
            $this->saveReferencesData( $group );
        }
 
        // done, clean up so we can reuse the group
        unset( $this->mRefs[$group] );
        unset( $this->mGroupCnt[$group] );
 
        return $ret;
    }
 
    private function referencesFormatEntry( $key, $val ) {
        // Anonymous reference
        if ( !is_array( $val ) ) {
            return wfMessage(
                    'cite_references_link_one',
                    $this->normalizeKey(
                        self::getReferencesKey( $key )
                    ),
                    $this->normalizeKey(
                        $this->refKey( $key )
                    ),
                    $this->referenceText( $key, $val ),
                    $val['dir']
                )->inContentLanguage()->plain();
        }
        $text = $this->referenceText( $key, $val['text'] );
        if ( isset( $val['follow'] ) ) {
            return wfMessage(
                    'cite_references_no_link',
                    $this->normalizeKey(
                        self::getReferencesKey( $val['follow'] )
                    ),
                    $text
                )->inContentLanguage()->plain();
        }
        if ( !isset( $val['count'] ) ) {
            // this handles the case of section preview for list-defined references
            return wfMessage( 'cite_references_link_many',
                    $this->normalizeKey(
                        self::getReferencesKey( $key . "-" . ( $val['key'] ?? '' ) )
                    ),
                    '',
                    $text
                )->inContentLanguage()->plain();
        }
        if ( $val['count'] < 0 ) {
            return wfMessage(
                    'cite_references_link_one',
                    $this->normalizeKey(
                        self::getReferencesKey( $val['key'] )
                    ),
                    $this->normalizeKey(
                        # $this->refKey( $val['key'], $val['count'] )
                        $this->refKey( $val['key'] )
                    ),
                    $text,
                    $val['dir']
                )->inContentLanguage()->plain();
            // Standalone named reference, I want to format this like an
            // anonymous reference because displaying "1. 1.1 Ref text" is
            // overkill and users frequently use named references when they
            // don't need them for convenience
        }
        if ( $val['count'] === 0 ) {
            return wfMessage(
                    'cite_references_link_one',
                    $this->normalizeKey(
                        self::getReferencesKey( $key . "-" . $val['key'] )
                    ),
                    $this->normalizeKey(
                        # $this->refKey( $key, $val['count'] ),
                        $this->refKey( $key, $val['key'] . "-" . $val['count'] )
                    ),
                    $text,
                    $val['dir']
                )->inContentLanguage()->plain();
        // Named references with >1 occurrences
        }
        $links = [];
        // for group handling, we have an extra key here.
        for ( $i = 0; $i <= $val['count']; ++$i ) {
            $links[] = wfMessage(
                    'cite_references_link_many_format',
                    $this->normalizeKey(
                        $this->refKey( $key, $val['key'] . "-$i" )
                    ),
                    $this->referencesFormatEntryNumericBacklinkLabel( $val['number'], $i, $val['count'] ),
                    $this->referencesFormatEntryAlternateBacklinkLabel( $i )
            )->inContentLanguage()->plain();
        }
 
        $list = $this->listToText( $links );
 
        return wfMessage( 'cite_references_link_many',
                $this->normalizeKey(
                    self::getReferencesKey( $key . "-" . $val['key'] )
                ),
                $list,
                $text,
                $val['dir']
            )->inContentLanguage()->plain();
    }
 
    private function referenceText( $key, $text ) {
        if ( $text === null || $text === '' ) {
            if ( $this->mParser->getOptions()->getIsSectionPreview() ) {
                return $this->warning( 'cite_warning_sectionpreview_no_text', $key, 'noparse' );
            }
            return $this->plainError( 'cite_error_references_no_text', $key );
        }
        return '<span class="reference-text">' . rtrim( $text, "\n" ) . "</span>\n";
    }
 
    private function referencesFormatEntryNumericBacklinkLabel( $base, $offset, $max ) {
        global $wgContLang;
        $scope = strlen( $max );
        $ret = $wgContLang->formatNum(
            sprintf( "%s.%0{$scope}s", $base, $offset )
        );
        return $ret;
    }
 
    private function referencesFormatEntryAlternateBacklinkLabel( $offset ) {
        if ( !isset( $this->mBacklinkLabels ) ) {
            $this->genBacklinkLabels();
        }
        if ( isset( $this->mBacklinkLabels[$offset] ) ) {
            return $this->mBacklinkLabels[$offset];
        } else {
            // Feed me!
            return $this->plainError( 'cite_error_references_no_backlink_label', null );
        }
    }
 
    private function getLinkLabel( $offset, $group, $label ) {
        $message = "cite_link_label_group-$group";
        if ( !isset( $this->mLinkLabels[$group] ) ) {
            $this->genLinkLabels( $group, $message );
        }
        if ( $this->mLinkLabels[$group] === false ) {
            // Use normal representation, ie. "$group 1", "$group 2"...
            return $label;
        }
 
        if ( isset( $this->mLinkLabels[$group][$offset - 1] ) ) {
            return $this->mLinkLabels[$group][$offset - 1];
        } else {
            // Feed me!
            return $this->plainError( 'cite_error_no_link_label_group', [ $group, $message ] );
        }
    }
 
    private function refKey( $key, $num = null ) {
        $prefix = wfMessage( 'cite_reference_link_prefix' )->inContentLanguage()->text();
        $suffix = wfMessage( 'cite_reference_link_suffix' )->inContentLanguage()->text();
        if ( $num !== null ) {
            $key = wfMessage( 'cite_reference_link_key_with_num', $key, $num )
                ->inContentLanguage()->plain();
        }
 
        return "$prefix$key$suffix";
    }
 
    public static function getReferencesKey( $key ) {
        $prefix = wfMessage( 'cite_references_link_prefix' )->inContentLanguage()->text();
        $suffix = wfMessage( 'cite_references_link_suffix' )->inContentLanguage()->text();
 
        return "$prefix$key$suffix";
    }
 
    private function linkRef( $group, $key, $count = null, $label = null, $subkey = '' ) {
        global $wgContLang;
 
        if ( $label === null ) {
            $label = ++$this->mGroupCnt[$group];
        }
 
        return $this->mParser->recursiveTagParse(
                wfMessage(
                    'cite_reference_link',
                    $this->normalizeKey(
                        $this->refKey( $key, $count )
                    ),
                    $this->normalizeKey(
                        self::getReferencesKey( $key . $subkey )
                    ),
                    Sanitizer::safeEncodeAttribute(
                        $this->getLinkLabel( $label, $group,
                            ( ( $group === self::DEFAULT_GROUP ) ? '' : "$group " ) . $wgContLang->formatNum( $label ) )
                    )
                )->inContentLanguage()->plain()
            );
    }
 
    private function normalizeKey( $key ) {
        $key = Sanitizer::escapeIdForAttribute( $key );
        $key = preg_replace( '/__+/', '_', $key );
        $key = Sanitizer::safeEncodeAttribute( $key );
 
        return $key;
    }
 
    private function listToText( $arr ) {
        $cnt = count( $arr );
        if ( $cnt === 1 ) {
            // Enforce always returning a string
            return (string)$arr[0];
        }
 
        $sep = wfMessage( 'cite_references_link_many_sep' )->inContentLanguage()->plain();
        $and = wfMessage( 'cite_references_link_many_and' )->inContentLanguage()->plain();
        $t = array_slice( $arr, 0, $cnt - 1 );
        return implode( $sep, $t ) . $and . $arr[$cnt - 1];
    }
 
    private function genBacklinkLabels() {
        $text = wfMessage( 'cite_references_link_many_format_backlink_labels' )
            ->inContentLanguage()->plain();
        $this->mBacklinkLabels = preg_split( '/\s+/', $text );
    }
 
    private function genLinkLabels( $group, $message ) {
        $text = false;
        $msg = wfMessage( $message )->inContentLanguage();
        if ( $msg->exists() ) {
            $text = $msg->plain();
        }
        $this->mLinkLabels[$group] = $text ? preg_split( '/\s+/', $text ) : false;
    }
 
    public function clearState( Parser $parser ) {
        if ( $parser->extCite !== $this ) {
            $parser->extCite->clearState( $parser );
            return;
        }
 
        # Don't clear state when we're in the middle of parsing
        # a <ref> tag
        if ( $this->mInCite || $this->mInReferences ) {
            return;
        }
 
        $this->mGroupCnt = [];
        $this->mOutCnt = 0;
        $this->mCallCnt = 0;
        $this->mRefs = [];
        $this->mReferencesErrors = [];
        $this->mRefCallStack = [];
    }
 
    public function cloneState( Parser $parser ) {
        if ( $parser->extCite !== $this ) {
            $parser->extCite->cloneState( $parser );
            return;
        }
 
        $parser->extCite = clone $this;
        $parser->setHook( 'ref', [ $parser->extCite, 'ref' ] );
        $parser->setHook( 'references', [ $parser->extCite, 'references' ] );
 
        // Clear the state, making sure it will actually work.
        $parser->extCite->mInCite = false;
        $parser->extCite->mInReferences = false;
        $parser->extCite->clearState( $parser );
    }
 
    public function checkRefsNoReferences( $afterParse, $parser, &$text ) {
        global $wgCiteResponsiveReferences;
        if ( $parser->extCite === null ) {
            return;
        }
        if ( $parser->extCite !== $this ) {
            $parser->extCite->checkRefsNoReferences( $afterParse, $parser, $text );
            return;
        }
 
        if ( $afterParse ) {
            $this->mHaveAfterParse = true;
        } elseif ( $this->mHaveAfterParse ) {
            return;
        }
 
        if ( !$parser->getOptions()->getIsPreview() ) {
            // save references data for later use by LinksUpdate hooks
            if ( $this->mRefs && isset( $this->mRefs[self::DEFAULT_GROUP] ) ) {
                $this->saveReferencesData();
            }
            $isSectionPreview = false;
        } else {
            $isSectionPreview = $parser->getOptions()->getIsSectionPreview();
        }
 
        $s = '';
        foreach ( $this->mRefs as $group => $refs ) {
            if ( !$refs ) {
                continue;
            }
            if ( $group === self::DEFAULT_GROUP || $isSectionPreview ) {
                $this->mInReferences = true;
                $s .= $this->referencesFormat( $group, $wgCiteResponsiveReferences );
                $this->mInReferences = false;
            } else {
                $s .= "\n<br />" .
                    $this->error(
                        'cite_error_group_refs_without_references',
                        Sanitizer::safeEncodeAttribute( $group )
                    );
            }
        }
        if ( $isSectionPreview && $s !== '' ) {
            // provide a preview of references in its own section
            $text .= "\n" . '<div class="mw-ext-cite-cite_section_preview_references" >';
            $headerMsg = wfMessage( 'cite_section_preview_references' );
            if ( !$headerMsg->isDisabled() ) {
                $text .= '<h2 id="mw-ext-cite-cite_section_preview_references_header" >'
                . $headerMsg->escaped()
                . '</h2>';
            }
            $text .= $s . '</div>';
        } else {
            $text .= $s;
        }
    }
 
    private function saveReferencesData( $group = self::DEFAULT_GROUP ) {
        global $wgCiteStoreReferencesData;
        if ( !$wgCiteStoreReferencesData ) {
            return;
        }
        $savedRefs = $this->mParser->getOutput()->getExtensionData( self::EXT_DATA_KEY );
        if ( $savedRefs === null ) {
            // Initialize array structure
            $savedRefs = [
                'refs' => [],
                'version' => self::DATA_VERSION_NUMBER,
            ];
        }
        if ( $this->mBumpRefData ) {
            // This handles pages with multiple <references/> tags with <ref> tags in between.
            // On those, a group can appear several times, so we need to avoid overwriting
            // a previous appearance.
            $savedRefs['refs'][] = [];
            $this->mBumpRefData = false;
        }
        $n = count( $savedRefs['refs'] ) - 1;
        // save group
        $savedRefs['refs'][$n][$group] = $this->mRefs[$group];
 
        $this->mParser->getOutput()->setExtensionData( self::EXT_DATA_KEY, $savedRefs );
    }
 
    public static function setHooks( Parser $parser ) {
        global $wgHooks;
 
        $parser->extCite = new self();
 
        if ( !self::$hooksInstalled ) {
            $wgHooks['ParserClearState'][] = [ $parser->extCite, 'clearState' ];
            $wgHooks['ParserCloned'][] = [ $parser->extCite, 'cloneState' ];
            $wgHooks['ParserAfterParse'][] = [ $parser->extCite, 'checkRefsNoReferences', true ];
            $wgHooks['ParserBeforeTidy'][] = [ $parser->extCite, 'checkRefsNoReferences', false ];
            self::$hooksInstalled = true;
        }
        $parser->setHook( 'ref', [ $parser->extCite, 'ref' ] );
        $parser->setHook( 'references', [ $parser->extCite, 'references' ] );
    }
 
    private function error( $key, $param = null ) {
        $error = $this->plainError( $key, $param );
        return $this->mParser->recursiveTagParse( $error );
    }
 
    private function plainError( $key, $param = null ) {
        # For ease of debugging and because errors are rare, we
        # use the user language and split the parser cache.
        $lang = $this->mParser->getOptions()->getUserLangObj();
        $dir = $lang->getDir();
 
        # We rely on the fact that PHP is okay with passing unused argu-
        # ments to functions.  If $1 is not used in the message, wfMessage will
        # just ignore the extra parameter.
        $msg = wfMessage(
            'cite_error',
            wfMessage( $key, $param )->inLanguage( $lang )->plain()
        )
            ->inLanguage( $lang )
            ->plain();
 
        $this->mParser->addTrackingCategory( 'cite-tracking-category-cite-error' );
 
        $ret = Html::rawElement(
            'span',
            [
                'class' => 'error mw-ext-cite-error',
                'lang' => $lang->getHtmlCode(),
                'dir' => $dir,
            ],
            $msg
        );
 
        return $ret;
    }
 
    private function warning( $key, $param = null, $parse = 'parse' ) {
        # For ease of debugging and because errors are rare, we
        # use the user language and split the parser cache.
        $lang = $this->mParser->getOptions()->getUserLangObj();
        $dir = $lang->getDir();
 
        # We rely on the fact that PHP is okay with passing unused argu-
        # ments to functions.  If $1 is not used in the message, wfMessage will
        # just ignore the extra parameter.
        $msg = wfMessage(
            'cite_warning',
            wfMessage( $key, $param )->inLanguage( $lang )->plain()
        )
            ->inLanguage( $lang )
            ->plain();
 
        $key = preg_replace( '/^cite_warning_/', '', $key ) . '';
        $ret = Html::rawElement(
            'span',
            [
                'class' => 'warning mw-ext-cite-warning mw-ext-cite-warning-' .
                    Sanitizer::escapeClass( $key ),
                'lang' => $lang->getHtmlCode(),
                'dir' => $dir,
            ],
            $msg
        );
 
        if ( $parse === 'parse' ) {
            $ret = $this->mParser->recursiveTagParse( $ret );
        }
 
        return $ret;
    }
 
    public static function getStoredReferences( Title $title ) {
        global $wgCiteStoreReferencesData;
        if ( !$wgCiteStoreReferencesData ) {
            return false;
        }
        $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
        $key = $cache->makeKey( self::EXT_DATA_KEY, $title->getArticleID() );
        return $cache->getWithSetCallback(
            $key,
            self::CACHE_DURATION_ONFETCH,
            function ( $oldValue, &$ttl, array &$setOpts ) use ( $title ) {
                $dbr = wfGetDB( DB_REPLICA );
                $setOpts += Database::getCacheSetOptions( $dbr );
                return self::recursiveFetchRefsFromDB( $title, $dbr );
            },
            [
                'checkKeys' => [ $key ],
                'lockTSE' => 30,
            ]
        );
    }
 
    private static function recursiveFetchRefsFromDB( Title $title, IDatabase $dbr,
        $string = '', $i = 1 ) {
        $id = $title->getArticleID();
        $result = $dbr->selectField(
            'page_props',
            'pp_value',
            [
                'pp_page' => $id,
                'pp_propname' => 'references-' . $i
            ],
            __METHOD__
        );
        if ( $result !== false ) {
            $string .= $result;
            $decodedString = gzdecode( $string );
            if ( $decodedString !== false ) {
                $json = json_decode( $decodedString, true );
                if ( json_last_error() === JSON_ERROR_NONE ) {
                    return $json;
                }
                // corrupted json ?
                // shouldn't happen since when string is truncated, gzdecode should fail
                wfDebug( "Corrupted json detected when retrieving stored references for title id $id" );
            }
            // if gzdecode fails, try to fetch next references- property value
            return self::recursiveFetchRefsFromDB( $title, $dbr, $string, ++$i );
 
        } else {
            // no refs stored in page_props at this index
            if ( $i > 1 ) {
                // shouldn't happen
                wfDebug( "Failed to retrieve stored references for title id $id" );
            }
            return false;
        }
    }
 
}