Category.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;
use MediaWiki\Page\PageIdentity;
use Wikimedia\Rdbms\ILoadBalancer;
 
class Category {
    private $mName = null;
    private $mID = null;
    private $mPage = null;
    private $mPages = null, $mSubcats = null, $mFiles = null;
 
    protected const LOAD_ONLY = 0;
    protected const LAZY_INIT_ROW = 1;
 
    public const ROW_COUNT_SMALL = 100;
 
    private $loadBalancer;
 
    private $readOnlyMode;
 
    private function __construct() {
        $services = MediaWikiServices::getInstance();
        $this->loadBalancer = $services->getDBLoadBalancer();
        $this->readOnlyMode = $services->getReadOnlyMode();
    }
 
    protected function initialize( $mode = self::LOAD_ONLY ) {
        if ( $this->mName === null && $this->mID === null ) {
            throw new MWException( __METHOD__ . ' has both names and IDs null' );
        } elseif ( $this->mID === null ) {
            $where = [ 'cat_title' => $this->mName ];
        } elseif ( $this->mName === null ) {
            $where = [ 'cat_id' => $this->mID ];
        } else {
            # Already initialized
            return true;
        }
 
        $dbr = $this->loadBalancer->getConnectionRef( DB_REPLICA );
        $row = $dbr->selectRow(
            'category',
            [ 'cat_id', 'cat_title', 'cat_pages', 'cat_subcats', 'cat_files' ],
            $where,
            __METHOD__
        );
 
        if ( !$row ) {
            # Okay, there were no contents.  Nothing to initialize.
            if ( $this->mPage ) {
                # If there is a page object but no record in the category table,
                # treat this as an empty category.
                $this->mID = false;
                $this->mName = $this->mPage->getDBkey();
                $this->mPages = 0;
                $this->mSubcats = 0;
                $this->mFiles = 0;
 
                # If the page exists, call refreshCounts to add a row for it.
                if ( $mode === self::LAZY_INIT_ROW && $this->mPage->exists() ) {
                    DeferredUpdates::addCallableUpdate( [ $this, 'refreshCounts' ] );
                }
 
                return true;
            } else {
                return false; # Fail
            }
        }
 
        $this->mID = $row->cat_id;
        $this->mName = $row->cat_title;
        $this->mPages = $row->cat_pages;
        $this->mSubcats = $row->cat_subcats;
        $this->mFiles = $row->cat_files;
 
        # (T15683) If the count is negative, then 1) it's obviously wrong
        # and should not be kept, and 2) we *probably* don't have to scan many
        # rows to obtain the correct figure, so let's risk a one-time recount.
        if ( $this->mPages < 0 || $this->mSubcats < 0 || $this->mFiles < 0 ) {
            $this->mPages = max( $this->mPages, 0 );
            $this->mSubcats = max( $this->mSubcats, 0 );
            $this->mFiles = max( $this->mFiles, 0 );
 
            if ( $mode === self::LAZY_INIT_ROW ) {
                DeferredUpdates::addCallableUpdate( [ $this, 'refreshCounts' ] );
            }
        }
 
        return true;
    }
 
    public static function newFromName( $name ) {
        $cat = new self();
        $title = Title::makeTitleSafe( NS_CATEGORY, $name );
 
        if ( !is_object( $title ) ) {
            return false;
        }
 
        $cat->mPage = $title;
        $cat->mName = $title->getDBkey();
 
        return $cat;
    }
 
    public static function newFromTitle( PageIdentity $page ): self {
        $cat = new self();
 
        $cat->mPage = $page;
        $cat->mName = $page->getDBkey();
 
        return $cat;
    }
 
    public static function newFromID( $id ) {
        $cat = new self();
        $cat->mID = intval( $id );
        return $cat;
    }
 
    public static function newFromRow( stdClass $row, ?PageIdentity $page = null ) {
        $cat = new self();
        $cat->mPage = $page;
 
        # NOTE: the row often results from a LEFT JOIN on categorylinks. This may result in
        #       all the cat_xxx fields being null, if the category page exists, but nothing
        #       was ever added to the category. This case should be treated link an empty
        #       category, if possible.
 
        if ( $row->cat_title === null ) {
            if ( $page === null ) {
                # the name is probably somewhere in the row, for example as page_title,
                # but we can't know that here...
                return false;
            } else {
                # if we have a PageIdentity object, fetch the category name from there
                $cat->mName = $page->getDBkey();
            }
 
            $cat->mID = false;
            $cat->mSubcats = 0;
            $cat->mPages = 0;
            $cat->mFiles = 0;
        } else {
            $cat->mName = $row->cat_title;
            $cat->mID = $row->cat_id;
            $cat->mSubcats = $row->cat_subcats;
            $cat->mPages = $row->cat_pages;
            $cat->mFiles = $row->cat_files;
        }
 
        return $cat;
    }
 
    public function getName() {
        return $this->getX( 'mName' );
    }
 
    public function getID() {
        return $this->getX( 'mID' );
    }
 
    public function getPageCount() {
        return $this->getX( 'mPages' );
    }
 
    public function getSubcatCount() {
        return $this->getX( 'mSubcats' );
    }
 
    public function getFileCount() {
        return $this->getX( 'mFiles' );
    }
 
    public function getPage(): ?PageIdentity {
        if ( $this->mPage ) {
            return $this->mPage;
        }
 
        if ( !$this->initialize( self::LAZY_INIT_ROW ) ) {
            return null;
        }
 
        $this->mPage = Title::makeTitleSafe( NS_CATEGORY, $this->mName );
        return $this->mPage;
    }
 
    public function getTitle() {
        return Title::castFromPageIdentity( $this->getPage() ) ?? false;
    }
 
    public function getMembers( $limit = false, $offset = '' ) {
        $dbr = $this->loadBalancer->getConnectionRef( DB_REPLICA );
 
        $conds = [ 'cl_to' => $this->getName(), 'cl_from = page_id' ];
        $options = [ 'ORDER BY' => 'cl_sortkey' ];
 
        if ( $limit ) {
            $options['LIMIT'] = $limit;
        }
 
        if ( $offset !== '' ) {
            $conds[] = 'cl_sortkey > ' . $dbr->addQuotes( $offset );
        }
 
        $result = TitleArray::newFromResult(
            $dbr->select(
                [ 'page', 'categorylinks' ],
                [ 'page_id', 'page_namespace', 'page_title', 'page_len',
                    'page_is_redirect', 'page_latest' ],
                $conds,
                __METHOD__,
                $options
            )
        );
 
        return $result;
    }
 
    private function getX( $key ) {
        if ( $this->{$key} === null && !$this->initialize( self::LAZY_INIT_ROW ) ) {
            return false;
        }
        return $this->{$key};
    }
 
    public function refreshCounts() {
        if ( $this->readOnlyMode->isReadOnly() ) {
            return false;
        }
 
        # If we have just a category name, find out whether there is an
        # existing row. Or if we have just an ID, get the name, because
        # that's what categorylinks uses.
        if ( !$this->initialize( self::LOAD_ONLY ) ) {
            return false;
        }
 
        $dbw = $this->loadBalancer->getConnectionRef( DB_PRIMARY );
        # Avoid excess contention on the same category (T162121)
        $name = __METHOD__ . ':' . md5( $this->mName );
        $scopedLock = $dbw->getScopedLockAndFlush( $name, __METHOD__, 0 );
        if ( !$scopedLock ) {
            return false;
        }
 
        $dbw->startAtomic( __METHOD__ );
 
        // Lock the `category` row before locking `categorylinks` rows to try
        // to avoid deadlocks with LinksDeletionUpdate (T195397)
        $dbw->lockForUpdate( 'category', [ 'cat_title' => $this->mName ], __METHOD__ );
 
        // Lock all the `categorylinks` records and gaps for this category;
        // this is a separate query due to postgres limitations
        $dbw->selectRowCount(
            [ 'categorylinks', 'page' ],
            '*',
            [ 'cl_to' => $this->mName, 'page_id = cl_from' ],
            __METHOD__,
            [ 'LOCK IN SHARE MODE' ]
        );
        // Get the aggregate `categorylinks` row counts for this category
        $catCond = $dbw->conditional( [ 'page_namespace' => NS_CATEGORY ], '1', 'NULL' );
        $fileCond = $dbw->conditional( [ 'page_namespace' => NS_FILE ], '1', 'NULL' );
        $result = $dbw->selectRow(
            [ 'categorylinks', 'page' ],
            [
                'pages' => 'COUNT(*)',
                'subcats' => "COUNT($catCond)",
                'files' => "COUNT($fileCond)"
            ],
            [ 'cl_to' => $this->mName, 'page_id = cl_from' ],
            __METHOD__
        );
 
        $shouldExist = $result->pages > 0 || $this->getPage()->exists();
 
        if ( $this->mID ) {
            if ( $shouldExist ) {
                # The category row already exists, so do a plain UPDATE instead
                # of INSERT...ON DUPLICATE KEY UPDATE to avoid creating a gap
                # in the cat_id sequence. The row may or may not be "affected".
                $dbw->update(
                    'category',
                    [
                        'cat_pages' => $result->pages,
                        'cat_subcats' => $result->subcats,
                        'cat_files' => $result->files
                    ],
                    [ 'cat_title' => $this->mName ],
                    __METHOD__
                );
            } else {
                # The category is empty and has no description page, delete it
                $dbw->delete(
                    'category',
                    [ 'cat_title' => $this->mName ],
                    __METHOD__
                );
                $this->mID = false;
            }
        } elseif ( $shouldExist ) {
            # The category row doesn't exist but should, so create it. Use
            # upsert in case of races.
            $dbw->upsert(
                'category',
                [
                    'cat_title' => $this->mName,
                    'cat_pages' => $result->pages,
                    'cat_subcats' => $result->subcats,
                    'cat_files' => $result->files
                ],
                'cat_title',
                [
                    'cat_pages' => $result->pages,
                    'cat_subcats' => $result->subcats,
                    'cat_files' => $result->files
                ],
                __METHOD__
            );
            // @todo: Should we update $this->mID here? Or not since Category
            // objects tend to be short lived enough to not matter?
        }
 
        $dbw->endAtomic( __METHOD__ );
 
        # Now we should update our local counts.
        $this->mPages = $result->pages;
        $this->mSubcats = $result->subcats;
        $this->mFiles = $result->files;
 
        return true;
    }
 
    public function refreshCountsIfEmpty() {
        return $this->refreshCountsIfSmall( 0 );
    }
 
    public function refreshCountsIfSmall( $maxSize = self::ROW_COUNT_SMALL ) {
        $dbw = $this->loadBalancer->getConnectionRef( DB_PRIMARY );
        $dbw->startAtomic( __METHOD__ );
 
        $typeOccurances = $dbw->selectFieldValues(
            'categorylinks',
            'cl_type',
            [ 'cl_to' => $this->getName() ],
            __METHOD__,
            [ 'LIMIT' => $maxSize + 1 ]
        );
 
        if ( !$typeOccurances ) {
            $doRefresh = true; // delete any category table entry
        } elseif ( count( $typeOccurances ) <= $maxSize ) {
            $countByType = array_count_values( $typeOccurances );
            $doRefresh = !$dbw->selectField(
                'category',
                '1',
                [
                    'cat_title' => $this->getName(),
                    'cat_pages' => $countByType['page'] ?? 0,
                    'cat_subcats' => $countByType['subcat'] ?? 0,
                    'cat_files' => $countByType['file'] ?? 0
                ],
                __METHOD__
            );
        } else {
            $doRefresh = false; // category is too big
        }
 
        $dbw->endAtomic( __METHOD__ );
 
        if ( $doRefresh ) {
            $this->refreshCounts(); // update the row
 
            return true;
        }
 
        return false;
    }
}