ElggUpgrade.php

Go to the documentation of this file.

<?php
use Elgg\Exceptions\InvalidArgumentException as ElggInvalidArgumentException;
use Elgg\Exceptions\UnexpectedValueException as ElggUnexpectedValueException;
use Elgg\Traits\TimeUsing;
use Elgg\Upgrade\Batch;

class ElggUpgrade extends ElggObject {

    use TimeUsing;
    
    private $requiredProperties = [
        'id',
        'title',
        'description',
        'class',
    ];

    public function initializeAttributes() {
        parent::initializeAttributes();

        $this->attributes['subtype'] = 'elgg_upgrade';

        // unowned
        $this->attributes['container_guid'] = 0;
        $this->attributes['owner_guid'] = 0;
    }

    public function setCompleted(): void {
        $this->setStartTime(); // to make sure a start time is present
        $this->setCompletedTime();
        $this->is_completed = true;

        elgg_trigger_event('complete', 'upgrade', $this);
    }

    public function isCompleted(): bool {
        return (bool) $this->is_completed;
    }

    public function setID(string $id): void {
        $this->id = $id;
    }

    public function setClass(string $class): void {
        $this->class = $class;
    }

    public function isAsynchronous(): bool {
        return !is_subclass_of($this->class, \Elgg\Upgrade\SystemUpgrade::class);
    }

    public function getBatch(): Batch|false {
        try {
            $batch = _elgg_services()->upgradeLocator->getBatch($this->class, $this);
        } catch (ElggInvalidArgumentException $ex) {
            // only report error if the upgrade still needs to run
            $loglevel = $this->isCompleted() ? 'INFO' : 'ERROR';
            elgg_log($ex->getMessage(), $loglevel);
            
            return false;
        }

        // check version before shouldBeSkipped() so authors can get immediate feedback on an invalid batch.
        $version = $batch->getVersion();

        // Version must be in format yyyymmddnn
        if (preg_match('/^[0-9]{10}$/', $version) === 0) {
            elgg_log("Upgrade {$this->class} returned an invalid version: {$version}");
            return false;
        }

        return $batch;
    }

    public function setCompletedTime(int $time = null): void {
        $this->completed_time = $time ?? $this->getCurrentTime()->getTimestamp();
    }

    public function getCompletedTime(): int {
        return (int) $this->completed_time;
    }
    
    public function reset(): void {
        unset($this->is_completed);
        unset($this->completed_time);
        unset($this->processed);
        unset($this->offset);
        unset($this->start_time);
    }
    
    public function setStartTime(int $time = null): void {
        if (isset($this->start_time)) {
            return;
        }
        
        $this->start_time = $time ?? $this->getCurrentTime()->getTimestamp();
    }
    
    public function getStartTime() {
        return (int) $this->start_time;
    }

    public function save(): bool {
        if (!isset($this->is_completed)) {
            $this->is_completed = false;
        }

        foreach ($this->requiredProperties as $prop) {
            if (!$this->$prop) {
                throw new ElggUnexpectedValueException("ElggUpgrade objects must have a value for the {$prop} property.");
            }
        }

        return parent::save();
    }

    public function getDisplayName(): string {
        return elgg_echo($this->title);
    }
}