MessageGroups.php

<?php
declare( strict_types = 1 );
 
namespace MediaWiki\Extension\Translate\MessageGroupProcessing;
 
use AggregateMessageGroup;
use AggregateMessageGroupLoader;
use CachedMessageGroupLoader;
use DependencyWrapper;
use InvalidArgumentException;
use MediaWiki\Extension\Translate\MessageProcessing\StringMatcher;
use MediaWiki\Extension\Translate\Services;
use MediaWiki\Extension\Translate\Utilities\Utilities;
use MediaWiki\MediaWikiServices;
use MessageGroup;
use MessageGroupBase;
use MessageGroupLoader;
use MessageHandle;
use RuntimeException;
use Title;
use TranslateMetadata;
use WANObjectCache;
 
class MessageGroups {
    private $groups;
    private $groupLoaders;
    private $cache;
 
    private const CACHE_VERSION = 4;
 
    protected function init(): void {
        if ( is_array( $this->groups ) ) {
            return; // groups already initialized
        }
 
        $value = $this->getCachedGroupDefinitions();
        $groups = $value['cc'];
 
        foreach ( $this->getGroupLoaders() as $loader ) {
            $groups += $loader->getGroups();
        }
        $this->initGroupsFromDefinitions( $groups );
    }
 
    protected function getCachedGroupDefinitions( $recache = false ): array {
        global $wgAutoloadClasses;
 
        $regenerator = function () {
            global $wgAutoloadClasses;
 
            $groups = $deps = $autoload = [];
            // This constructs the list of all groups from multiple different sources.
            // When possible, a cache dependency is created to automatically recreate
            // the cache when configuration changes. Currently used by other extensions
            // such as Banner Messages and test cases to load message groups.
            Services::getInstance()->getHookRunner()
                ->onTranslatePostInitGroups( $groups, $deps, $autoload );
            // Register autoloaders for this request, both values modified by reference
            self::appendAutoloader( $autoload, $wgAutoloadClasses );
 
            $value = [
                'ts' => wfTimestamp( TS_MW ),
                'cc' => $groups,
                'autoload' => $autoload
            ];
            $wrapper = new DependencyWrapper( $value, $deps );
            $wrapper->initialiseDeps();
 
            return $wrapper; // save the new value to cache
        };
 
        $cache = $this->getCache();
        $wrapper = $cache->getWithSetCallback(
            $this->getCacheKey(),
            $cache::TTL_DAY,
            $regenerator,
            [
                'lockTSE' => 30, // avoid stampedes (mutex)
                'checkKeys' => [ $this->getCacheKey() ],
                'touchedCallback' => static function ( $value ) {
                    return ( $value instanceof DependencyWrapper && $value->isExpired() )
                        ? time() // treat value as if it just expired (for "lockTSE")
                        : null;
                },
                'minAsOf' => $recache ? INF : $cache::MIN_TIMESTAMP_NONE, // "miss" on recache
            ]
        );
 
        $value = $wrapper->getValue();
        self::appendAutoloader( $value['autoload'], $wgAutoloadClasses );
 
        return $value;
    }
 
    protected function initGroupsFromDefinitions( array $groups ): void {
        foreach ( $groups as $id => $mixed ) {
            if ( !is_object( $mixed ) ) {
                $groups[$id] = call_user_func( $mixed, $id );
            }
        }
 
        $this->groups = $groups;
    }
 
    public function recache(): void {
        // Purge the value from all datacenters
        $cache = $this->getCache();
        $cache->touchCheckKey( $this->getCacheKey() );
 
        $this->clearProcessCache();
 
        foreach ( $this->getCacheGroupLoaders() as $cacheLoader ) {
            $cacheLoader->recache();
        }
 
        // Reload the cache value and update the local datacenter
        $value = $this->getCachedGroupDefinitions( 'recache' );
        $groups = $value['cc'];
 
        foreach ( $this->getGroupLoaders() as $loader ) {
            $groups += $loader->getGroups();
        }
 
        $this->initGroupsFromDefinitions( $groups );
    }
 
    public static function clearCache(): void {
        $self = self::singleton();
 
        $cache = $self->getCache();
        $cache->delete( $self->getCacheKey(), 1 );
 
        foreach ( $self->getCacheGroupLoaders() as $cacheLoader ) {
            $cacheLoader->clearCache();
        }
 
        $self->clearProcessCache();
    }
 
    public function clearProcessCache(): void {
        $this->groups = null;
        $this->groupLoaders = null;
    }
 
    protected function getCache(): WANObjectCache {
        if ( $this->cache === null ) {
            return MediaWikiServices::getInstance()->getMainWANObjectCache();
        } else {
            return $this->cache;
        }
    }
 
    public function setCache( ?WANObjectCache $cache = null ) {
        $this->cache = $cache;
    }
 
    public function getCacheKey(): string {
        return $this->getCache()->makeKey( 'translate-groups', 'v' . self::CACHE_VERSION );
    }
 
    protected static function appendAutoloader( array &$additions, array &$to ): void {
        foreach ( $additions as $class => $file ) {
            if ( isset( $to[$class] ) && $to[$class] !== $file ) {
                $msg = "Autoload conflict for $class: {$to[$class]} !== $file";
                trigger_error( $msg, E_USER_WARNING );
                continue;
            }
 
            $to[$class] = $file;
        }
    }
 
    protected function getGroupLoaders(): array {
        if ( $this->groupLoaders !== null ) {
            return $this->groupLoaders;
        }
 
        $cache = $this->getCache();
 
        $groupLoaderInstances = $this->groupLoaders = [];
 
        // Initialize the dependencies
        $deps = [
            'database' => Utilities::getSafeReadDB(),
            'cache' => $cache
        ];
 
        Services::getInstance()->getHookRunner()
            ->onTranslateInitGroupLoaders( $groupLoaderInstances, $deps );
 
        if ( $groupLoaderInstances === [] ) {
            return $this->groupLoaders;
        }
 
        foreach ( $groupLoaderInstances as $loader ) {
            if ( !$loader instanceof MessageGroupLoader ) {
                throw new InvalidArgumentException(
                    "MessageGroupLoader - $loader must implement the " .
                    "MessageGroupLoader interface."
                );
            }
 
            $this->groupLoaders[] = $loader;
        }
 
        return $this->groupLoaders;
    }
 
    protected function getCacheGroupLoaders(): array {
        // @phan-suppress-next-line PhanTypeMismatchReturn
        return array_filter( $this->getGroupLoaders(), static function ( $groupLoader ) {
            return $groupLoader instanceof CachedMessageGroupLoader;
        } );
    }
 
    public static function getGroup( string $id ): ?MessageGroup {
        $groups = self::singleton()->getGroups();
        $id = self::normalizeId( $id );
 
        if ( isset( $groups[$id] ) ) {
            return $groups[$id];
        }
 
        if ( $id !== '' && $id[0] === '!' ) {
            $dynamic = self::getDynamicGroups();
            if ( isset( $dynamic[$id] ) ) {
                return new $dynamic[$id];
            }
        }
 
        return null;
    }
 
    public static function normalizeId( ?string $id ): string {
        /* Translatable pages use spaces, but MW occasionally likes to
         * normalize spaces to underscores */
        $id = (string)$id;
 
        if ( str_starts_with( $id, 'page-' ) ) {
            $id = strtr( $id, '_', ' ' );
        }
 
        global $wgTranslateGroupAliases;
        if ( isset( $wgTranslateGroupAliases[$id] ) ) {
            $id = $wgTranslateGroupAliases[$id];
        }
 
        return $id;
    }
 
    public static function exists( string $id ): bool {
        return (bool)self::getGroup( $id );
    }
 
    public static function labelExists( string $name ): bool {
        $loader = AggregateMessageGroupLoader::getInstance();
        $labels = array_map( static function ( MessageGroupBase $g ) {
            return $g->getLabel();
        }, $loader->loadAggregateGroups() );
        return in_array( $name, $labels, true );
    }
 
    public static function getAllGroups(): array {
        return self::singleton()->getGroups();
    }
 
    public static function getPriority( $group ): string {
        if ( $group instanceof MessageGroup ) {
            $id = $group->getId();
        } else {
            $id = self::normalizeId( $group );
        }
 
        return Services::getInstance()->getMessageGroupReviewStore()->getGroupPriority( $id ) ?? '';
    }
 
    public static function setPriority( $group, string $priority = '' ): void {
        if ( $group instanceof MessageGroup ) {
            $id = $group->getId();
        } else {
            $id = self::normalizeId( $group );
        }
 
        $priority = $priority === '' ? null : $priority;
        Services::getInstance()->getMessageGroupReviewStore()->setGroupPriority( $id, $priority );
    }
 
    public static function isDynamic( MessageGroup $group ): bool {
        $id = $group->getId();
 
        return ( $id[0] ?? null ) === '!';
    }
 
    public static function getSharedGroups( MessageGroup $group ): array {
        // Take the first message, get a handle for it and check
        // if that message belongs to other groups. Those are the
        // parent aggregate groups. Ideally we loop over all keys,
        // but this should be enough.
        $keys = array_keys( $group->getDefinitions() );
        $title = Title::makeTitle( $group->getNamespace(), $keys[0] );
        $handle = new MessageHandle( $title );
        $ids = $handle->getGroupIds();
        foreach ( $ids as $index => $id ) {
            if ( $id === $group->getId() ) {
                unset( $ids[$index] );
                break;
            }
        }
 
        return $ids;
    }
 
    public static function getParentGroups( MessageGroup $targetGroup ): array {
        $ids = self::getSharedGroups( $targetGroup );
        if ( $ids === [] ) {
            return [];
        }
 
        $targetId = $targetGroup->getId();
 
        /* Get the group structure. We will be using this to find which
         * of our candidates are top-level groups. Prefilter it to only
         * contain aggregate groups. */
        $structure = self::getGroupStructure();
        foreach ( $structure as $index => $group ) {
            if ( $group instanceof MessageGroup ) {
                unset( $structure[$index] );
            } else {
                $structure[$index] = array_shift( $group );
            }
        }
 
        /* Now that we have all related groups, use them to find all paths
         * from top-level groups to target group with any number of subgroups
         * in between. */
        $paths = [];
 
        /* This function recursively finds paths to the target group */
        $pathFinder = static function ( &$paths, $group, $targetId, $prefix = '' )
        use ( &$pathFinder ) {
            if ( $group instanceof AggregateMessageGroup ) {
                foreach ( $group->getGroups() as $subgroup ) {
                    $subId = $subgroup->getId();
                    if ( $subId === $targetId ) {
                        $paths[] = $prefix;
                        continue;
                    }
 
                    $pathFinder( $paths, $subgroup, $targetId, "$prefix|$subId" );
                }
            }
        };
 
        // Iterate over the top-level groups only
        foreach ( $ids as $id ) {
            // First, find a top level groups
            $group = self::getGroup( $id );
 
            // Quick escape for leaf groups
            if ( !$group instanceof AggregateMessageGroup ) {
                continue;
            }
 
            foreach ( $structure as $rootGroup ) {
                if ( $rootGroup->getId() === $group->getId() ) {
                    // Yay we found a top-level group
                    $pathFinder( $paths, $rootGroup, $targetId, $id );
                    break; // No we have one or more paths appended into $paths
                }
            }
        }
 
        // And finally explode the strings
        return array_map( static function ( string $pathString ): array {
            return explode( '|', $pathString );
        }, $paths );
    }
 
    public static function singleton(): self {
        static $instance;
        if ( !$instance instanceof self ) {
            $instance = new self();
        }
 
        return $instance;
    }
 
    public function getGroups(): array {
        $this->init();
 
        return $this->groups;
    }
 
    public static function getGroupsById( array $ids, bool $skipMeta = false ): array {
        $groups = [];
        foreach ( $ids as $id ) {
            $group = self::getGroup( $id );
 
            if ( $group !== null ) {
                if ( $skipMeta && $group->isMeta() ) {
                    continue;
                } else {
                    $groups[$id] = $group;
                }
            } else {
                wfDebug( __METHOD__ . ": Invalid message group id: $id\n" );
            }
        }
 
        return $groups;
    }
 
    public static function expandWildcards( $ids ): array {
        $all = [];
 
        $ids = (array)$ids;
        foreach ( $ids as $index => $id ) {
            // Fast path, no wildcards
            if ( strcspn( $id, '*?' ) === strlen( $id ) ) {
                $g = self::getGroup( $id );
                if ( $g ) {
                    $all[] = $g->getId();
                }
                unset( $ids[$index] );
            }
        }
 
        if ( $ids === [] ) {
            return $all;
        }
 
        // Slow path for the ones with wildcards
        $matcher = new StringMatcher( '', $ids );
        foreach ( self::getAllGroups() as $id => $_ ) {
            if ( $matcher->matches( $id ) ) {
                $all[] = $id;
            }
        }
 
        return $all;
    }
 
    public static function getDynamicGroups(): array {
        return [
            '!recent' => 'RecentMessageGroup',
            '!additions' => 'RecentAdditionsMessageGroup',
            '!sandbox' => 'SandboxMessageGroup',
        ];
    }
 
    public static function getGroupsByType( string $type ): array {
        $groups = self::getAllGroups();
        foreach ( $groups as $id => $group ) {
            if ( !$group instanceof $type ) {
                unset( $groups[$id] );
            }
        }
 
        // @phan-suppress-next-line PhanTypeMismatchReturn
        return $groups;
    }
 
    public static function getGroupStructure(): array {
        $groups = self::getAllGroups();
 
        // Determine the top level groups of the tree
        $tree = $groups;
        foreach ( $groups as $id => $o ) {
            if ( !$o->exists() ) {
                unset( $groups[$id], $tree[$id] );
                continue;
            }
 
            if ( $o instanceof AggregateMessageGroup ) {
                foreach ( $o->getGroups() as $sid => $so ) {
                    unset( $tree[$sid] );
                }
            }
        }
 
        usort( $tree, [ self::class, 'groupLabelSort' ] );
 
        /* Now we have two things left in $tree array:
         * - solitaries: top-level non-aggregate message groups
         * - top-level aggregate message groups */
        foreach ( $tree as $index => $group ) {
            if ( $group instanceof AggregateMessageGroup ) {
                $tree[$index] = self::subGroups( $group );
            }
        }
 
        /* Essentially we are done now. Cyclic groups can cause part of the
         * groups not be included at all, because they have all unset each
         * other in the first loop. So now we check if there are groups left
         * over. */
        $used = [];
        array_walk_recursive(
            $tree,
            static function ( MessageGroup $group ) use ( &$used ) {
                $used[$group->getId()] = true;
            }
        );
        $unused = array_diff_key( $groups, $used );
        if ( $unused ) {
            foreach ( $unused as $index => $group ) {
                if ( !$group instanceof AggregateMessageGroup ) {
                    unset( $unused[$index] );
                }
            }
 
            // Only list the aggregate groups, other groups cannot cause cycles
            $participants = implode( ', ', array_keys( $unused ) );
            throw new RuntimeException( "Found cyclic aggregate message groups: $participants" );
        }
 
        return $tree;
    }
 
    public static function groupLabelSort( MessageGroup $a, MessageGroup $b ): int {
        $al = $a->getLabel();
        $bl = $b->getLabel();
 
        return strcasecmp( $al, $bl );
    }
 
    public static function subGroups(
        AggregateMessageGroup $parent,
        array &$childIds = [],
        string $fname = 'caller'
        ): array {
        static $recursionGuard = [];
 
        $pid = $parent->getId();
        if ( isset( $recursionGuard[$pid] ) ) {
            $tid = $pid;
            $path = [ $tid ];
            do {
                $tid = $recursionGuard[$tid];
                $path[] = $tid;
                // Until we have gone full cycle
            } while ( $tid !== $pid );
            $path = implode( ' > ', $path );
            throw new RuntimeException( "Found cyclic aggregate message groups: $path" );
        }
 
        // We don't care about the ids.
        $tree = array_values( $parent->getGroups() );
        usort( $tree, [ self::class, 'groupLabelSort' ] );
        // Expand aggregate groups (if any left) after sorting to form a tree
        foreach ( $tree as $index => $group ) {
            if ( $group instanceof AggregateMessageGroup ) {
                $sid = $group->getId();
                $recursionGuard[$pid] = $sid;
                $tree[$index] = self::subGroups( $group, $childIds, __METHOD__ );
                unset( $recursionGuard[$pid] );
 
                $childIds[$sid] = 1;
            }
        }
 
        // Parent group must be first item in the array
        array_unshift( $tree, $parent );
 
        if ( $fname !== __METHOD__ ) {
            // Move the IDs from the keys to the value for final return
            $childIds = array_values( $childIds );
        }
 
        return $tree;
    }
 
    public static function haveSingleSourceLanguage( array $groups ): string {
        $seen = '';
 
        foreach ( $groups as $group ) {
            $language = $group->getSourceLanguage();
            if ( $seen === '' ) {
                $seen = $language;
            } elseif ( $language !== $seen ) {
                return '';
            }
        }
 
        return $seen;
    }
 
    public static function isTranslatableMessage( MessageHandle $handle, string $targetLanguage ): bool {
        static $cache = [];
 
        if ( !$handle->isValid() ) {
            return false;
        }
 
        $group = $handle->getGroup();
        $groupId = $group->getId();
        $cacheKey = "$groupId:$targetLanguage";
 
        if ( !isset( $cache[$cacheKey] ) ) {
            $supportedLanguages = Utilities::getLanguageNames( 'en' );
            $inclusionList = $group->getTranslatableLanguages() ?? $supportedLanguages;
 
            $included = isset( $inclusionList[$targetLanguage] );
            $excluded = TranslateMetadata::isExcluded( $groupId, $targetLanguage );
 
            $cache[$cacheKey] = [
                'relevant' => $included && !$excluded,
                'tags' => [],
            ];
 
            $groupTags = $group->getTags();
            foreach ( [ 'ignored', 'optional' ] as $tag ) {
                if ( isset( $groupTags[$tag] ) ) {
                    foreach ( $groupTags[$tag] as $key ) {
                        // TODO: ucfirst should not be here
                        $cache[$cacheKey]['tags'][ucfirst( $key )] = true;
                    }
                }
            }
        }
 
        return $cache[$cacheKey]['relevant'] &&
            !isset( $cache[$cacheKey]['tags'][ucfirst( $handle->getKey() )] );
    }
}
 
class_alias( MessageGroups::class, 'MessageGroups' );