wikimedia/mediawiki-core

<?php

namespace MediaWiki\CommentFormatter;

use MediaWiki\CommentStore\CommentStore;
use Traversable;
use Wikimedia\Rdbms\IResultWrapper;

/**
 * This is basically a CommentFormatter with a CommentStore dependency, allowing
 * it to retrieve comment texts directly from database result wrappers.
 *
 * @since 1.38
 */
class RowCommentFormatter extends CommentFormatter {
    /** @var CommentStore */
    private $commentStore;

    /**
     * @internal Use MediaWikiServices::getRowCommentFormatter()
     *
     * @param CommentParserFactory $commentParserFactory
     * @param CommentStore $commentStore
     */
    public function __construct(
        CommentParserFactory $commentParserFactory,
        CommentStore $commentStore
    ) {
        parent::__construct( $commentParserFactory );
        $this->commentStore = $commentStore;
    }

    /**
     * Format DB rows using a fluent interface. Pass the return value of this
     * function to CommentBatch::comments().
     *
     * Example:
     *   $comments = $rowCommentFormatter->createBatch()
     *       ->comments(
     *           $rowCommentFormatter->rows( $rows )
     *           ->commentField( 'img_comment' )
     *       )
     *       ->useBlock( true )
     *       ->execute();
     *
     * @param Traversable|array $rows
     * @return RowCommentIterator
     */
    public function rows( $rows ) {
        return new RowCommentIterator( $this->commentStore, $rows );
    }

    /**
     * Format DB rows using a parametric interface.
     *
     * @param iterable<\stdClass>|IResultWrapper $rows
     * @param string $commentKey The comment key to pass through to CommentStore,
     *   typically a legacy field name.
     * @param string|null $namespaceField The namespace field for the self-link
     *   target, or null to have no self-link target.
     * @param string|null $titleField The title field for the self-link target,
     *   or null to have no self-link target.
     * @param string|null $indexField The field to use for array keys in the
     *   result, or null to use the same keys as in the input $rows
     * @param bool $useBlock Wrap the output in standard punctuation and
     *   formatting if it's non-empty.
     * @param bool $useParentheses Wrap the output with parentheses. Has no
     *   effect if $useBlock is false.
     * @return string[] The formatted comment. The key will be the value of the
     *   index field if an index field was specified, or the key from the
     *   corresponding element of $rows if no index field was specified.
     */
    public function formatRows( $rows, $commentKey, $namespaceField = null, $titleField = null,
        $indexField = null, $useBlock = false, $useParentheses = true
    ) {
        return $this->createBatch()
            ->comments(
                $this->rows( $rows )
                ->commentKey( $commentKey )
                ->namespaceField( $namespaceField )
                ->titleField( $titleField )
                ->indexField( $indexField )
            )
            ->useBlock( $useBlock )
            ->useParentheses( $useParentheses )
            ->execute();
    }
}