Oihana PHP

requireAndMergeArrays.php

Table of Contents

Functions

requireAndMergeArrays()  : array<string|int, mixed>
Requires multiple PHP files (each returning an array) and merges the results.

Functions

requireAndMergeArrays()

Requires multiple PHP files (each returning an array) and merges the results.

requireAndMergeArrays(array<string|int, mixed> $filePaths[, bool $recursive = true ][, string|null $allowedBase = null ][, int|null $maxBytes = null ]) : array<string|int, mixed>

Each path goes through a defensive validation pipeline before require:

  1. The path must be a non-empty string.
  2. It must resolve via realpath() to an existing regular file.
  3. The file extension must be .php (case-insensitive).
  4. If $allowedBase is provided, the resolved file must be located inside that base directory (defense in depth against path-escape attacks).
  5. If $maxBytes is provided, the file size must be ≤ $maxBytes (defensive cap against parser OOM on extremely large config files).

This protects against arbitrary file inclusion when paths come from untrusted or semi-trusted sources. Note that even with $allowedBase, callers must still trust the content of the included files — require executes their PHP code.

Parameters
$filePaths : array<string|int, mixed>

An array of file paths to load.

$recursive : bool = true

Whether to perform a deep (recursive) merge (true) or a simple merge (false).

$allowedBase : string|null = null

Optional absolute directory path. When provided, every file in $filePaths must be located inside this directory after canonicalisation. Strongly recommended when paths are not 100% trusted at the call site.

$maxBytes : int|null = null

Optional per-file size cap (in bytes). When provided, any file whose size exceeds this limit is rejected before being included, throwing RuntimeException. Default null (no limit — historical behaviour).

Tags
throws
InvalidArgumentException

If $allowedBase is provided but does not resolve to a valid directory.

RuntimeException

If a path is not a non-empty string, does not resolve to an existing .php file, escapes $allowedBase, exceeds $maxBytes, or does not return an array.

example 
use function oihana\files\requireAndMergeArrays;

$paths = [
    __DIR__ . '/config/default.php',
    __DIR__ . '/config/override.php',
];

// Basic usage — relies on the caller to trust $paths.
$config = requireAndMergeArrays($paths);

// Shallow merge.
$config = requireAndMergeArrays($paths, false);

// Hardened usage — every file must be under __DIR__/config.
$config = requireAndMergeArrays($paths, true, __DIR__ . '/config');

// With a per-file size cap (defensive — 1 MiB max per config file).
$config = requireAndMergeArrays($paths, true, __DIR__ . '/config', 1024 * 1024);

Example of a required file:

// config/default.php
return [
    'app' => [
        'debug'    => false,
        'timezone' => 'UTC',
    ],
];
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
array<string|int, mixed> —

The merged array.

On this page

Search results