wikimedia/mediawiki-core

<?php

namespace MediaWiki\CommentFormatter;

use MediaWiki\Linker\LinkTarget;
use Traversable;

/**
 * This class provides a fluent interface for formatting a batch of comments.
 *
 * @since 1.38
 */
class CommentBatch {
    /** @var CommentFormatter */
    private $formatter;
    /** @var iterable<CommentItem>|Traversable */
    private $comments;
    /** @var bool|null */
    private $useBlock;
    /** @var bool|null */
    private $useParentheses;
    /** @var LinkTarget|null */
    private $selfLinkTarget;
    /** @var bool|null */
    private $samePage;
    /** @var string|false|null */
    private $wikiId;
    /** @var bool|null */
    private $enableSectionLinks;

    /**
     * @internal Use CommentFormatter::createBatch()
     *
     * @param CommentFormatter $formatter
     */
    public function __construct( CommentFormatter $formatter ) {
        $this->formatter = $formatter;
    }

    /**
     * Set the comments to be formatted. This can be an array of CommentItem
     * objects, or it can be an iterator which generates CommentItem objects.
     *
     * Theoretically iterable should imply Traversable, but PHPStorm gives an
     * error when RowCommentIterator is passed as iterable<CommentItem>.
     *
     * @param iterable<CommentItem>|Traversable $comments
     * @return $this
     */
    public function comments( $comments ) {
        $this->comments = $comments;
        return $this;
    }

    /**
     * Specify the comments to be formatted as an array of strings. This is a
     * simplified wrapper for comments() which does not allow you to set options
     * on a per-comment basis.
     *
     * $strings must be an array -- use comments() if you want to use an iterator.
     *
     * @param string[] $strings
     * @return $this
     */
    public function strings( array $strings ) {
        $this->comments = new StringCommentIterator( $strings );
        return $this;
    }

    /**
     * Wrap each comment in standard punctuation and formatting if it's
     * non-empty. Empty comments remain empty. This causes the batch to work
     * like the old Linker::commentBlock().
     *
     * If this function is not called, the option is false.
     *
     * @param bool $useBlock
     * @return $this
     */
    public function useBlock( $useBlock = true ) {
        $this->useBlock = $useBlock;
        return $this;
    }

    /**
     * Wrap each comment with parentheses. This has no effect if the useBlock
     * option is not enabled.
     *
     * Unlike the legacy Linker::commentBlock(), this option defaults to false
     * if this method is not called, since that better preserves the fluent
     * style.
     *
     * @param bool $useParentheses
     * @return $this
     */
    public function useParentheses( $useParentheses = true ) {
        $this->useParentheses = $useParentheses;
        return $this;
    }

    /**
     * Set the title to be used for self links in the comments. If there is no
     * title specified either here or in the item, fragment links are not
     * expanded.
     *
     * @param LinkTarget $selfLinkTarget
     * @return $this
     */
    public function selfLinkTarget( LinkTarget $selfLinkTarget ) {
        $this->selfLinkTarget = $selfLinkTarget;
        return $this;
    }

    /**
     * Set the option to enable/disable section links formatted as C-style
     * comments, as used in revision comments to indicate the section which
     * was edited.
     *
     * If the method is not called, the option is true. Setting this to false
     * approximately emulates Linker::formatLinksInComment() except that HTML
     * in the input is escaped.
     *
     * @param bool $enable
     * @return $this
     */
    public function enableSectionLinks( $enable ) {
        $this->enableSectionLinks = $enable;
        return $this;
    }

    /**
     * Disable section links formatted as C-style comments, as used in revision
     * comments to indicate the section which was edited. Calling this
     * approximately emulates Linker::formatLinksInComment() except that HTML
     * in the input is escaped.
     *
     * @return $this
     */
    public function disableSectionLinks() {
        $this->enableSectionLinks = false;
        return $this;
    }

    /**
     * Set the same-page option. If this is true, section links and fragment-
     * only wikilinks are rendered with an href that is a fragment-only URL.
     * If it is false (the default), such links go to the self link title.
     *
     * This can also be set per-item using CommentItem::samePage().
     *
     * This is equivalent to $local in the old Linker methods.
     *
     * @param bool $samePage
     * @return $this
     */
    public function samePage( $samePage = true ) {
        $this->samePage = $samePage;
        return $this;
    }

    /**
     * ID of the wiki to link to (if not the local wiki), as used by WikiMap.
     * This is used to render comments which are loaded from a foreign wiki.
     * This only affects links which are syntactically internal -- it has no
     * effect on interwiki links.
     *
     * This can also be set per-item using CommentItem::wikiId().
     *
     * @param string|false|null $wikiId
     * @return $this
     */
    public function wikiId( $wikiId ) {
        $this->wikiId = $wikiId;
        return $this;
    }

    /**
     * Format the comments and produce an array of HTML fragments.
     *
     * @return string[]
     */
    public function execute() {
        return $this->formatter->formatItemsInternal(
            $this->comments,
            $this->selfLinkTarget,
            $this->samePage,
            $this->wikiId,
            $this->enableSectionLinks,
            $this->useBlock,
            $this->useParentheses
        );
    }

}