Real‑world examples of duplicate function definition errors in PHP

Classic examples of duplicate function definition errors in PHP

Let’s start with the most boring — and most common — scenario: two files, one function name.

// file: helpers.php
<?php
function format_price(float $amount): string {
    return '\(' . number_format(\)amount, 2);
}

// file: more_helpers.php
<?php
function format_price(float $amount): string {
    return '\(' . number_format(\)amount, 2) . ' USD';
}

// file: index.php
<?php
require 'helpers.php';
require 'more_helpers.php';

echo format_price(10);

Run index.php and PHP stops with:

Fatal error: Cannot redeclare format_price() (previously declared in /path/helpers.php:3)

This is one of the simplest examples of duplicate function definition errors in PHP: the same function name is defined twice in the global namespace. The interpreter doesn’t care that the implementations differ or that the second one might be “better.” It just refuses to redeclare.

Real examples of duplicate function definition errors in PHP with includes and requires

The next pattern shows up constantly in legacy projects: the same file included multiple times through different paths.

// file: config.php
<?php
function app_config(): array {
    return ['env' => 'production'];
}

// file: bootstrap.php
<?php
require 'config.php';

// file: index.php
<?php
require 'config.php';
require 'bootstrap.php'; // indirectly requires config.php again

$config = app_config();

Result:

Fatal error: Cannot redeclare app_config() (previously declared in /path/config.php:3)

This is a textbook example of duplicate function definition errors in PHP caused by require instead of require_once. Because config.php is loaded directly and then loaded again via bootstrap.php, PHP tries to define app_config() twice.

Switching to require_once or include_once in bootstrap.php (or everywhere) fixes it:

// bootstrap.php
require_once 'config.php';

In large codebases, this pattern becomes nasty when file paths differ slightly (../config.php vs ./config.php) and the developer assumes they’re different files. PHP resolves them to the same file and you get the same fatal error.

Composer and autoloading: modern examples include library name collisions

In 2024, a lot of PHP projects use Composer for dependency management. That’s good news, but it also introduces more subtle examples of duplicate function definition errors in PHP.

Imagine you pull in two libraries that both define a global helper function called array_flatten() in their own functions.php files:

// composer.json (simplified)
{
  "autoload": {
    "files": [
      "vendor/libA/src/functions.php",
      "vendor/libB/src/functions.php"
    ]
  }
}

// vendor/libA/src/functions.php
<?php
function array_flatten(array $items): array {
    // implementation A
}

// vendor/libB/src/functions.php
<?php
function array_flatten(array $items): array {
    // implementation B
}

Composer’s file autoloading system will include both functions.php files on every request. The result is a fatal Cannot redeclare array_flatten() before your app even boots.

These are some of the best examples of how modern tooling can still produce duplicate function definition errors in PHP. The fix options are limited:

• Remove or replace one of the libraries.
• Fork one library and rename the function or move it into a namespace.
• Stop using autoload.files for global functions and move them into proper classes or namespaced functions.

The broader trend in modern PHP (especially since PHP 7 and 8) is to avoid global functions in libraries precisely because of these problems, and to rely on namespaced functions or class methods instead.

For an overview of modern PHP practices, the official PHP manual remains the best starting point: https://www.php.net/manual/en/

Conditional definitions: function_exists as a double‑edged sword

Developers often try to guard against duplicates using function_exists. Used correctly, it prevents redeclaration. Used poorly, it hides deeper design problems.

// file: legacy_helpers.php
<?php
if (!function_exists('str_starts_with')) {
    function str_starts_with(string \(haystack, string \)needle): bool {
        return substr(\(haystack, 0, strlen(\)needle)) === $needle;
    }
}

Before PHP 8, this was a common polyfill pattern. In PHP 8+, str_starts_with is a built‑in function. Without the function_exists check, this code would explode with a duplicate function definition error as soon as you upgraded to PHP 8.

In other words, function_exists can turn potential examples of duplicate function definition errors in PHP into safe, version‑aware fallbacks. But if you scatter this pattern across multiple files, you can still trip yourself up:

// file: helpers_a.php
<?php
if (!function_exists('slugify')) {
    function slugify(string $text): string { /* ... */ }
}

// file: helpers_b.php
<?php
if (!function_exists('slugify')) {
    function slugify(string $text): string { /* slightly different ... */ }
}

Here, you don’t get a fatal error, but you do get non‑deterministic behavior depending on which file is loaded first. These are quieter, more dangerous examples of duplicate function definition logic, even if PHP doesn’t technically throw the error.

Namespaces: cleaner design, but not a silver bullet

Namespaces are often sold as the answer to everything. They help, but they don’t completely eliminate duplicate function definition errors in PHP.

First, the good news. With namespaces, you can safely define two functions with the same short name:

// file: src/Math/Helpers.php
<?php
namespace App\Math;

function sum(array $numbers): int {
    return array_sum($numbers);
}

// file: src/String/Helpers.php
<?php
namespace App\String;

function sum(array $chars): int {
    return strlen(implode('', $chars));
}

No conflict here, because the fully qualified names are App\Math\sum and App\String\sum.

But here’s where people still run into trouble. Suppose a legacy file defines a global function sum() without a namespace:

// file: legacy_sum.php
<?php
function sum(array $numbers): int {
    return array_sum($numbers);
}

And somewhere else, you accidentally define it again, also without a namespace:

// file: other_legacy_sum.php
<?php
function sum(array $numbers): int {
    return array_sum($numbers) + 1; // debugging hack that leaked into prod
}

If both files are included, you get the familiar fatal error. Namespaces only help if you actually use them consistently and avoid global functions for shared helpers.

The PHP manual’s section on namespaces is worth a careful read if you’re still mixing namespaced and global code: https://www.php.net/manual/en/language.namespaces.php

Frameworks and real examples from modern PHP stacks

In current Laravel, Symfony, and WordPress ecosystems, examples of duplicate function definition errors in PHP usually come from one of three patterns:

WordPress and pluggable functions

WordPress has a long‑standing pattern of “pluggable” functions that can be redefined by plugins. Core defines them only if they don’t already exist:

if (!function_exists('wp_mail')) {
    function wp_mail(\(to, \)subject, \(message, \)headers = '', $attachments = array()) {
        // core implementation
    }
}

If a plugin tries to define wp_mail() without that guard, or includes a file twice, you get a duplicate function definition error. Real examples include:

• Plugins that copy an old version of a core function into their own file.
• Themes that ship their own wp_mail() implementation without respecting the pluggable pattern.

The WordPress developer resources document this pattern and recommend function_exists for overrides: https://developer.wordpress.org/reference/

Laravel and helper collisions

Laravel ships with its own helpers like abort(), config(), and view(). If a custom package or legacy codebase defines a global function with the same name, you can hit a fatal error as soon as Composer autoloads both.

A typical example:

// file: legacy/helpers.php
<?php
function abort($code) {
    // Old custom behavior
}

Once you upgrade to a modern Laravel version that defines its own abort() helper, your next request dies with Cannot redeclare abort(). This is one of those real examples of duplicate function definition errors in PHP that only appears during framework upgrades.

Symfony and third‑party polyfills

Symfony’s polyfill packages add missing PHP functions for older versions. If your app or another library ships its own polyfills for the same functions without function_exists guards, you can get duplicate function definition errors when running on older PHP versions.

The trend in 2024–2025 is clear: frameworks and major libraries lean heavily on namespaces, classes, and guarded polyfills to avoid these collisions. The remaining risk usually comes from older, global‑function‑heavy code.

Practical debugging: how to track down duplicate function definitions

When you hit a Cannot redeclare error, PHP actually gives you a decent breadcrumb trail:

Fatal error: Cannot redeclare format_price() (previously declared in /var/www/app/helpers.php:3) in /var/www/app/more_helpers.php on line 5

That message tells you where the function was first declared and where PHP is trying to redeclare it. Real‑world debugging usually looks like this:

• Open both files and confirm the function signatures.
• Search the codebase for the function name to make sure there aren’t even more copies.
• Check your composer.json for autoload.files entries that might be pulling in extra helpers.
• Replace require/include with require_once/include_once where appropriate.
• If the function is library code, consider namespacing it or moving logic into a class.

Static analysis tools like PHPStan and Psalm can also catch many of these issues before runtime by flagging multiple declarations in the same project. While these tools are often discussed in the context of type safety, they’re also good at surfacing structural problems like repeated symbols.

For a broader perspective on debugging practices and error handling in software, the US National Institute of Standards and Technology (NIST) has long emphasized defensive coding and rigorous testing, even though their publications are language‑agnostic: https://www.nist.gov/

Preventing duplicate function definition errors in new and legacy code

Looking across all these real examples of duplicate function definition errors in PHP, some patterns emerge.

In new code:

• Avoid global functions for anything beyond very narrow, project‑local helpers.
• Prefer namespaced functions or static class methods.
• Keep Composer’s autoload.files list short and audited.
• Use function_exists only for polyfills or framework‑sanctioned override points.

In legacy code:

• Standardize on require_once and include_once for shared files.
• Consolidate scattered helper files into a single, namespaced library.
• When modernizing, watch for collisions with framework helpers and PHP core functions added in new versions.

These habits don’t just prevent one type of bug; they make your codebase easier to reason about. The same structural discipline that avoids duplicate function definition errors also reduces security risks, makes refactoring safer, and improves testability.

FAQ: common questions and examples

What is an example of a duplicate function definition error in PHP?

A simple example is two files that both define the same global function and are both included:

// a.php
function foo() { return 'A'; }

// b.php
function foo() { return 'B'; }

// index.php
require 'a.php';
require 'b.php';

Running index.php triggers Fatal error: Cannot redeclare foo() because foo() is defined twice in the global namespace.

How do I avoid duplicate function definition errors when using third‑party libraries?

Stick to libraries that use namespaces and avoid global helpers, or at least review their helper files before adding them. If you see overlapping function names between two packages, you have a high risk of running into the kinds of examples of duplicate function definition errors in PHP we walked through above.

Can namespaces completely prevent duplicate function definition errors in PHP?

No. Namespaces prevent collisions between namespaced functions, but you can still get errors if you define the same function twice in the same namespace, or define a global function twice. Namespaces are a strong tool, not a magic shield.

Is using function_exists always safe?

It’s safe in the sense that it avoids the fatal error, but it can hide design problems. If you have multiple guarded definitions of the same function across your codebase, the behavior you get depends on which file loads first. That kind of implicit behavior can be harder to debug than a straightforward duplicate function definition error.

Do newer PHP versions (8.x) change how duplicate function errors work?

The core behavior — throwing a fatal error on a second definition — is the same. What changed is the surface area for collisions. As PHP adds more built‑in functions over time, older code that defined polyfills without function_exists guards can suddenly start throwing errors after an upgrade. Those are subtle, version‑driven examples of duplicate function definition errors in PHP that show up during modernization efforts.