PrestaShop update debug regex not compatible with supplied defines_custom.inc.php

Problem

Symptom 1: Unable to toggle debug mode from the back-office. An error is thrown. Permissions are set correctly.
or
Symptom 2: The toggle switch shows debug is OFF but the top shows debug is ON.

Error: Could not find whether debug mode is enabled. Make sure that the correct permissions are set on the file /var/www/html/app/../config/defines.inc.php

This problem has been reported on two occasions.

https://github.com/PrestaShop/PrestaShop/issues/30773
https://github.com/PrestaShop/PrestaShop/issues/26400

Diagnosis

This repo provides PrestaShop a defines_custom.inc.php. A boolean casted getenv function is used to define the PS_MODE_DEV constant. PrestaShop validates this file by using a regex which does not match this format. PrestaShop expects a true or false value in order for this regex to match.

This PrestaShop regex does not match (bool) getenv('PS_DEV_MODE')

# src/Adapter/Debug/DebugMode.php
private function updateDebugModeValueInCustomFile($value)
    {
        ...
        if (!preg_match('/define\(\'_PS_MODE_DEV_\', ([a-zA-Z]+)\);/Ui', $cleanedFileContent)) {
        ....
    }

Solution

Go into config/defines_custom.inc.php and replace (bool) getenv('PS_DEV_MODE') with true or false

Start with src/Adapter/Debug/DebugMode.php, especially updateDebugModeValueInCustomFile(), and compare its validation with config/defines_custom.inc.php. Reproduce the back-office debug toggle in the supplied Docker setup and verify that the reported error is gone and the displayed debug state matches the setting.