9. Troubleshooting and Notes - digitalutsc/islandora_lite_docs GitHub Wiki

Setup Debugging Tool

Install XDebug 2.9 in Islandora Playbook or Islandora playbook

Prepare: sudo apt install php7.4-dev
Git clone xdebug repo and compile:

git clone git://github.com/xdebug/xdebug.git
git checkout xdebug_2_9
phpize
./configure --enable-xdebug
sudo make install
sudo service apache2 restart

Activate xdebug by updating xdebug.ini sudo vi /etc/php/7.4/mods-available/xdebug.ini

[xdebug]
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.remote_host=10.0.2.2
xdebug.remote_handler=dbgp
xdebug.remote_port=9000
xdebug.max_nesting_level = 2000

Then, run

sudo phpenmod xdebug
sudo service apache2 restart

Outcome if things are setup properly is Xdebug version when command php --version is run:

root@islandora8:/var/www/html/xdebug# php --version
PHP 7.4.27 (cli) (built: Dec 20 2021 21:28:15) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.27, Copyright (c), by Zend Technologies
    with Xdebug v2.9.9-dev, Copyright (c) 2002-2020, by Derick Rethans

In PHPStorm

Follow steps in: https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html
Setup Remote Host connect PHP Storm to the playbook
- Make sure setup Mappings which synchronize file in playbook and local system because it's unable to set a breakpoint in Remote Host mode.
In IDE:
- Enable listening to incoming debug connections by either clicking the Start Listening for PHP Debug Connections button on the toolbar or selecting Run | Start Listening for PHP Debug Connections
- Set a breakpoint at anywhere of the code.
In Web Browser:
- Install Xdebug Browser Extension for Google Chrome(https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc) and Firefox (https://addons.mozilla.org/en-US/firefox/addon/zend-debugger-toolbar/)
- Then Enable the Debug mode, More can be found here
If the setup goes through, PHPStorm should start listening debugging connection and display Debug console windows

Checking Coding Standards with PHPCS

Below is an example workflow YAML file for checking files with PHPCS. This workflow consists of one job named "PHPCS" that uses the Checkout and Setup PHP actions and runs some commands to install and use PHPCS.

name: PHPCS Check
on: [pull_request]

jobs:
  phpcs:
    name: PHPCS
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v1

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 7.4

      - name: Install PHPCS with Drupal Coding Standards
        run: |
          composer global require drupal/coder
          composer global require drupal/coder dealerdirect/phpcodesniffer-composer-installer
      
      - name: Check PHPCS Coding Standards
        run: |
          phpcs --standard=Drupal --extensions=php,module,inc,install,test,profile,theme,css,info,txt,md,yml --ignore=node_modules,bower_components,vendor ./

Sync GitHub Repo to GitLab

An action that can be helpful in syncing GitHub repositories to GitLab is the Mirror to GitLab and run GitLab CI action. When used in a workflow, this action will mirror all GitHub commits to the GitLab repository linked in the environment variable.

The action's documentation provides an example workflow that can be used as a base for usage.

Note that a project access token should be generated rather than a personal access token. When the token is generated, a bot user with the username project_{project_id}_bot will be added to the GitLab project.

If the repository is being migrated from GitLab, it can be imported to GitHub before setting up mirroring. After being imported, GitHub Actions must be manually enabled in the repository's settings. If an import fails, the GitLab repo can still be mirrored manually.

With the action:

GITLAB_USERNAME should be set to the username of the bot.
GITLAB_HOSTNAME should be set to git.drupal.org
GITLAB_PROJECT_ID should be set to the project id, which can be found in the bot user's username.
Input parameters should be set to the URL of the project (https://git.drupalcode.org/project/{project_name}).

More Granular Instructions

Mirroring to GitLab when there is no GitLab repository: just add the action on GitHub

Mirroring to GitLab when there is no GitHub repository: import the GitLab history, add the action. Sometimes the automated import from GitLab fails, but you can still manually import it to GitHub using the command line

Adding the action:

On GitLab, navigate to your project.
Go to Settings > Access Tokens
Create a token with api, read_repository, and write_repository permissions.
On GitHub, add the token to the secrets of the github project under GITLAB_PASSWORD
On GitLab, under Project Information > Members, get the username of the bot that was just added from the token (should be project_[id]_bot where [id] is the project id).
When calling the action, set GITLAB_USERNAME to the username of the bot, GITLAB_HOSTNAME to git.drupal.org, and GITLAB_PROJECT_ID to the project id

Testing With Different Versions

A reusable workflow is set up so that we can test against different versions of PHP and Drupal while running PHP-CS.

Github Actions

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to create workflows to automate tasks such as building or testing.

The GitHub Actions documentation is located here.

Workflows

GitHub Actions workflows are YAML files that are placed in the .github/workflows directory of a repository. You can configure a workflow to be triggered upon an event, run on a schedule, or be activated manually.

A workflow consists of jobs which are made up of a set of steps that will execute on a runner. Each step can be a shell script or an action, and each step within one job will be run sequentially. Actions are applications on the GitHub Actions platform that run a frequently repeated task can prevent repetitive code in workflows. Actions written by others that are available to use can be found on the GitHub Marketplace.