UpgradeVersionCommand.php

<?php
/**
 * COmanage Match Upgrade Version Command
 *
 * Portions licensed to the University Corporation for Advanced Internet
 * Development, Inc. ("UCAID") under one or more contributor license agreements.
 * See the NOTICE file distributed with this work for additional information
 * regarding copyright ownership.
 *
 * UCAID licenses this file to you under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with the
 * License. You may obtain a copy of the License at:
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 * @link          https://www.internet2.edu/comanage COmanage Project
 * @package       match
 * @since         COmanage Match v1.2.0
 * @license       Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
 */

declare(strict_types = 1);

namespace App\Command;

use App\Application;
use Cake\Console\Arguments;
use Cake\Console\Command;
use Cake\Console\CommandRunner;
use Cake\Console\ConsoleIo;
use Cake\Console\ConsoleOptionParser;
use Cake\Utility\Security;
use \App\Command\DatabaseCommand;
use \App\Lib\Enum\PermissionEnum;

class UpgradeVersionCommand extends Command {
  // Make sure to keep this list in order so we can walk the array rather than compare
  // version strings. You must specify the 'block' parameter. If you flag a version
  // as blocking, be sure to document why.
  // In general, it should be safe to run the upgrade command multiple times (eg: if
  // a deployment is tracking develop). Any pre or post operations should either
  // operate in a "safe" way or else check if they've already been run.
  protected $versions = [
    "1.0.0" => ['block' => false],
    "1.1.0" => ['block' => false],
    "1.2.0" => ['block' => false, 'post' => 'post120']
  ];

  // ConsoleIo
  protected $io = null;

  /**
   * Register command specific options.
   *
   * @since  COmanage Match v1.2.0
   * @param  ConsoleOptionParser $parser Console Option Parser
   * @return ConsoleOptionParser         Console Option Parser
   */
  
  public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser {
    $parser->addArgument(
      'version',
      [
        'help' => __('match.cmd.arg.version'),
        'required' => false
      ]
    )->addOption(
      'forcecurrent',
      [
        'short' => 'f',
        'help' => __('match.cmd.opt.forcecurrent'),
        'boolean' => false,
        'default' => false
      ]
    )->addOption(
      'skipdatabase',
      [
        'short' => 'D',
        'help' => __('match.cmd.opt.skipdatabase'),
        'boolean' => true,
        'default' => false
      ]
    )->addOption(
      'skipvalidation',
      [
        'short' => 'X',
        'help' => __('match.cmd.opt.skipvalidation'),
        'boolean' => false,
        'default' => false
      ]
    );

    return $parser;
  }

  /**
   * Execute the Upgrade Version Command.
   *
   * @since  COmanage Match v1.0.0
   * @param  Arguments $args Command Arguments
   * @param  ConsoleIo $io   Console IO
   */
  
  public function execute(Arguments $args, ConsoleIo $io) {
    global $argv;
    
    $this->io = $io;

    // Determine the (PHP) code version (or use the one passed in)
    $targetVersion = $args->getArgument('version');

    if(!$targetVersion) {
      // Read the current release from the VERSION file
      $versionFile = CONFIG . DS . "VERSION";

      $targetVersion = rtrim(file_get_contents($versionFile));
    }

    // Pull the current database version (or use the one passed in)
    $Meta = $this->getTableLocator()->get('Meta');
    $currentVersion = $args->getOption('forcecurrent');

    if(!$currentVersion) {
      $currentVersion = $Meta->getUpgradeVersion();
    }

    $io->out(__('match.cmd.ug.current', [$currentVersion]));
    $io->out(__('match.cmd.ug.target', [$targetVersion]));

    if(!$args->getOption('skipvalidation')) {
      // Validate the version path
      try {
        $this->validateVersions($currentVersion, $targetVersion);
      }
      catch(\Exception $e) {
        $io->out($e->getMessage());
        $io->out(__('match.er.cmd.ug.fail'));
        return;
      }
    }

    // Run appropriate pre-database steps

    $fromFound = false;

    foreach($this->versions as $version => $params) {
      if($version == $currentVersion) {
        // Note we don't actually want to run the steps for $currentVersion
        $fromFound = true;
        continue;
      }

      if(!$fromFound) {
        // We haven't reached the from version yet
        continue;
      }

      if(isset($params['pre'])) {
        $fn = $params['pre'];

        $io->out(__('match.cmd.ug.post', [$fn]));
        $this->$fn();
      }

      if($version == $targetVersion) {
        // We're done
        break;
      }
    }

    if(!$args->getOption('skipdatabase')) {
      // Call database shell
      $this->executeCommand(DatabaseCommand::class);
    }

    // Run appropriate post-database steps

    $fromFound = false;

    foreach($this->versions as $version => $params) {
      if($version == $currentVersion) {
        // Note we don't actually want to run the steps for $currentVersion
        $fromFound = true;
        continue;
      }

      if(!$fromFound) {
        // We haven't reached the from version yet
        continue;
      }

      if(isset($params['post'])) {
        $fn = $params['post'];

        $io->out(__('match.cmd.ug.post', [$fn]));
        $this->$fn();
      }

      if($version == $targetVersion) {
        // We're done
        break;
      }
    }

    // Now that we're done, update the current version
    $Meta->setUpgradeVersion($targetVersion);

    $io->out(__('match.cmd.ug.ok'));

    return;
  }

  /**
   * Process post-upgrade steps for v1.2.0.
   * 
   * @since  COmanage Match v1.2.0
   */

  protected function post120() {
    // Set all Systems of Record to operate in Standard Trust Mode, which is
    // the effective behavior prior to v1.2.0.

    $this->io->out(__('match.cmd.ug.120.trust_mode'));
    $this->setNewDefault('SystemsOfRecord', 'trust_mode', 'S');
  }

  /**
   * Set a new value for all rows in a column. $value will replace any null
   * entries, but not any entries already set.
   * 
   * @since  COmanage Match v1.2.0
   * @param  string   $table  Table name, in StudlyCap format
   * @param  string   $column Column name
   * @param  string   $value  New default value
   */

  protected function setNewDefault(string $table, string $column, string $value) {
    $Table = $this->getTableLocator()->get($table);

    $Table->query()
          ->update()
          ->set([$column => $value])
          ->where(["$column IS NULL"])
          ->execute();
  }

  /**
   * Validate the requested from and to versions.
   *
   * @since  COmanage Match v1.2.0
   * @param  string   $from   "From" version (current database)
   * @param  string   $to     "To" version (current codebase)
   * @return bool             true if the requested range is valid
   * @throws InvalidArgumentException
   */

  protected function validateVersions(string $from, string $to): bool {
    // First make sure these are valid versions

    if(!array_key_exists($from, $this->versions)) {
      throw new \InvalidArgumentException(__('match.er.cmd.ug.version', [$from]));
    }

    if(!array_key_exists($to, $this->versions)) {
      throw new \InvalidArgumentException(__('match.er.cmd.ug.version', [$to]));
    }

    // If $from and $to are the same, nothing to do.

    if($from == $to) {
      throw new \InvalidArgumentException(__('match.er.cmd.ug.same'));
    }

    // Walk through the version array and check our version path

    $fromFound = false;

    foreach($this->versions as $version => $params) {
      $blocks = $params['block'];

      if($version == $from) {
        $fromFound = true;
      } elseif($version == $to) {
        if(!$fromFound) {
          // Can't downgrade ($from must preceed $to)
          throw new \InvalidArgumentException(__('match.er.cmd.ug.order'));
        } else {
          // We're good to go
          break;
        }
      } else {
        if($fromFound && $blocks) {
          // We can't pass a blocker version
          throw new \InvalidArgumentException(__('match.er.cmd.ug.blocked', [$version]));
        }
      }
    }

    return true;
  }
}