<?php
/**
 * @license GPL-2.0-or-later
 */

/**
 * Ties together the batch update components to provide a composable
 * method of batch updating rows in a database. To use create a class
 * implementing the RowUpdateGenerator interface and configure the
 * BatchRowIterator and BatchRowWriter for access to the correct table.
 * The components will handle reading, writing, and waiting for replica DBs
 * while the generator implementation handles generating update arrays
 * for singular rows.
 *
 * Instantiate:
 *   $updater = new BatchRowUpdate(
 *       new BatchRowIterator( $dbr, 'some_table', 'primary_key_column', 500 ),
 *       new BatchRowWriter( $dbw, 'some_table', 'clusterName' ),
 *       new MyImplementationOfRowUpdateGenerator
 *   );
 *
 * Run:
 *   $updater->execute();
 *
 * An example maintenance script utilizing the BatchRowUpdate can be
 * located in the Echo extension file maintenance/updateSchema.php
 *
 * @ingroup Maintenance
 */
class BatchRowUpdate {
	/**
	 * @var BatchRowIterator Iterator that returns an array of
	 *  database rows
	 */
	protected $reader;

	/**
	 * @var BatchRowWriter Writer capable of pushing row updates
	 *  to the database
	 */
	protected $writer;

	/**
	 * @var RowUpdateGenerator Generates single row updates
	 *  based on the rows content
	 */
	protected $generator;

	/**
	 * @var callable Output callback
	 */
	protected $output;

	/**
	 * @param BatchRowIterator $reader Iterator that returns an
	 *  array of database rows
	 * @param BatchRowWriter $writer Writer capable of pushing
	 *  row updates to the database
	 * @param RowUpdateGenerator $generator Generates single row updates
	 *  based on the rows content
	 */
	public function __construct(
		BatchRowIterator $reader, BatchRowWriter $writer, RowUpdateGenerator $generator
	) {
		$this->reader = $reader;
		$this->writer = $writer;
		$this->generator = $generator;
		$this->output = static function ( $text ) {
		}; // nop
	}

	/**
	 * Runs the batch update process
	 */
	public function execute() {
		foreach ( $this->reader as $rows ) {
			$updates = [];
			foreach ( $rows as $row ) {
				$update = $this->generator->update( $row );
				if ( $update ) {
					$updates[] = [
						'primaryKey' => $this->reader->extractPrimaryKeys( $row ),
						'changes' => $update,
					];
				}
			}

			if ( $updates ) {
				$this->output( "Processing " . count( $updates ) . " rows\n" );
				$this->writer->write( $updates );
			}
		}

		$this->output( "Completed\n" );
	}

	/**
	 * Accepts a callable which will receive a single parameter
	 * containing string status updates
	 *
	 * @param callable $output A callback taking a single string
	 *  parameter to output
	 */
	public function setOutput( callable $output ) {
		$this->output = $output;
	}

	/**
	 * Write out a status update
	 *
	 * @param string $text The value to print
	 */
	protected function output( $text ) {
		( $this->output )( $text );
	}
}