Array Merge Recursive Laravel Package

Product Decisions This Supports

• Config-resolution architecture. Every layered configuration story (package defaults → environment → tenant → user override) requires an explicit answer to "what happens when both layers set the same nested key?" PHP's built-in array_merge_recursive answers "turn the scalar into an array and append," which is almost never what a product wants. This package answers "last writer wins, recursively." Choosing that semantic explicitly is a product decision, not just a technical one — it determines whether a tenant override replaces or pollutes a default.
• Build vs. buy on the utility tier. The capability is a ~30–50 line function. This package is best evaluated as a reference implementation and a naming decision, not as a dependency to adopt. It informs the threshold policy for "how small does a library have to be before we just write it ourselves?"
• Concrete feature surfaces it unlocks: multi-tenant settings and preference overrides, theming/design-token cascades, feature-flag payload composition, nested PATCH/PUT request merging, and package default-config overrides in service providers.
• Supply-chain risk budget. With 7 stars, 0 dependents, a last release in April 2021, and a WTFPL license, this is a live example for calibrating what level of abandonment risk is acceptable for leaf-node utilities.
• Framework-primitive consolidation. For a Laravel-first product this is largely a non-decision: Arr::merge already implements replace-style deep merge, and has for years. The PM-relevant output is "standardize on the framework primitive and document it," which removes a category of inconsistency from code review.

When to Consider This Package

Consider it when:

• You are on non-Laravel or legacy PHP and are repeatedly bitten by array_merge_recursive wrapping scalars into arrays.
• The need is genuinely leaf-level: one merge semantic, no conflict-policy matrix, no performance sensitivity on large nested payloads.
• You are comfortable vendoring or forking the logic instead of taking a composer require, given the maintenance signal.
• The merge behavior is already pinned by your own test suite, so an unmaintained dependency cannot silently change semantics under you.

Look elsewhere when:

• You are in a Laravel app — Arr::merge covers this; adding a dependency is pure overhead.
• You need maintained third-party code, security response, or PHP 8.3+/future version guarantees.
• You need configurable conflict strategies (keep-first, keep-last, append-to-lists, custom callbacks) or list/collection merge semantics. This package is a fixed policy, not a merge engine.
• Your legal/procurement review flags WTFPL — it is effectively public domain, but it is not OSI-approved and some compliance pipelines will stop it on sight.
• You need typed objects, immutability, or schema-validated merges rather than raw arrays.

How to Pitch It (Stakeholders)

To executives: This is a small, free utility that fixes a specific and recurring class of configuration bug — the kind where a tenant's override silently turns a setting into a list instead of replacing it. It is not a platform investment and should not appear on a roadmap. The recommendation is almost certainly not to adopt the package, but to adopt its one-line semantic decision (replace, don't append) as a documented standard. Cost: near zero. Risk: near zero. Benefit: fewer subtle environment-specific defects and faster diagnosis when configs disagree.

To engineering: The library is a drop-in replacement for array_merge_recursive with replace semantics. Before adding it: if we're on Laravel, Arr::merge already does this and we should use it and say so in the style guide. If we're not, vendor a small internal helper with tests rather than pulling in a 2021-abandoned package with zero dependents and an unusual license. Either way, write the merge contract down — "nested keys are replaced, not appended, at every depth" — and cover it with a test, because that sentence is the actual deliverable here.