wiki.techinc.nl/includes/user/UserSelectQueryBuilder.php

<?php
/**
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 * http://www.gnu.org/copyleft/gpl.html
 *
 * @file
 */

namespace MediaWiki\User;

use Iterator;
use MediaWiki\Block\HideUserUtils;
use MediaWiki\User\TempUser\TempUserConfig;
use Wikimedia\Assert\Assert;
use Wikimedia\Assert\PreconditionException;
use Wikimedia\Rdbms\IExpression;
use Wikimedia\Rdbms\IReadableDatabase;
use Wikimedia\Rdbms\LikeValue;
use Wikimedia\Rdbms\SelectQueryBuilder;

class UserSelectQueryBuilder extends SelectQueryBuilder {

	/** @var ActorStore */
	private $actorStore;
	private TempUserConfig $tempUserConfig;
	private HideUserUtils $hideUserUtils;

	private bool $userJoined = false;

	/**
	 * @internal
	 * @param IReadableDatabase $db
	 * @param ActorStore $actorStore
	 * @param TempUserConfig $tempUserConfig
	 */
	public function __construct(
		IReadableDatabase $db,
		ActorStore $actorStore,
		TempUserConfig $tempUserConfig,
		HideUserUtils $hideUserUtils
	) {
		parent::__construct( $db );

		$this->actorStore = $actorStore;
		$this->tempUserConfig = $tempUserConfig;
		$this->hideUserUtils = $hideUserUtils;
		$this->table( 'actor' );
	}

	/**
	 * Find by provided user ids.
	 *
	 * @param int|int[] $userIds
	 * @return UserSelectQueryBuilder
	 */
	public function whereUserIds( $userIds ): self {
		Assert::parameterType( [ 'integer', 'array' ], $userIds, '$userIds' );
		$this->conds( [ 'actor_user' => $userIds ] );
		return $this;
	}

	/**
	 * Find by provided user ids.
	 * @deprecated since 1.37, use whereUserIds instead
	 * @param int|int[] $userIds
	 * @return UserSelectQueryBuilder
	 */
	public function userIds( $userIds ): self {
		return $this->whereUserIds( $userIds );
	}

	/**
	 * Find by provided user names.
	 *
	 * @param string|string[] $userNames
	 * @return UserSelectQueryBuilder
	 */
	public function whereUserNames( $userNames ): self {
		Assert::parameterType( [ 'string', 'array' ], $userNames, '$userIds' );
		$userNames = array_map( function ( $name ) {
			return $this->actorStore->normalizeUserName( (string)$name );
		}, (array)$userNames );
		$this->conds( [ 'actor_name' => $userNames ] );
		return $this;
	}

	/**
	 * Find by provided user names.
	 * @deprecated since 1.37, use whereUserNames instead
	 * @param string|string[] $userNames
	 * @return UserSelectQueryBuilder
	 */
	public function userNames( $userNames ): self {
		return $this->whereUserNames( $userNames );
	}

	/**
	 * Find users with names starting from the provided prefix.
	 *
	 * @note this could produce a huge number of results, like User00000 ... User99999,
	 * so you must set a limit when using this condition.
	 *
	 * @param string $prefix
	 * @return UserSelectQueryBuilder
	 */
	public function whereUserNamePrefix( string $prefix ): self {
		if ( !isset( $this->options['LIMIT'] ) ) {
			throw new PreconditionException( 'Must set a limit when using a user name prefix' );
		}
		$this->conds(
			$this->db->expr( 'actor_name', IExpression::LIKE, new LikeValue( $prefix, $this->db->anyString() ) )
		);
		return $this;
	}

	/**
	 * Find users with names starting from the provided prefix.
	 *
	 * @note this could produce a huge number of results, like User00000 ... User99999,
	 * so you must set a limit when using this condition.
	 * @deprecated since 1.37 use whereUserNamePrefix instead
	 * @param string $prefix
	 * @return UserSelectQueryBuilder
	 */
	public function userNamePrefix( string $prefix ): self {
		return $this->whereUserNamePrefix( $prefix );
	}

	/**
	 * Find registered users who registered
	 *
	 * @param string $timestamp
	 * @param bool $direction Direction flag (if true, user_registration must be before $timestamp)
	 * @since 1.42
	 * @return UserSelectQueryBuilder
	 */
	public function whereRegisteredTimestamp( string $timestamp, bool $direction ): self {
		if ( !$this->userJoined ) {
			$this->join( 'user', null, [ "actor_user=user_id" ] );
			$this->userJoined = true;
		}

		$this->conds(
			$this->db->expr( 'user_registration', ( $direction ? '<' : '>' ), $this->db->timestamp( $timestamp ) )
		);
		return $this;
	}

	/**
	 * Order results by name in $direction
	 *
	 * @param string $dir one of self::SORT_ASC or self::SORT_DESC
	 * @return UserSelectQueryBuilder
	 */
	public function orderByName( string $dir = self::SORT_ASC ): self {
		$this->orderBy( 'actor_name', $dir );
		return $this;
	}

	/**
	 * Order results by user id.
	 *
	 * @param string $dir one of self::SORT_ASC or self::SORT_DESC
	 * @return UserSelectQueryBuilder
	 */
	public function orderByUserId( string $dir = self::SORT_ASC ): self {
		$this->orderBy( 'actor_user', $dir );
		return $this;
	}

	/**
	 * Only return registered users.
	 *
	 * @return UserSelectQueryBuilder
	 */
	public function registered(): self {
		$this->conds( $this->db->expr( 'actor_user', '!=', null ) );
		return $this;
	}

	/**
	 * Only return anonymous users.
	 *
	 * @return UserSelectQueryBuilder
	 */
	public function anon(): self {
		$this->conds( [ 'actor_user' => null ] );
		return $this;
	}

	/**
	 * Only return named users.
	 *
	 * @return UserSelectQueryBuilder
	 */
	public function named(): self {
		if ( !$this->tempUserConfig->isKnown() ) {
			// nothing to do: getMatchCondition throws if temp accounts aren't known
			return $this;
		}
		$this->conds( $this->tempUserConfig->getMatchCondition( $this->db, 'actor_name', IExpression::NOT_LIKE ) );
		return $this;
	}

	/**
	 * Only return temp users
	 *
	 * @return UserSelectQueryBuilder
	 */
	public function temp(): self {
		if ( !$this->tempUserConfig->isKnown() ) {
			// nothing to do: getMatchCondition throws if temp accounts aren't known
			return $this;
		}
		$this->conds( $this->tempUserConfig->getMatchCondition( $this->db, 'actor_name', IExpression::LIKE ) );
		return $this;
	}

	/**
	 * Filter based on user hidden status
	 *
	 * @since 1.38
	 * @param bool $hidden True - only hidden users, false - no hidden users
	 * @return $this
	 */
	public function hidden( bool $hidden ): self {
		$this->conds( $this->hideUserUtils->getExpression(
			$this->db,
			'actor_user',
			$hidden ? HideUserUtils::HIDDEN_USERS : HideUserUtils::SHOWN_USERS
		) );
		return $this;
	}

	/**
	 * Fetch a single UserIdentity that matches specified criteria.
	 *
	 * @return UserIdentity|null
	 */
	public function fetchUserIdentity(): ?UserIdentity {
		$this->fields( [ 'actor_id', 'actor_name', 'actor_user' ] );
		$row = $this->fetchRow();
		if ( !$row ) {
			return null;
		}
		return $this->actorStore->newActorFromRow( $row );
	}

	/**
	 * Fetch UserIdentities for the specified query.
	 *
	 * @return Iterator<UserIdentity>
	 */
	public function fetchUserIdentities(): Iterator {
		$this->fields( [ 'actor_id', 'actor_name', 'actor_user' ] );

		$result = $this->fetchResultSet();
		foreach ( $result as $row ) {
			yield $this->actorStore->newActorFromRow( $row );
		}
		$result->free();
	}

	/**
	 * Returns an array of user names matching the query.
	 *
	 * @return string[]
	 */
	public function fetchUserNames(): array {
		$this->field( 'actor_name' );
		return $this->fetchFieldValues();
	}
}