Application upgrade implementation with PHP Runtime

When application is upgraded to a new version, APS Controller sends REST request calling upgrade method of the top resource of the application. See example.

PHP runtime transfers this REST request to upgrade function of corresponding PHP class.

If new required properties are added to the APS type, you need to define new resource properties within the upgrade method.

At the time the upgrade function is called, existing resources still belong to the old type version, and should be retrieved using old version. Then, when we add the new property and update the resource, we need to explicitly change the type version.

To simplify this process, PHP Runtime does the following:

• Provides method getTypeByServiceId, which returns type version that resource currently uses, by its service ID.
• Replaces the type with the latest one in the updateResource method, if it’s called within upgrade method.

This enables developers to use the following simple method to add a new property to existing resources:

<?php

 require_once("aps/2/runtime.php");

/**
 * Class Globals
 * @type("http://company.com/app/globals/1.0")
 * @implements("http://aps-standard.org/types/core/application/1.0")
 */
 class globals extends \APS\ResourceBase {
    ....
      public function upgrade () {

             $apsc = \APS\Request::getController();

             $start = 0;
             do {
                 // retrieve the list of resource by old type version
                 $vpses = $apsc->getResources("implementing(".$this->getTypeByServiceId("vpses")."),limit($start,1000)");

                 foreach ($vpses as $vps) {
                     $vps->newprop = "new value";
                     // in updateResource, php runtime replaces type to new version
                     $apsc->updateResource($vps);
                 }
                 $start += 1000;
             } while (count($vpses) > 0);
      }

If a new property is added to the top resource, it should be set as in the following example:

<?php

 require_once("aps/2/runtime.php");

/**
 * Class Globals
 * @type("http://company.com/app/globals/1.0")
 * @implements("http://aps-standard.org/types/core/application/1.0")
 */
 class globals extends \APS\ResourceBase {
    ....
      public function upgrade () {
         $this->newprop = "new value";
      }

PHP Runtime will return the changed resource, and change the type to the new version.

Note

These improvements in upgrade process are added in PHP Runtime 2.0-383, 2.1-302 and 2.2-115. Use runtimeVersions annotation to require particular version.

← Operating APS Versions

Error Handling and Custom Exceptions in PHP Runtime →