Table of Contents

  1. Introduction

  2. The Relationship Between Dolibarr and PHP

  3. Supported PHP Versions for Dolibarr (2023–2025)

  4. Common PHP Compatibility Problems in Dolibarr

  5. Diagnosing PHP Issues with Dolibarr

  6. Understanding Error Logs and Warning Types

  7. Upgrading or Downgrading PHP Safely for Dolibarr

  8. Adjusting PHP Configuration for Dolibarr

  9. Fixing Dolibarr Errors Caused by PHP Changes

  10. How Custom Modules and Templates Break with PHP Updates

  11. Development Best Practices for PHP Compatibility

  12. How to Future-Proof Your Dolibarr Instance

  13. Final Thoughts

1. Introduction

Dolibarr ERP & CRM is a robust, open-source business management platform designed to serve the evolving needs of freelancers, SMEs, and even large organizations. Built using PHP, Dolibarr relies entirely on the PHP runtime for everything—from rendering web pages to executing business logic and API endpoints.

Because of this, PHP version compatibility is not just a technical detail—it’s a foundational element that can directly impact performance, functionality, and stability.

In this article, we’ll explore how PHP and Dolibarr interact, identify common compatibility issues, walk through diagnostics and fixes, and offer best practices for keeping your system both up to date and stable.

2. The Relationship Between Dolibarr and PHP

Dolibarr is built entirely in PHP. Every single feature, module, and user interface component is processed through a PHP-based execution engine. That means the version of PHP running on your server must align with what Dolibarr supports.

If your PHP version is too old, Dolibarr may not start, or you may miss key features. If it’s too new, you could face unexpected errors, deprecated functions, and broken modules.

PHP upgrades introduce:

  • Performance improvements

  • Deprecation or removal of functions

  • Changes to default behavior (e.g., strict typing, error handling)

  • Extensions or configuration changes

  • Security fixes

Dolibarr releases are regularly updated to support newer PHP versions, but if you’re not tracking these changes carefully, you may find yourself with a broken instance after a PHP upgrade.

3. Supported PHP Versions for Dolibarr (2023–2025)

Here’s a general overview of PHP compatibility across recent Dolibarr versions:

Dolibarr Version Minimum PHP Recommended PHP Max Tested PHP
13.x – 14.x PHP 7.0 PHP 7.4 PHP 8.0
15.x – 17.x PHP 7.2 PHP 8.0 PHP 8.1
18.x – 20.x PHP 7.4 PHP 8.0 / 8.1 PHP 8.1
21.x – 22.x PHP 8.0 PHP 8.1+ PHP 8.2 / 8.3
Future 23.x+ PHP 8.1 PHP 8.2+ PHP 8.3+

Important: Always refer to the release notes of the specific Dolibarr version you're running before upgrading PHP.

4. Common PHP Compatibility Problems in Dolibarr

When PHP versions are not correctly aligned with Dolibarr’s requirements, the following issues may appear:

4.1 Fatal Errors

  • Example:

    php

    Fatal error: Uncaught Error: Call to undefined function get_magic_quotes_gpc()

This happens when Dolibarr code calls a function removed in newer PHP versions (like PHP 8.0 and above).

4.2 Deprecation Warnings

  • Example:

    php

    Deprecated: Array and string offset access syntax with curly braces is deprecated

This warning doesn’t crash the app but clutters logs and may indicate future failure points.

4.3 Module Incompatibility

  • Third-party modules written for PHP 7.x may break under PHP 8.x

  • Custom PDF templates using outdated functions can generate blank or broken documents

4.4 Unexpected Behavior

  • Broken redirects

  • Session issues (e.g., constant logouts)

  • API authentication failures

These are harder to trace but often stem from changed defaults or stricter type handling in newer PHP versions.

5. Diagnosing PHP Issues with Dolibarr

The first step to resolving compatibility problems is to accurately identify the cause.

5.1 Enable Error Reporting

In htdocs/main.inc.php, enable error output:

php

ini_set('display_errors', 1); error_reporting(E_ALL);

This will allow you to see warnings, notices, and fatal errors directly in your browser during testing.

5.2 Check PHP Logs

PHP logs often contain more detail than browser output.

Typical locations:

  • /var/log/php-fpm.log

  • /var/log/apache2/error.log

  • /var/log/nginx/error.log

  • /var/log/php/error.log (shared hosting)

Check for recent entries related to undefined functions, deprecated syntax, or memory_limit breaches.

5.3 Use phpinfo()

Create a simple PHP file in your Dolibarr root:

php

<?php phpinfo(); ?>

Access it via browser and confirm:

  • PHP version

  • Loaded extensions

  • Configuration values (memory_limit, upload_max_filesize, etc.)

  • Session and timezone settings

6. Understanding Error Logs and Warning Types

Understanding the different kinds of errors PHP produces is key to effective troubleshooting. Here's a quick breakdown of the most common error types seen in Dolibarr when there's a PHP mismatch.

6.1 Fatal Errors

These stop execution immediately. Dolibarr pages may render blank or break mid-way.

Example:

php

Fatal error: Uncaught Error: Undefined function mb_str_split()

6.2 Warnings

Warnings indicate a problem, but the page usually still loads.

Example:

php

Warning: Use of undefined constant ‘FOO’ - assumed ‘FOO’

These often appear when third-party code hasn’t been updated for new PHP versions.

6.3 Notices

Notices point to sloppy or deprecated code.

Example:

php

Notice: Trying to access array offset on value of type null

These may not affect functionality today but can become errors in future PHP versions.

6.4 Deprecated Notices

PHP flags features that will be removed soon. These notices are your early warning system.

Example:

php

Deprecated: Function create_function() is deprecated in ...

While Dolibarr core is generally cleaned up with each release, older modules and custom code often cause these notices.

7. Upgrading or Downgrading PHP Safely for Dolibarr

Changing your PHP version can resolve issues—or create them. The key is doing it methodically.

7.1 When to Upgrade PHP

Upgrade if:

  • You're running an older PHP version (e.g. 7.2, 7.3) that’s no longer supported

  • You need better performance or security features

  • You’re moving to a newer Dolibarr version (e.g., 22.x+ requires PHP 8.0 or higher)

7.2 When to Downgrade PHP

Downgrade if:

  • You’re using legacy Dolibarr versions (e.g., v12–v14)

  • Custom modules are not compatible with PHP 8.x

  • You experience fatal errors after a PHP update

Important: Always test in a staging environment before changing PHP in production.

7.3 How to Change PHP Version (Linux CLI)

For Ubuntu/Debian:

bash

sudo apt install php8.1 php8.1-mysql php8.1-cli php8.1-fpm sudo update-alternatives --config php

For CentOS/RHEL:

bash

sudo yum install php81 php81-php-fpm

To switch back to a previous version:

bash

sudo update-alternatives --config php

Restart the web server:

bash

sudo systemctl restart apache2 # or sudo systemctl restart php8.1-fpm

Make sure Dolibarr loads properly and all modules are accessible after the change.

8. Adjusting PHP Configuration for Dolibarr

Even with the right PHP version, bad settings can cause slow performance or unexpected errors.

Edit php.ini to fine-tune these settings:

ini

memory_limit = 512M upload_max_filesize = 20M post_max_size = 25M max_execution_time = 120 max_input_vars = 3000 date.timezone = "Europe/Paris" ; Or your local timezone

8.1 Enable Required Extensions

Dolibarr requires several PHP extensions. Use php -m to check active modules.

Make sure these are enabled:

  • pdo_mysql

  • mbstring

  • curl

  • gd

  • intl

  • json

  • fileinfo

  • xml

Enable extensions via:

bash

sudo apt install php8.1-gd php8.1-mbstring php8.1-curl php8.1-intl

Then restart your web server.

9. Fixing Dolibarr Errors Caused by PHP Changes

Here’s how to fix specific Dolibarr issues triggered by PHP version mismatches:

9.1 get_magic_quotes_gpc() Undefined

This function was removed in PHP 8.0.

Fix: Upgrade Dolibarr to at least v15.x or comment out calls in custom modules.

9.2 Blank Invoices or Proposals

This is often due to outdated TCPDF or DOMPDF versions that aren’t PHP 8 compatible.

Fix:

  • Replace custom PDF templates with updated ones

  • Upgrade the lib/pdf or lib/tcpdf directories

  • Ensure no whitespace exists before <?php tags in templates

9.3 API Authentication Fails

Newer PHP versions may handle header parsing more strictly.

Fix:

  • Verify the API key is passed correctly

  • Confirm content-type headers are set

  • Re-enable web services in the Dolibarr configuration

9.4 Broken Modules or Menus

If menus disappear or modules fail to load after a PHP upgrade, it may be due to:

  • Deprecated syntax (e.g. curly brace array offsets)

  • Old-style constructors in classes

  • Missing or changed function calls

Fix:

  • Check logs

  • Disable the problematic module

  • Update the module if a newer version exists

  • Contact the module developer for a PHP 8.x update

10. How Custom Modules and Templates Break with PHP Updates

Dolibarr core evolves quickly, but custom modules often lag behind. Here’s what typically breaks:

10.1 Old PHP Syntax

Custom modules written for PHP 5 or 7 may use now-deprecated syntax.

  • create_function()

  • each()

  • Short open tags (<? instead of <?php)

  • Non-strict comparison

Solution: Refactor code using PHP 8 best practices and test on a staging server.

10.2 Deprecated Constructors

Older class constructors may use the class name, which is no longer valid in PHP 8:

php

class MyModule { function MyModule() { ... } // Invalid in PHP 8 }

Replace with:

php

function __construct() { ... }

10.3 PDF Templates with Obsolete Calls

Custom PDF invoice or proposal templates often use outdated methods or functions that conflict with newer versions of DOMPDF or TCPDF.

Solution:

  • Rebuild the template using the latest pdf_model.class.php structure

  • Validate all variables and output functions

  • Avoid any direct echo or print statements outside of buffered content

11. Development Best Practices for PHP Compatibility

For those developing on or extending Dolibarr, follow these best practices to ensure compatibility with current and future PHP versions.

Use PHP 8+ in Development

Always test your modules against the latest PHP versions, even if production uses older versions.

Avoid Deprecated Features

Track deprecations using the PHP manual or tools like:

Use Type Declarations When Possible

Type-safe code is more resilient to PHP version changes.

php

public function calculateTotal(float $amount, int $taxRate): float

Structure Modules Properly

Follow Dolibarr's module skeleton and ensure you declare:

  • Hooks

  • Permissions

  • Menu entries

  • Language files

This ensures your module integrates cleanly regardless of PHP changes.

12. How to Future-Proof Your Dolibarr Instance

Always Use LTS Versions

Stick to Dolibarr releases labeled as stable or LTS to avoid regressions.

Test Before You Upgrade

Maintain a staging environment with the upcoming PHP and Dolibarr versions.

Track Compatibility Announcements

Dolibarr changelogs often include notes about PHP support. Watch for:

  • Minimum PHP version changes

  • Deprecated features

  • Compatibility-breaking core updates

Automate Compatibility Checks

Integrate static analysis tools in your CI pipeline:

  • PHPStan

  • Psalm

  • PHP_CodeSniffer (with PHPCompatibility ruleset)

13. Final Thoughts

PHP compatibility is a core concern for every Dolibarr user, from small business owners to full-stack developers. As Dolibarr evolves to take advantage of modern PHP features—improving speed, security, and code quality—you must evolve your environment with it.

A smart compatibility strategy includes:

  • Staying on supported Dolibarr versions

  • Keeping PHP up to date—but not too far ahead

  • Testing thoroughly in staging environments

  • Updating custom modules proactively

  • Following PHP development best practices

By mastering the relationship between PHP and Dolibarr, you ensure your ERP system is not only functional and fast, but also resilient and future-ready.