How to prefix third-party composer libraries for WordPress Plugin

When developing WordPress plugins, you often need to prefix third-party composer libraries to avoid conflict. However, conflicts between third-party libraries can arise when multiple plugins include different versions of the same library. This can lead to unexpected behavior or even fatal errors, making it crucial to isolate dependencies properly.

In this blog, we’ll explore how to resolve such conflicts using manual namespacing and automation with PHP-Scoper.

The Problem: Conflicting Dependencies

Imagine you have a WordPress plugin that generates QR codes using the endroid/qr-code library(version 1.0.0). If another plugin on the same site also includes endroid/qr-code (version 2.0.0) but in a different version, conflicts can occur, leading to class redefinition errors and potential plugin failures.

We need to isolate third-party dependencies to avoid this so they don’t interfere with other plugins.

Option 1 : Let’s first start with the manual process of resolution

One way to resolve conflicts is to manually rename the namespace of the third-party library and update your plugin’s references. Here’s how:

Step 1: Download the Library

Install endroid/qr-code into your plugin’s vendor/ directory using Composer:

composer require endroid/qr-code

Step 2: Move the Library

Relocate the library into a custom namespace within your plugin’s src/vendor/ directory.

Step 3: Modify the Namespace

Update the library files to use a unique namespace. This involves manually renaming all references within the library’s source files:

namespace MyPlugin\Vendor\Endroid\QrCode;

Since most third-party libraries are structured with multiple files and dependencies, this process can be tedious. You’ll need to update all references in the library to use your new namespace. For example, if a file originally contained:

use Endroid\QrCode\QrCode;

It should be updated to:

use MyPlugin\Vendor\Endroid\QrCode\QrCode;

Step 4: Update Your Plugin Code

Ensure your plugin references the modified namespace:

use MyPlugin\Vendor\Endroid\QrCode\QrCode;

$qrCode = new QrCode('example');

This manual method effectively isolates dependencies but is labor-intensive and error-prone. A more efficient solution is to automate the process using library like PHP-Scoper.

Option 2 : Using PHP-Scoper to Automate Namespacing

PHP-Scoper is a tool that automatically renames namespaces, ensuring dependencies remain isolated.

Step 1: Install PHP-Scoper

composer require humbug/php-scoper --dev

Step 2: Configure PHP-Scoper

Create a scoper.inc.php file in your plugin’s root directory with the following configuration:

<?php

return [
    'prefix'.  => 'MyPluginVendor', // Custom namespace prefix
    'finders'  => [],
    'patchers' => [],
];

Step 3: Run PHP-Scoper

Execute the following command to apply namespace isolation:

php-scoper add-prefix

Now, all third-party dependencies will be prefixed and safely isolated.

Automating the Process with Composer Scripts

To ensure that namespacing is applied every time you package your plugin, you can automate the process using a Composer script.

Step 1: Add a Composer Script

Modify your composer.json file to include a script under the scripts section:

"scripts": {
    "pre-package": [
        "php-scoper add-prefix"
    ]
}

Step 2: Using Composer to Create a ZIP Archive

Modify composer.json Add the following script under scripts in your composer.json:

"scripts": {
    "pre-package": [
        "php-scoper add-prefix"
    ],
    "package": [
        "composer run pre-package",
        "composer archive --format=zip --dir=build"
    ]
}

Run the Packaging Process
Execute the following command to generate a ZIP file:

composer run package

How this Works?

pre-package runs PHP-Scoper to namespace dependencies.
composer archive creates a ZIP file of the plugin inside a build/ directory.
The ZIP file will exclude vendor/ if specified in .gitattributes.

This ensures that third-party dependencies are properly namespaced before creating a ZIP file, avoiding conflicts in WordPress.

By leveraging PHP-Scoper and automating the process with Composer scripts, you can prevent dependency conflicts, ensuring the smooth operation of your WordPress plugin. This approach saves time, reduces errors, and improves compatibility with other plugins.

Have questions or suggestions? Let me know in the comments!

Kishan Jasani