Prepare your Developer Portal for the update for Drupal 10

Guidance on how to prepare your Developer Portal site from Drupal 9 to Drupal 10.

If your Developer Portal contains custom modules and themes that are written by yourself or downloaded from elsewhere, ensure that they are Drupal 10 compatible before you start the upgrade process. This action aims toward a seamless IBM® API Connect upgrade experience. To find more information about your modules and themes compatibility, download the Upgrade Status module available here.

Note: Before you start the upgrade, check the status of your modules and themes and if they are in use. Remove the ones that you do not use.

Installing the Upgrade Status module

  1. Log in to your Developer Portal as the administrator.
  2. If the administrator dashboard is not displayed, click Manage to display it.
  3. Install the Upgrade Status module. For more information about how to install the Upgrade Status, see Installing custom modules.
  4. When you finish your Upgrade Status installment, click Admin > Reports > Upgrade-status.

  5. The DRUPAL CORE AND HOSTING ENVIRONMENT section can be ignored. This area is managed by IBM API Connect and gets resolved when you upgrade.
    Note: Your custom modules and themes must be PHP 8.1 compatible before you upgrade to Drupal 10, and you are responsible for doing the upgrade.
  6. The list of projects further on the page are the ones that your Upgrade Status believes are not compatible with Drupal 10. These projects are categorized into sections, for example: REMOVE, UPDATE, COLLABORATE WITH MAINTAINERS.

    When you upgrade IBM API Connect, the Drupal 10 compatibility is automatically given to the modules and themes that you have not created or installed manually.

  7. If you find your custom modules and themes there, you can scan them to reveal what changes are needed to make them Drupal 10 compatible. For instance, the following image demonstrates the process of scanning an installed custom module, named custom_icons.

  8. Select your custom modules and themes and then click Scan selected. When completed, if your custom module or theme requires changes, you see a link on the row of them.
    Note: For Upgrade Status to identify all of the Drupal 10 compatibility issues in your custom modules and themes, you must have them enabled before scanning it.

  9. Click export as HTML to see a clear view.

Upgrading your module to be Drupal 10 compatible

This module is an example of how you can read the report and fix your code to be compatible with Drupal 10.

  1. The report shows that drupal_get_path() is deprecated, and the code must be changed to use the newer function getPath(). The following examples demonstrate the change to the newer extension type-specific version.

    Before

     $name = preg_replace("/[^A-Za-z0-9]/", '', $returnValue);
      $returnValue = Url::fromUri('internal:/' . drupal_get_path('module', 'custom_icons') . '/images/' . _custom_image_getRandomImageName($name))
        ->toString();

    After

    $name = preg_replace("/[^A-Za-z0-9]/", '', $returnValue);
      $iconPath = \Drupal::service('extension.list.module')->getPath('custom_icons');
      $returnValue = Url::fromUri('internal:/' . $iconPath . '/images/' . _custom_image_getRandomImageName($name))
        ->toString();
  2. Add the new version into the info.yml file.
  3. Drupal/Core/Extension/Extension List is still present in Drupal 8 and Drupal 9, so you can keep them, and add on support for Drupal 10.
  4. Modify the version number when you make a new change to the module as seen in the following example.

    Before

     name: 'IBM APIC Portal - custom icons'
    type: module
    description: 'IBM API Connect Developer Portal tutorial - Example of custom product icons'
    package: 'Custom'
    core_version_requirement: ^8 || ^9
    version: 1.0.1
    project: 'custom_icons'
    dependencies:
      - ibm_apim

    After

    name: 'IBM APIC Portal - custom icons'
    type: module
    description: 'IBM API Connect Developer Portal tutorial - Example of custom product icons'
    package: 'Custom'
    core_version_requirement: ^8 || ^9 || ^10
    version: 1.0.2
    project: 'custom_icons'
    dependencies:
      - ibm_apim

Import your module into your Developer Portal

Import the module by using the Developer Portal Toolkit CLI. For more information about how to use the Developer Portal CLI, see Getting started with the Portal CLI commands.

For example,
❯ apic login -s $SERVER -r provider/default-idp-2 -u steve
Warning: Using default toolkit credentials.
Enter your API Connect credentials
Password?
Logged into api.fyre-ci-134466-master.fyre.ibm.com successfully

❯ apic -s $SERVER -m portaladmin custom-module:create-import -o ibm -c api-connect-catalog-2 /tmp/custom_icons.zip
Loading File (Large files may take a while)...

201 CREATED - Task ID: wp5fhmm9l74pmkw1

Response Code - 202:

Message(s) -
The status of this task is: QUEUED

Response Code - 202:

Message(s) -
The status of this task is: RUNNING

Response Code - 200:

Message(s) -
2023-02-27 14:39:38: CLI task (custom_module:import) starting.
2023-02-27 14:39:40: Deleting existing custom module /var/aegir/platforms/devportal-9.x-10.0.5.2-20230105-1720/sites/ibm.api-connect-catalog-2.portal.fyre-ci-134466-master.fyre.ibm.com/modules/custom_icons
2023-02-27 14:39:40: Importing custom module custom_icons
2023-02-27 14:40:25: CLI task (custom_module:import) completed successfully.

Alternatively, import your updated module by installing it again using the Developer Portal UI. For more information about how to install custom modules, see Installing custom modules.

Verifying that your module is Drupal 10 compatible

The updated module is now imported into the Developer Portal. Return to the Upgrade Status report page to rescan the module. When it becomes compatible with Drupal 10, it appears at the end of the page.

Results

You used the Upgrade Status module to identify and fix the Drupal 10 compatibility problems with your custom modules and themes. However, this process might not cover everything that you need to be ready for the upgrade to Drupal 10. Drupal 10 requires PHP 8.1, so you might need to change your custom modules and themes to support it. Remember to keep your custom modules and themes up to date, and to remove deprecated code within your own written custom modules and themes.