OpenEMR Customization: When to Build a Module Instead of Modifying Core Code

OpenEMR Customization: When to Build Modules vs. Core Changes

OpenEMR is a PHP-based electronic medical record system with a built-in module framework. Customising OpenEMR falls into two categories: modifying core code or creating a module. Core changes (patching core PHP files) are technically possible but are discouraged for most extensions. Community leaders note that core modifications must be re-applied on each upgrade and can be avoided by using modules: “to avoid having to do this in the future you should try bundling your changes into a module”. Conversely, modules can be installed via Composer and maintained separately, preserving core upgradability.

This post provides a framework to decide when to build a module versus patching core, illustrated with OpenEMR examples. It covers module architecture, practical criteria, trade‑offs, and considerations (upgrades, security, testing). We assume no specific OpenEMR version – the advice applies broadly to v7, v8, etc.

When to Use a Module vs Modify Core

Deciding between a module and a core patch depends on the change’s scope, reusability, and risk. Guiding principles from OpenEMR leadership include:

  • Vendor or Third‑Party Services: If integration involves an external service or vendor-specific feature (e.g., payment gateway, telehealth, e-prescribing), implement it as a module. OpenEMR should remain neutral about third-party choices, so such features are “a clear line against [core]” inclusion. For example, the official Comlink Telehealth and WENO ePrescribing features are provided as modules (not core).
  • User Base: If a new feature is needed by a large share of users (a general EMR feature), it may belong in core. Otherwise (site‑specific or niche functionality), a module isolates it. The module approach does not preclude eventual core adoption, but keeps optional features separate for now.
  • Scope of Change: Simple UI tweaks or report changes can often hook into existing infrastructure via a module. Complex logic changes touching many core functions might be too invasive for a module hook.
  • Upgrade/Portability: Changes in core require manual merging after each update. Modules allow clean upgrades – the core can be updated independently and modules updated or reinstalled via Composer. In fact, developers warn that if you have altered core files, you must reapply them after a patch; to avoid that hassle, one should use a module.
  • Events/Hooks Availability: OpenEMR emits events (e.g., menu rendering, form load, API access) that modules can listen to. If the desired change can be done by hooking an event (for example, adding a menu link or injecting code on page load), use a module. If no suitable event exists, one can propose adding an event in core and then implement a module, rather than hacking core.
  • Maintenance and Security: Custom core code adds to the long-term maintenance burden of OpenEMR. Modules (especially community‑maintained ones) can be managed and audited separately. Core authors emphasise security; modules that bypass core checks must enforce their own ACLs and logging.

Practically, consider the following checklist:

  • Is this a vendor integration or optional add‑on? → Module. (E.g., payment processors, telehealth, messaging services.)
  • Is it a general feature needed by most clinics? → Core (or contribute). (E.g., a new billing workflow, critical LBF calculation feature.)
  • Can it be done via an event/hook? → Module. (Use existing events like EncounterMenuEvent, LoadEncounterFormFilterEvent, etc.)
  • Does it require changing the database schema? → Modules can have their own tables (via table.sql), so a module is appropriate unless the schema must be in core for standardized use.
  • Will it affect all users and require certification? → Possibly core (submit a PR to upstream).
  • Is the change trivial or highly local? → Module (keep it separate; easier to remove later).

Decision Table (Module vs Core):

Factor Module Core Code Change
Purpose New feature/extension, especially third-party integration Core feature needed by most users
Scope Localised or optional functionality; can use hooks/events Broad change affecting workflows or UI globally
Upgradability Easier – no core merge conflicts; managed by Composer Harder – must reapply patches on upgrades
Maintenance Isolated; maintain separately; can be removed without core impact Coupled; harder to track; risk of divergences
Installation Composer require; use package registry Directly edit source files; must redeploy manually
Security/Compliance Must enforce its own ACLs, CSRF, PHI handling (outside core audit logs) Inherits core’s security controls
Dependencies Can declare module dependencies via Composer; limited to PHP modules N/A (all code lives in one codebase)
Testing Test as a separate component; can be disabled Impacts core tests; harder to isolate issues
Project Contribution Encourages community modules; can be upstreamed if widely useful Submit PR; go through review; must adhere to core standards

OpenEMR Module Architecture

OpenEMR’s modern architecture (v7/v8) embeds the Zend/Laminas MVC framework. Custom modules follow this pattern and live under interface/modules/. There are two categories:

  • Zend Modules (/interface/modules/zend_modules): Structured as Laminas modules, with Module.php, config/module.config.php, Controllers, etc.
  • Custom Modules (/interface/modules/custom_modules): A simpler structure for legacy or loosely coupled modules. Each custom module lives in its own subfolder, typically with:
    • module_name/ (folder named after module, e.g. oe-module-telehealth)
      • index.php (entry point or landing page)
      • info.txt (module name/description)
      • table.sql (DB tables for the module).
      • moduleSettings.php (defines ACL, hooks, etc).
      • public/ (web-accessible assets or forms).
      • Additional PHP files, classes as needed.

Both module types register with OpenEMR’s Module Installer. They can define dependencies on other modules and declare the needed OpenEMR version (e.g., via composer require or module config). For example, the online modules list shows version requirements.

Modules integrate via hooks/events. Notably:

  • Menu Hooks: A module can add items to OpenEMR menus by defining hooks or subscribing to menu events. For instance, hooking into the MainMenuRole (e.g. EncounterMenuEvent) lets a module insert new menu links. Example code:
use OpenEMR\Events\Encounter\EncounterMenuEvent;

// ...

public function onEncounterMenu(EncounterMenuEvent $event) {

    $menu = $event->getMenuData();

    // Add a new menu entry under "WC AI Agent"

    $menu['WC AI Agent'] = [

      'children' => [[

          'state' => 1,

          'directory' => 'oe-module-wound-care',  // module directory

          'displayText' => 'Assistant',

          // other menu item attributes...

      ]]

    ];

    $event->setMenuData($menu);

    return $event;

}
  • Form/Content Hooks: For injecting pages or forms, OpenEMR triggers events like LoadEncounterFormFilterEvent when loading an encounter form. A module can respond and redirect the form include path into the module directory. Example:
public function respondToLoadEncounterFormFilterEvent(

  LoadEncounterFormFilterEvent $event

) {

    $customForms = ['my-test-form'];

    if (in_array($event->getFormName(), $customForms)) {

        // Point to module’s public/forms/<formName>/ directory

        $dir = $this->modulePath . 'public/forms/' . $event->getFormName() . '/';

        $event->setDir($dir);

    }

    return $event;

}
  • The $this->modulePath is the file-system path to interface/modules/custom_modules/<module>/. See [54†L175-L184] for details. This mechanism lets modules supply their own forms or pages in context without editing core form code.
  • Routing: Zend modules typically place front-end files under public/ and define routes in module.config.php. Custom modules might use a simpler index.php. URLs to modules generally go through interface/zend_modules/public/… with .htaccess mapping to the controller/action in the module config.
  • Composer & Installation: Modern modules are managed via Composer. As one core developer notes, “we haven’t given much thought to installing any non-PHP service via modules as our module architecture now is all delivered via Composer”. For example, a sample skeleton module can be added with:

composer require adunsulag/oe-module-custom-skeleton

  • as documented on Packagist. This ensures modules are versioned and loaded by the autoloader. The composer.json for a module should specify its name, description, version, dependencies, and autoload PSR‑4 classes. Once installed, modules appear in Admin > Modules and can be enabled.

Implementation and Integration Details

When building a module:

  • File Structure: Follow the module guidelines. Use info.txt (or composer.json description) for metadata. Define moduleSettings.php with $MODULESETTINGS array (ACL and hooks), or for Zend modules, put that info in module.config.php.
  • Menu Integration: Define hook classes (listeners) that subscribe to menu events. Use existing event names (e.g., MenuEvent, EncounterMenuEvent) to insert menu entries or modify menus. An example from the ModuleMenuSubscriber class shows how moduleSettings hooks are applied under “Modules” and “Reports” menus, but custom listeners can target any menu (e.g., the “Encounter” menu).
  • Routing and Pages: Modules deliver pages via controller/action or static files. Zend modules use Laminas controllers, whereas simple modules might include PHP scripts. Ensure any new pages have proper ACL checks or token verification as needed.
  • Dependencies: In your module composer.json or installer config, list any required modules. For example, one can specify a getDependedModulesConfig() function for older modules, or in module.config.php use ‘dependencies’.
  • Data Schema: Include table.sql in your module root to create necessary tables. This SQL is run when enabling the module. Schema names should avoid collisions (prefix with module name or use unique names).
  • Configuration: Use the Module Installer’s config UI or moduleSettings.php to let the admin set options. ACLs for new menu links or actions must be declared so that the Administrator can grant permissions. The example $MODULESETTINGS[‘ACL’] array shows how to name ACOs for access control.
  • Example Customizations: In practice, many custom modules exist. The official modules listing includes:
    • WENO ePrescribing: Requires ≥7.0.2; vendor eRx integration.
    • Comlink Telehealth: Requires ≥7.0.0; video conferencing integration.
    • Fax/SMS module: Requires ≥7.0.1; telecom functions.
    • ClaimRev Clearinghouse: Requires ≥7.0.1; billing submission service.
    • Payment Processing (Sphere): Requires ≥6.0.0; handles payment gateway.
    • Custom Billing/Reporting: e.g. Layout-Based Form extensions (LBF modules) for summaries. These concrete examples illustrate that integrations (eRx, telehealth, payments) are modules, not core features.
  • Code Snippets: A minimal composer.json for an OpenEMR module might look like:
{

  "name": "acme/oe-module-example",

  "description": "My Custom Module",

  "type": "project",

  "require": {

    "php": "^7.4"

  },

  "autoload": {

    "psr-4": {

      "ACME\\OE\\Example\\": "src/"

    }

  }

}
  • Inside src/, you’d place your PHP classes (e.g. a Module class). The Module class’s onBootstrap() method can attach listeners:
public function onBootstrap($event) {

    $app = $event->getApplication();

    $evm = $app->getEventManager();

    $evm->attach(MenuUpdateEvent::class, [$this, 'addMenuItem']);

}
  • Hooks vs Core Edits: As emphasized by core contributors, if a desired extension requires changing core logic, first ask if an event can achieve it. Modules can register for built-in events without editing any core file. For example, instead of hard-coding a new UI control in patient_tracker.php, one might hook into an “onChartStart” event to add custom content. If no event exists, best practice is to request a new hook via an issue/PR, rather than modifying core. This makes future maintenance easier.

Upgrade and Maintenance Considerations

Modular design greatly simplifies upgrades. When OpenEMR issues a new version or patch, it only replaces its own core files. If you modified core, you must manually merge your changes after every upgrade. In contrast:

  • Modules survive upgrades: Since modules are separate packages, updating OpenEMR typically won’t overwrite them. You manage modules via Composer or the Module UI. If a module is broken by an upgrade, you only need to update the module (or adapt it), leaving core intact.
  • Version Compatibility: As of 2026, the project plans to let modules declare a minimum OpenEMR version. For now, check module compatibility yourself before upgrading. The online module list shows required versions as a hint.
  • Merging Custom Core: If you do patch core, clearly document changes in version control. Align with OpenEMR’s patch release workflow. Follow the advice of project developers: upstream generic fixes into core when possible. The deployment approach “runs clean, unmodified OpenEMR as released” and only resorts to local forks if an upstream PR is declined. If a feature merits inclusion, submit a pull request for core incorporation.

If you modified core files, compare and reapply changes manually, and “to avoid having to do this in the future you should try bundling your changes into a module”. 

Similarly, when integrating new FHIR endpoints, core devs advised: “If you do it as a custom module, you can use it without having to modify core files”. These reminders underscore that modules ease ongoing maintenance.

Security, Privacy and Testing

Regardless of approach, security is paramount. Key points:

  • Use Core APIs and Framework: Whenever possible, leverage OpenEMR’s built-in libraries (e.g. Doctrine DBAL, Twig templating) to reduce vulnerabilities. The project is moving to Doctrine (ORM) for queries and Twig for HTML, explicitly to eliminate SQL injection and XSS risks. Modules should adopt these patterns (if available) instead of raw string SQL or manual escaping.
  • Access Control: Modules must define their own ACL objects so administrators can grant access. In moduleSettings.php, set ‘ACL’ entries for menu items or functionality. Without proper ACL, any user could see your module’s UI.
  • CSRF and Input Validation: Any form or AJAX endpoint in a module should include CSRF tokens (OpenEMR provides token helpers) and validate inputs just like core. Treat module code with the same discipline as core code. Core developers explicitly audit for missing CSRF/ACL in modules (“file_download.php has no ACL or CSRF” caused a CVE in one module), so be vigilant.
  • PHI Handling: If your module sends Protected Health Information to an external service, ensure you handle PHI securely. Unlike core code, which automatically logs data access at the database level, custom code must implement its own audit logging and encryption of data in transit. The core team warns that outside-core services must treat PHI with care: “This is handled at the core SQL level inside of OpenEMR and if you operate outside that, you’ll need to make sure you are handling all the compliance aspects yourself”. For example, record who accessed patient data, when, and via which module in your own logs.
  • Testing: Thoroughly test both modules and core changes. For modules, this includes unit tests (if you set up PHPUnit) and integration testing in a staging OpenEMR install. Ensure your code does not break existing features. Use static analysis (linting) on PHP, and consider security scanners (e.g. OWASP ZAP) against any new web routes you add. Document your tests so future maintainers know how to verify the module. Remember that core patches should pass the standard OpenEMR test suite (if any) and community review.

Customize OpenEMR Without Compromising Its Core

Build a more flexible and scalable EHR with CapMinds. 

Our OpenEMR experts help you develop custom modules, optimize workflows, EHR integration healthcare systems, and extend functionality while keeping your core code upgrade-friendly.

Talk to Our OpenEMR Experts

Pandi Paramasivan

Pandi Paramasivan

Founder & CEO of CapMinds.