ActorMigrationBase.php

Go to the documentation of this file.

<?php
use MediaWiki\User\ActorStoreFactory;
use MediaWiki\User\UserIdentity;
use Wikimedia\IPUtils;
use Wikimedia\Rdbms\IDatabase;
 
class ActorMigrationBase {
    private $joinCache = [];
 
    private $readStage;
 
    private $writeStage;
 
    private $actorStoreFactory;
 
    private $fieldInfos;
 
    private $allowUnknown;
 
    public function __construct(
        $fieldInfos,
        $stage,
        ActorStoreFactory $actorStoreFactory,
        $options = []
    ) {
        $this->fieldInfos = $fieldInfos;
        $this->allowUnknown = $options['allowUnknown'] ?? true;
 
        $writeStage = $stage & SCHEMA_COMPAT_WRITE_MASK;
        $readStage = $stage & SCHEMA_COMPAT_READ_MASK;
        if ( $writeStage === 0 ) {
            throw new InvalidArgumentException( '$stage must include a write mode' );
        }
        if ( $readStage === 0 ) {
            throw new InvalidArgumentException( '$stage must include a read mode' );
        }
        if ( !in_array( $readStage,
            [ SCHEMA_COMPAT_READ_OLD, SCHEMA_COMPAT_READ_TEMP, SCHEMA_COMPAT_READ_NEW ] )
        ) {
            throw new InvalidArgumentException( 'Cannot read multiple schemas' );
        }
        if ( $readStage === SCHEMA_COMPAT_READ_OLD && !( $writeStage & SCHEMA_COMPAT_WRITE_OLD ) ) {
            throw new InvalidArgumentException( 'Cannot read the old schema without also writing it' );
        }
        if ( $readStage === SCHEMA_COMPAT_READ_TEMP && !( $writeStage & SCHEMA_COMPAT_WRITE_TEMP ) ) {
            throw new InvalidArgumentException( 'Cannot read the temp schema without also writing it' );
        }
        if ( $readStage === SCHEMA_COMPAT_READ_NEW && !( $writeStage & SCHEMA_COMPAT_WRITE_NEW ) ) {
            throw new InvalidArgumentException( 'Cannot read the new schema without also writing it' );
        }
        $this->readStage = $readStage;
        $this->writeStage = $writeStage;
 
        $this->actorStoreFactory = $actorStoreFactory;
    }
 
    protected function getFieldInfo( $key ) {
        if ( isset( $this->fieldInfos[$key] ) ) {
            return $this->fieldInfos[$key];
        } elseif ( $this->allowUnknown ) {
            return [];
        } else {
            throw new InvalidArgumentException( $this->getInstanceName() . ": unknown key $key" );
        }
    }
 
    protected function getInstanceName() {
        if ( ( new ReflectionClass( $this ) )->isAnonymous() ) {
            // Mostly for PHPUnit
            return self::class;
        } else {
            return static::class;
        }
    }
 
    protected function checkDeprecation( $key ) {
        $fieldInfo = $this->getFieldInfo( $key );
        if ( isset( $fieldInfo['removedVersion'] ) ) {
            $removedVersion = $fieldInfo['removedVersion'];
            $component = $fieldInfo['component'] ?? 'MediaWiki';
            throw new InvalidArgumentException(
                "Use of {$this->getInstanceName()} for '$key' was removed in $component $removedVersion"
            );
        }
        if ( isset( $fieldInfo['deprecatedVersion'] ) ) {
            $deprecatedVersion = $fieldInfo['deprecatedVersion'];
            $component = $fieldInfo['component'] ?? 'MediaWiki';
            wfDeprecated( "{$this->getInstanceName()} for '$key'", $deprecatedVersion, $component, 3 );
        }
    }
 
    public function isAnon( $field ) {
        return ( $this->readStage >= SCHEMA_COMPAT_READ_TEMP ) ? "$field IS NULL" : "$field = 0";
    }
 
    public function isNotAnon( $field ) {
        return ( $this->readStage >= SCHEMA_COMPAT_READ_TEMP ) ? "$field IS NOT NULL" : "$field != 0";
    }
 
    private function getFieldNames( $key ) {
        $fieldInfo = $this->getFieldInfo( $key );
        $textField = $fieldInfo['textField'] ?? $key . '_text';
        $actorField = $fieldInfo['actorField'] ?? substr( $key, 0, -5 ) . '_actor';
        return [ $textField, $actorField ];
    }
 
    private function getTempTableInfo( $key ) {
        $fieldInfo = $this->getFieldInfo( $key );
        return $fieldInfo['tempTable'] ?? null;
    }
 
    public function getJoin( $key ) {
        $this->checkDeprecation( $key );
 
        if ( !isset( $this->joinCache[$key] ) ) {
            $tables = [];
            $fields = [];
            $joins = [];
 
            list( $text, $actor ) = $this->getFieldNames( $key );
 
            if ( $this->readStage === SCHEMA_COMPAT_READ_OLD ) {
                $fields[$key] = $key;
                $fields[$text] = $text;
                $fields[$actor] = 'NULL';
            } elseif ( $this->readStage === SCHEMA_COMPAT_READ_TEMP ) {
                $tempTableInfo = $this->getTempTableInfo( $key );
                if ( $tempTableInfo ) {
                    $alias = "temp_$key";
                    $tables[$alias] = $tempTableInfo['table'];
                    $joins[$alias] = [ 'JOIN',
                        "{$alias}.{$tempTableInfo['pk']} = {$tempTableInfo['joinPK']}" ];
                    $joinField = "{$alias}.{$tempTableInfo['field']}";
                } else {
                    $joinField = $actor;
                }
 
                $alias = "actor_$key";
                $tables[$alias] = 'actor';
                $joins[$alias] = [ 'JOIN', "{$alias}.actor_id = {$joinField}" ];
 
                $fields[$key] = "{$alias}.actor_user";
                $fields[$text] = "{$alias}.actor_name";
                $fields[$actor] = $joinField;
            } else /* SCHEMA_COMPAT_READ_NEW */ {
                $alias = "actor_$key";
                $tables[$alias] = 'actor';
                $joins[$alias] = [ 'JOIN', "{$alias}.actor_id = {$actor}" ];
 
                $fields[$key] = "{$alias}.actor_user";
                $fields[$text] = "{$alias}.actor_name";
                $fields[$actor] = $actor;
            }
 
            $this->joinCache[$key] = [
                'tables' => $tables,
                'fields' => $fields,
                'joins' => $joins,
            ];
        }
 
        return $this->joinCache[$key];
    }
 
    public function getInsertValues( IDatabase $dbw, $key, UserIdentity $user ) {
        $this->checkDeprecation( $key );
 
        if ( $this->getTempTableInfo( $key ) ) {
            throw new InvalidArgumentException( "Must use getInsertValuesWithTempTable() for $key" );
        }
 
        list( $text, $actor ) = $this->getFieldNames( $key );
        $ret = [];
        if ( $this->writeStage & SCHEMA_COMPAT_WRITE_OLD ) {
            $ret[$key] = $user->getId();
            $ret[$text] = $user->getName();
        }
        if ( $this->writeStage & SCHEMA_COMPAT_WRITE_TEMP
            || $this->writeStage & SCHEMA_COMPAT_WRITE_NEW
        ) {
            $ret[$actor] = $this->actorStoreFactory
                ->getActorNormalization( $dbw->getDomainID() )
                ->acquireActorId( $user, $dbw );
        }
        return $ret;
    }
 
    public function getInsertValuesWithTempTable( IDatabase $dbw, $key, UserIdentity $user ) {
        $this->checkDeprecation( $key );
 
        $fieldInfo = $this->getFieldInfo( $key );
        $tempTableInfo = $fieldInfo['tempTable'] ?? null;
        if ( isset( $fieldInfo['formerTempTableVersion'] ) ) {
            wfDeprecated( __METHOD__ . " for $key",
                $fieldInfo['formerTempTableVersion'],
                $fieldInfo['component'] ?? 'MediaWiki' );
        } elseif ( !$tempTableInfo ) {
            throw new InvalidArgumentException( "Must use getInsertValues() for $key" );
        }
 
        list( $text, $actor ) = $this->getFieldNames( $key );
        $ret = [];
        $callback = null;
 
        if ( $this->writeStage & SCHEMA_COMPAT_WRITE_OLD ) {
            $ret[$key] = $user->getId();
            $ret[$text] = $user->getName();
        }
        if ( $this->writeStage & ( SCHEMA_COMPAT_WRITE_TEMP | SCHEMA_COMPAT_WRITE_NEW ) ) {
            $id = $this->actorStoreFactory
                ->getActorNormalization( $dbw->getDomainID() )
                ->acquireActorId( $user, $dbw );
 
            if ( $tempTableInfo ) {
                if ( $this->writeStage & SCHEMA_COMPAT_WRITE_TEMP ) {
                    $func = __METHOD__;
                    $callback = static function ( $pk, array $extra ) use ( $tempTableInfo, $dbw, $id, $func ) {
                        $set = [ $tempTableInfo['field'] => $id ];
                        foreach ( $tempTableInfo['extra'] as $to => $from ) {
                            if ( !array_key_exists( $from, $extra ) ) {
                                throw new InvalidArgumentException( "$func callback: \$extra[$from] is not provided" );
                            }
                            $set[$to] = $extra[$from];
                        }
                        $dbw->upsert(
                            $tempTableInfo['table'],
                            [ $tempTableInfo['pk'] => $pk ] + $set,
                            [ [ $tempTableInfo['pk'] ] ],
                            $set,
                            $func
                        );
                    };
                }
                if ( $this->writeStage & SCHEMA_COMPAT_WRITE_NEW ) {
                    $ret[$actor] = $id;
                }
            } else {
                $ret[$actor] = $id;
            }
        }
 
        if ( $callback === null ) {
            // Make a validation-only callback if there was temp table info
            if ( $tempTableInfo ) {
                $func = __METHOD__;
                $callback = static function ( $pk, array $extra ) use ( $tempTableInfo, $func ) {
                    foreach ( $tempTableInfo['extra'] as $to => $from ) {
                        if ( !array_key_exists( $from, $extra ) ) {
                            throw new InvalidArgumentException( "$func callback: \$extra[$from] is not provided" );
                        }
                    }
                };
            } else {
                $callback = static function ( $pk, array $extra ) {
                };
            }
        }
        return [ $ret, $callback ];
    }
 
    public function getWhere( IDatabase $db, $key, $users, $useId = true ) {
        $this->checkDeprecation( $key );
 
        $tables = [];
        $conds = [];
        $joins = [];
 
        if ( $users instanceof UserIdentity ) {
            $users = [ $users ];
        } elseif ( $users === null || $users === false ) {
            // DWIM
            $users = [];
        } elseif ( !is_array( $users ) ) {
            $what = is_object( $users ) ? get_class( $users ) : gettype( $users );
            throw new InvalidArgumentException(
                __METHOD__ . ": Value for \$users must be a UserIdentity or array, got $what"
            );
        }
 
        // Get information about all the passed users
        $ids = [];
        $names = [];
        $actors = [];
        foreach ( $users as $user ) {
            if ( $useId && $user->isRegistered() ) {
                $ids[] = $user->getId();
            } else {
                // make sure to use normalized form of IP for anonymous users
                $names[] = IPUtils::sanitizeIP( $user->getName() );
            }
            $actorId = $this->actorStoreFactory
                ->getActorNormalization( $db->getDomainID() )
                ->findActorId( $user, $db );
 
            if ( $actorId ) {
                $actors[] = $actorId;
            }
        }
 
        list( $text, $actor ) = $this->getFieldNames( $key );
 
        // Combine data into conditions to be ORed together
        if ( $this->readStage === SCHEMA_COMPAT_READ_NEW ) {
            if ( $actors ) {
                $conds['newactor'] = $db->makeList( [ $actor => $actors ], IDatabase::LIST_AND );
            }
        } elseif ( $this->readStage === SCHEMA_COMPAT_READ_TEMP ) {
            if ( $actors ) {
                $tempTableInfo = $this->getTempTableInfo( $key );
                if ( $tempTableInfo ) {
                    $alias = "temp_$key";
                    $tables[$alias] = $tempTableInfo['table'];
                    $joins[$alias] = [ 'JOIN',
                        "{$alias}.{$tempTableInfo['pk']} = {$tempTableInfo['joinPK']}" ];
                    $joinField = "{$alias}.{$tempTableInfo['field']}";
                } else {
                    $joinField = $actor;
                }
                $conds['actor'] = $db->makeList( [ $joinField => $actors ], IDatabase::LIST_AND );
            }
        } else {
            if ( $ids ) {
                $conds['userid'] = $db->makeList( [ $key => $ids ], IDatabase::LIST_AND );
            }
            if ( $names ) {
                $conds['username'] = $db->makeList( [ $text => $names ], IDatabase::LIST_AND );
            }
        }
 
        return [
            'tables' => $tables,
            'conds' => $conds ? $db->makeList( array_values( $conds ), IDatabase::LIST_OR ) : '1=0',
            'orconds' => $conds,
            'joins' => $joins,
        ];
    }
}