LinkRenderer.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Linker;
 
use MediaWiki\Config\ServiceOptions;
use MediaWiki\Context\IContextSource;
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\HookContainer\HookRunner;
use MediaWiki\Html\Html;
use MediaWiki\Language\Language;
use MediaWiki\Linker\LinkTarget as MWLinkTarget;
use MediaWiki\Message\Message;
use MediaWiki\Page\LinkCache;
use MediaWiki\Page\PageReference;
use MediaWiki\Parser\Parser;
use MediaWiki\SpecialPage\SpecialPageFactory;
use MediaWiki\Title\Title;
use MediaWiki\Title\TitleFormatter;
use MediaWiki\Title\TitleValue;
use MediaWiki\User\TempUser\TempUserConfig;
use MediaWiki\User\TempUser\TempUserDetailsLookup;
use MediaWiki\User\UserIdentity;
use MediaWiki\User\UserIdentityLookup;
use MediaWiki\User\UserNameUtils;
use Wikimedia\Assert\Assert;
use Wikimedia\HtmlArmor\HtmlArmor;
use Wikimedia\Parsoid\Core\LinkTarget;
 
class LinkRenderer {
 
    public const CONSTRUCTOR_OPTIONS = [
        'renderForComment',
    ];
 
    private $forceArticlePath = false;
 
    private $expandUrls = false;
 
    private $comment = false;
 
    private $titleFormatter;
 
    private $linkCache;
 
    private $hookRunner;
 
    private $specialPageFactory;
 
    private UserLinkRenderer $userLinkRenderer;
 
    public function __construct(
        TitleFormatter $titleFormatter,
        LinkCache $linkCache,
        SpecialPageFactory $specialPageFactory,
        HookContainer $hookContainer,
        TempUserConfig $tempUserConfig,
        TempUserDetailsLookup $tempUserDetailsLookup,
        UserIdentityLookup $userIdentityLookup,
        UserNameUtils $userNameUtils,
        ServiceOptions $options
    ) {
        $options->assertRequiredOptions( self::CONSTRUCTOR_OPTIONS );
        $this->comment = $options->get( 'renderForComment' );
 
        $this->titleFormatter = $titleFormatter;
        $this->linkCache = $linkCache;
        $this->specialPageFactory = $specialPageFactory;
        $this->hookRunner = new HookRunner( $hookContainer );
        $this->userLinkRenderer = new UserLinkRenderer(
            $hookContainer,
            $tempUserConfig,
            $specialPageFactory,
            $this,
            $tempUserDetailsLookup,
            $userIdentityLookup,
            $userNameUtils
        );
    }
 
    public function setForceArticlePath( $force ) {
        $this->forceArticlePath = $force;
    }
 
    public function getForceArticlePath() {
        return $this->forceArticlePath;
    }
 
    public function setExpandURLs( $expand ) {
        $this->expandUrls = $expand;
    }
 
    public function getExpandURLs() {
        return $this->expandUrls;
    }
 
    public function isForComment(): bool {
        // This option only exists to power a hack in Wikibase's onHtmlPageLinkRendererEnd hook.
        return $this->comment;
    }
 
    public function makeLink(
        $target, $text = null, array $extraAttribs = [], array $query = []
    ) {
        Assert::parameterType( [ LinkTarget::class, PageReference::class ], $target, '$target' );
        if ( $this->castToTitle( $target )->isKnown() ) {
            return $this->makeKnownLink( $target, $text, $extraAttribs, $query );
        } else {
            return $this->makeBrokenLink( $target, $text, $extraAttribs, $query );
        }
    }
 
    private function runBeginHook( $target, &$text, array &$extraAttribs, array &$query ) {
        $ret = null;
        if ( !$this->hookRunner->onHtmlPageLinkRendererBegin(
            // @phan-suppress-next-line PhanTypeMismatchArgument Type mismatch on pass-by-ref args
            $this, $this->castToTitle( $target ), $text, $extraAttribs, $query, $ret )
        ) {
            return $ret;
        }
    }
 
    public function makePreloadedLink(
        $target, $text = null, $classes = [], array $extraAttribs = [], array $query = []
    ) {
        Assert::parameterType( [ LinkTarget::class, PageReference::class ], $target, '$target' );
 
        // Run begin hook
        $ret = $this->runBeginHook( $target, $text, $extraAttribs, $query );
        if ( $ret !== null ) {
            return $ret;
        }
        $target = $this->normalizeTarget( $target );
        $url = $this->getLinkURL( $target, $query );
        // Define empty attributes here for consistent order in the output
        $attribs = [ 'href' => null, 'class' => [], 'title' => null ];
 
        $prefixedText = $this->titleFormatter->getPrefixedText( $target );
        if ( $prefixedText !== '' ) {
            $attribs['title'] = $prefixedText;
        }
 
        $attribs = array_merge( $attribs, $extraAttribs, [ 'href' => $url ] );
 
        Html::addClass( $classes, Html::expandClassList( $extraAttribs['class'] ?? [] ) );
        // Stringify attributes for hook compatibility
        $attribs['class'] = Html::expandClassList( $classes );
 
        $text ??= $this->getLinkText( $target );
 
        return $this->buildAElement( $target, $text, $attribs, true );
    }
 
    public function makeKnownLink(
        $target, $text = null, array $extraAttribs = [], array $query = []
    ) {
        Assert::parameterType( [ LinkTarget::class, PageReference::class ], $target, '$target' );
        if ( $target instanceof LinkTarget ) {
            $isExternal = $target->isExternal();
        } else {
            // $target instanceof PageReference
            // treat all PageReferences as local for now
            $isExternal = false;
        }
        $classes = [];
        if ( $isExternal ) {
            $classes[] = 'extiw';
        }
        $colour = $this->getLinkClasses( $target, $this->isDefaultLinkCaption( $target, $text ) );
        if ( $colour !== '' ) {
            $classes[] = $colour;
        }
 
        return $this->makePreloadedLink(
            $target,
            $text,
            $classes,
            $extraAttribs,
            $query
        );
    }
 
    public function makeBrokenLink(
        $target, $text = null, array $extraAttribs = [], array $query = []
    ) {
        Assert::parameterType( [ LinkTarget::class, PageReference::class ], $target, '$target' );
        // Run legacy hook
        $ret = $this->runBeginHook( $target, $text, $extraAttribs, $query );
        if ( $ret !== null ) {
            return $ret;
        }
 
        if ( $target instanceof LinkTarget ) {
            # We don't want to include fragments for broken links, because they
            # generally make no sense.
            if ( $target->hasFragment() ) {
                $target = $target->createFragmentTarget( '' );
            }
        }
        $target = $this->normalizeTarget( $target );
 
        if ( !isset( $query['action'] ) && $target->getNamespace() !== NS_SPECIAL ) {
            $query['action'] = 'edit';
            $query['redlink'] = '1';
        }
 
        $url = $this->getLinkURL( $target, $query );
        $classes = rtrim( 'new ' . $this->getLinkClasses( $target, $this->isDefaultLinkCaption( $target, $text ) ) );
        // Define empty attributes here for consistent order in the output
        $attribs = [ 'href' => null, 'class' => $classes, 'title' => null ];
 
        $prefixedText = $this->titleFormatter->getPrefixedText( $target );
        if ( $prefixedText !== '' ) {
            // This ends up in parser cache!
            $attribs['title'] = wfMessage( 'red-link-title', $prefixedText )
                ->inContentLanguage()
                ->text();
        }
 
        $attribs = array_merge( $attribs, $extraAttribs, [ 'href' => $url ] );
 
        Html::addClass( $attribs['class'], 'new' );
        // Stringify attributes for hook compatibility
        $attribs['class'] = Html::expandClassList( $attribs['class'] ?? [] );
 
        $text ??= $this->getLinkText( $target );
 
        return $this->buildAElement( $target, $text, $attribs, false );
    }
 
    public function makeExternalLink(
        string $url, $text, $title, $linktype = '', $attribs = []
    ) {
        $attribs['class'] ??= [];
        Html::addClass( $attribs['class'], 'external' );
        if ( $linktype ) {
            Html::addClass( $attribs['class'], $linktype );
        }
        // Stringify attributes for hook compatibility
        $attribs['class'] = Html::expandClassList( $attribs['class'] );
 
        if ( $text instanceof Message ) {
            $text = $text->escaped();
        } else {
            $text = HtmlArmor::getHtml( $text );
            // Tell phan that $text is non-null after ::getHtml()
            '@phan-var string $text';
        }
 
        $newRel = Parser::getExternalLinkRel( $url, $title );
        if ( $newRel !== null ) {
            $attribs['rel'] ??= [];
            Html::addClass( $attribs['rel'], $newRel );
            $attribs['rel'] = Html::expandClassList( $attribs['rel'] );
        }
        $link = '';
        $success = $this->hookRunner->onLinkerMakeExternalLink(
            $url, $text, $link, $attribs, $linktype );
        if ( !$success ) {
            wfDebug( "Hook LinkerMakeExternalLink changed the output of link "
                . "with url {$url} and text {$text} to {$link}" );
            return $link;
        }
        $attribs['href'] = $url;
        return Html::rawElement( 'a', $attribs, $text );
    }
 
    public function makeRedirectHeader(
        Language $lang, Title $target,
        bool $forceKnown = false, bool $addLinkTag = false
    ) {
        $html = '<ul class="redirectText">';
        if ( $forceKnown ) {
            $link = $this->makeKnownLink(
                $target,
                $target->getFullText(),
                [],
                // Make sure wiki page redirects are not followed
                $target->isRedirect() ? [ 'redirect' => 'no' ] : []
            );
        } else {
            $link = $this->makeLink(
                $target,
                $target->getFullText(),
                [],
                // Make sure wiki page redirects are not followed
                $target->isRedirect() ? [ 'redirect' => 'no' ] : []
            );
        }
 
        $redirectToText = wfMessage( 'redirectto' )->inLanguage( $lang )->escaped();
        $linkTag = '';
        if ( $addLinkTag ) {
            $linkTag = Html::rawElement( 'link', [
                'rel' => 'mw:PageProp/redirect',
                'href' => $this->getLinkURL( $this->normalizeTarget( $target ) ),
            ] );
        }
 
        return Html::rawElement(
            'div', [ 'class' => 'redirectMsg' ],
            Html::rawElement( 'p', [], $redirectToText ) .
            Html::rawElement( 'ul', [ 'class' => 'redirectText' ],
                Html::rawElement( 'li', [], $link ) )
        ) . $linkTag;
    }
 
    public function makeUserLink(
        UserIdentity $targetUser,
        IContextSource $context,
        ?string $altUserName = null,
        array $attributes = []
    ): string {
        return $this->userLinkRenderer->userLink(
            $targetUser, $context, $altUserName, $attributes
        );
    }
 
    private function buildAElement( $target, $text, array $attribs, $isKnown ) {
        $ret = null;
        if ( !$this->hookRunner->onHtmlPageLinkRendererEnd(
            // @phan-suppress-next-line PhanTypeMismatchArgument Type mismatch on pass-by-ref args
            $this, $this->castToLinkTarget( $target ), $isKnown, $text, $attribs, $ret )
        ) {
            return $ret;
        }
 
        return Html::rawElement( 'a', $attribs, HtmlArmor::getHtml( $text ) );
    }
 
    private function getLinkText( $target ) {
        $prefixedText = $this->titleFormatter->getPrefixedText( $target );
        // If the target is just a fragment, with no title, we return the fragment
        // text.  Otherwise, we return the title text itself.
        if ( $prefixedText === '' && $target instanceof LinkTarget && $target->hasFragment() ) {
            return $target->getFragment();
        }
 
        return $prefixedText;
    }
 
    private function getLinkURL( $target, $query = [] ) {
        if ( $this->forceArticlePath ) {
            $realQuery = $query;
            $query = [];
        } else {
            $realQuery = [];
        }
        $url = $this->castToTitle( $target )->getLinkURL( $query, false, $this->expandUrls );
 
        if ( $this->forceArticlePath && $realQuery ) {
            $url = wfAppendQuery( $url, $realQuery );
        }
 
        return $url;
    }
 
    public function normalizeTarget( $target ): MWLinkTarget {
        $target = $this->castToLinkTarget( $target );
        if ( $target->getNamespace() === NS_SPECIAL && !$target->isExternal() ) {
            [ $name, $subpage ] = $this->specialPageFactory->resolveAlias(
                $target->getDBkey()
            );
            if ( $name ) {
                return new TitleValue(
                    NS_SPECIAL,
                    $this->specialPageFactory->getLocalNameFor( $name, $subpage ),
                    $target->getFragment()
                );
            }
        }
 
        return $target;
    }
 
    public function getLinkClasses( $target, bool $isDefaultCaption = false ) {
        Assert::parameterType( [ LinkTarget::class, PageReference::class ], $target, '$target' );
        $target = $this->castToLinkTarget( $target );
        // Don't call LinkCache if the target is "non-proper"
        if ( $target->isExternal() || $target->getText() === '' ) {
            return '';
        }
        $classes = $this->userLinkRenderer->getLinkClasses( $target, $isDefaultCaption );
        if ( $target->getNamespace() < 0 ) {
            return implode( ' ', $classes );
        }
        // Make sure the target is in the cache
        $id = $this->linkCache->addLinkObj( $target );
        if ( $id == 0 ) {
            // Doesn't exist
            return implode( ' ', $classes );
        }
 
        if ( $this->linkCache->getGoodLinkFieldObj( $target, 'redirect' ) ) {
            # Page is a redirect
            $classes[] = 'mw-redirect';
        }
 
        return implode( ' ', $classes );
    }
 
    private function castToTitle( $target ): Title {
        if ( $target instanceof LinkTarget ) {
            return Title::newFromLinkTarget( $target );
        }
        // $target instanceof PageReference
        return Title::newFromPageReference( $target );
    }
 
    private function castToLinkTarget( $target ): MWLinkTarget {
        if ( $target instanceof PageReference ) {
            return Title::newFromPageReference( $target );
        }
        if ( $target instanceof MWLinkTarget ) {
            return $target;
        }
        return TitleValue::newFromLinkTarget( $target );
    }
 
    public function isDefaultLinkCaption(
        LinkTarget|PageReference|null $targetPage,
        string|HtmlArmor|null $caption
    ): bool {
        // If the target page is invalid, it has no default caption
        if ( $targetPage === null ) {
            return false;
        }
        if ( $caption instanceof HtmlArmor ) {
            $caption = HtmlArmor::getHtml( $caption );
        }
        $caption ??= $this->getLinkText( $targetPage );
        $caption = html_entity_decode( strip_tags( $caption ) );
        $captionLength = mb_strlen( $caption );
 
        $prefixedTitle = $this->titleFormatter->getPrefixedText( $targetPage );
        $titleLength = mb_strlen( $prefixedTitle );
 
        if ( $captionLength > $titleLength ) {
            return false;
        }
 
        $titleSuffix = mb_substr( $prefixedTitle, -$captionLength );
        if ( $titleSuffix !== $caption ) {
            return false;
        }
 
        if ( $titleLength === $captionLength ) {
            return true;
        }
 
        $precedingChar = mb_substr( $prefixedTitle, -$captionLength - 1, 1 );
        if ( $precedingChar === ':' || $precedingChar === '/' ) {
            return true;
        }
        return false;
    }
}