feat: add ConfigService and GlobalsRegistrar helpers

.composer-require-checker.json

@@ -14,7 +14,13 @@
     "callable",
     "iterable",
     "void",
-    "object"
+    "object",
+    "attr",
+    "xlt",
+    "OpenEMR\\Common\\Crypto\\CryptoGen",
+    "OpenEMR\\Common\\Database\\QueryUtils",
+    "OpenEMR\\Events\\Globals\\GlobalsInitializedEvent",
+    "OpenEMR\\Services\\Globals\\GlobalSetting"
   ],
   "php-core-extensions": [
     "Core",

composer.json

@@ -26,11 +26,13 @@
     "require": {
         "php": ">=8.2",
         "ext-filter": "*",
+        "symfony/event-dispatcher": "^6.4 || ^7.0",
         "symfony/http-foundation": "^6.4 || ^7.0",
         "symfony/yaml": "^6.4 || ^7.0"
     },
     "require-dev": {
         "ergebnis/composer-normalize": "^2.44",
+        "openemr/openemr": ">=8.0.0 || 8.1.0.x-dev || dev-master",
         "phpstan/phpstan": "^2.1",
         "phpunit/phpunit": "^11.0",
         "rector/rector": "^2.0",
@@ -39,6 +41,59 @@
     "suggest": {
         "google/cloud-secret-manager": "Required for gcp-secret-manager provider in _secrets block (^2.1)"
     },
+    "repositories": [
+        {
+            "type": "package",
+            "package": {
+                "name": "openemr/openemr",
+                "version": "8.0.0",
+                "autoload": {
+                    "psr-4": {
+                        "OpenEMR\\": "src/"
+                    }
+                },
+                "source": {
+                    "type": "git",
+                    "url": "https://github.com/openemr/openemr.git",
+                    "reference": "v8_0_0"
+                }
+            }
+        },
+        {
+            "type": "package",
+            "package": {
+                "name": "openemr/openemr",
+                "version": "8.1.0.x-dev",
+                "autoload": {
+                    "psr-4": {
+                        "OpenEMR\\": "src/"
+                    }
+                },
+                "source": {
+                    "type": "git",
+                    "url": "https://github.com/openemr/openemr.git",
+                    "reference": "rel-810"
+                }
+            }
+        },
+        {
+            "type": "package",
+            "package": {
+                "name": "openemr/openemr",
+                "version": "dev-master",
+                "autoload": {
+                    "psr-4": {
+                        "OpenEMR\\": "src/"
+                    }
+                },
+                "source": {
+                    "type": "git",
+                    "url": "https://github.com/openemr/openemr.git",
+                    "reference": "master"
+                }
+            }
+        }
+    ],
     "minimum-stability": "stable",
     "prefer-stable": true,
     "autoload": {

src/ConfigService.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenCoreEMR\ModuleConfig;
+
+use OpenEMR\Common\Crypto\CryptoGen;
+use OpenEMR\Common\Database\QueryUtils;
+
+/**
+ * Persist module settings to the OpenEMR globals table via upsert.
+ *
+ * @author    Michael A. Smith <michael@opencoreemr.com>
+ * @copyright Copyright (c) 2026 OpenCoreEMR Inc. <https://www.opencoreemr.com>
+ */
+class ConfigService
+{
+    private const UPSERT_SQL = <<<'SQL'
+        INSERT INTO `globals` (`gl_name`, `gl_index`, `gl_value`)
+        VALUES (?, 0, ?)
+        ON DUPLICATE KEY UPDATE `gl_value` = ?
+        SQL;
+
+    /**
+     * Save a setting to the globals table (plaintext).
+     */
+    public function saveSetting(string $key, string $value): void
+    {
+        QueryUtils::sqlStatementThrowException(self::UPSERT_SQL, [$key, $value, $value]);
+    }
+
+    /**
+     * Encrypt a value with CryptoGen and save it to the globals table.
+     */
+    public function saveEncryptedSetting(string $key, string $value): void
+    {
+        $encrypted = (new CryptoGen())->encryptStandard($value);
+        $this->saveSetting($key, $encrypted);
+    }
+}

src/GlobalsRegistrar.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenCoreEMR\ModuleConfig;
+
+use OpenEMR\Events\Globals\GlobalsInitializedEvent;
+use OpenEMR\Services\Globals\GlobalSetting;
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
+use Symfony\Component\HttpFoundation\ParameterBag;
+
+/**
+ * Register a module's globals section: enable/disable toggle and settings page link.
+ *
+ * Eliminates the boilerplate every OCE module copy-pastes in its Bootstrap class.
+ *
+ * @author    Michael A. Smith <michael@opencoreemr.com>
+ * @copyright Copyright (c) 2026 OpenCoreEMR Inc. <https://www.opencoreemr.com>
+ */
+class GlobalsRegistrar
+{
+    public function __construct(
+        private readonly ParameterBag $globalsBag,
+    ) {
+    }
+
+    /**
+     * Subscribe to GlobalsInitializedEvent and register the module's globals section.
+     */
+    public function register(
+        EventDispatcherInterface $eventDispatcher,
+        GlobalsSectionDescriptor $descriptor,
+    ): void {
+        $globalsBag = $this->globalsBag;
+
+        $eventDispatcher->addListener(
+            GlobalsInitializedEvent::EVENT_HANDLE,
+            static function (GlobalsInitializedEvent $event) use ($descriptor, $globalsBag): void {
+                $service = $event->getGlobalsService();
+
+                $service->createSection($descriptor->sectionName);
+
+                // Enable/disable toggle
+                $enableSetting = new GlobalSetting(
+                    sprintf(xlt('Enable %s'), $descriptor->sectionName),
+                    GlobalSetting::DATA_TYPE_BOOL,
+                    '0',
+                    sprintf(xlt('Enable or disable the %s module'), $descriptor->sectionName),
+                );
+                $service->appendToSection(
+                    $descriptor->sectionName,
+                    $descriptor->enableKey,
+                    $enableSetting,
+                );
+
+                // Settings page link
+                $webroot = $globalsBag->getString('webroot');
+                $settingsPath = $webroot
+                    . '/interface/modules/custom_modules/' . $descriptor->moduleDirName
+                    . '/public/settings.php';
+
+                $linkSetting = new GlobalSetting(
+                    xlt('Module Settings'),
+                    GlobalSetting::DATA_TYPE_HTML_DISPLAY_SECTION,
+                    '',
+                    xlt('Link to the module settings page'),
+                );
+                $linkSetting->addFieldOption(
+                    GlobalSetting::DATA_TYPE_OPTION_RENDER_CALLBACK,
+                    static function () use ($settingsPath, $descriptor): string {
+                        $url = attr($settingsPath);
+                        $label = xlt('Open Module Settings');
+                        $description = xlt($descriptor->settingsDescription);
+                        return <<<HTML
+                            <p>{$description}</p>
+                            <a href="{$url}" class="btn btn-secondary btn-sm"
+                               onclick="top.restoreSession()">{$label}</a>
+                            HTML;
+                    },
+                );
+                $service->appendToSection(
+                    $descriptor->sectionName,
+                    $descriptor->enableKey . '_settings_link',
+                    $linkSetting,
+                );
+            },
+        );
+    }
+}

src/GlobalsSectionDescriptor.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenCoreEMR\ModuleConfig;
+
+/**
+ * Parameters for registering a module's globals section (enable toggle + settings link).
+ *
+ * @author    Michael A. Smith <michael@opencoreemr.com>
+ * @copyright Copyright (c) 2026 OpenCoreEMR Inc. <https://www.opencoreemr.com>
+ */
+final readonly class GlobalsSectionDescriptor
+{
+    /**
+     * @param string $sectionName Display name for the globals section (e.g. "OpenCoreEMR Sinch Conversations")
+     * @param string $moduleDirName Module directory name under custom_modules/ (e.g. "oce-module-sinch-conversations")
+     * @param string $enableKey Globals key for the enable/disable toggle (e.g. "oce_sinch_conversations_enabled")
+     * @param string $settingsDescription Help text shown above the settings link
+     */
+    public function __construct(
+        public string $sectionName,
+        public string $moduleDirName,
+        public string $enableKey,
+        public string $settingsDescription,
+    ) {
+    }
+}

tests/Mocks/MockCryptoGen.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenEMR\Common\Crypto;
+
+/**
+ * Mock CryptoGen — uses base64 to simulate encryption without real crypto dependencies.
+ */
+class CryptoGen
+{
+    public function encryptStandard(string $value): string
+    {
+        return base64_encode($value);
+    }
+}

tests/Mocks/MockQueryUtils.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenEMR\Common\Database;
+
+/**
+ * Mock QueryUtils to avoid database calls during tests.
+ */
+class QueryUtils
+{
+    /** @var list<array{sql: string, binds: list<mixed>}> */
+    private static array $queries = [];
+
+    private static ?\Throwable $nextException = null;
+
+    /**
+     * @param list<mixed> $binds
+     */
+    public static function sqlStatementThrowException(string $sql, array $binds = []): true
+    {
+        self::$queries[] = ['sql' => $sql, 'binds' => $binds];
+        if (self::$nextException !== null) {
+            $e = self::$nextException;
+            self::$nextException = null;
+            throw $e;
+        }
+        return true;
+    }
+
+    public static function setNextException(\Throwable $e): void
+    {
+        self::$nextException = $e;
+    }
+
+    /** @return list<array{sql: string, binds: list<mixed>}> */
+    public static function getQueries(): array
+    {
+        return self::$queries;
+    }
+
+    public static function reset(): void
+    {
+        self::$queries = [];
+        self::$nextException = null;
+    }
+}

tests/Mocks/openemr_functions.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+// Stubs for OpenEMR global functions used by library classes (xlt, attr, etc.).
+// Loaded by the test bootstrap before any test runs.
+
+if (!function_exists('xlt')) {
+    function xlt(string $text): string
+    {
+        return $text;
+    }
+}
+
+if (!function_exists('attr')) {
+    function attr(string $text): string
+    {
+        return htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
+    }
+}