Make ecs.php extensible instead of fully replaceable

[coisa]

Description

Problem

Currently, the ecs.php configuration file is treated as a fully replaceable artifact. Any customization requires copying and maintaining a complete version of the file in the consumer project.

This approach introduces several issues:

• Duplication of configuration: users must copy the entire base configuration even for small changes
• Drift from upstream: updates to the original ecs.php are not automatically propagated
• Maintenance overhead: keeping custom configs aligned with the repository becomes error-prone
• Poor composability: no way to incrementally extend or override behavior

Proposed Solution

Allow ecs.php to be extensible instead of replaceable, enabling users to build on top of the base configuration.

Possible approaches:

1. Require + extend pattern

Expose the base configuration in a reusable way:

$ecsConfig = require __DIR__ . '/vendor/fast-forward/dev-tools/ecs.php';

$ecsConfig
    ->withRules([
        // project-specific rules
    ]);

return $ecsConfig;

This allows consumers to reuse the default configuration and only append/override what is necessary.

2. Config factory / builder method

Provide a method that returns a preconfigured ECSConfig instance:

use FastForward\DevTools\Config\EcsConfigFactory;

return EcsConfigFactory::create()
    ->withRules([
        // overrides
    ]);

This avoids direct file coupling and enables version-safe extensions.

3. CLI-level extensibility

Allow passing additional configuration via CLI arguments:

composer code-style --extra-config=ecs.custom.php

Where ecs.custom.php augments the base configuration.

4. Layered configuration support

Support multiple config files that are merged in order:

return ECSConfig::merge([
    __DIR__ . '/vendor/.../ecs.php',
    __DIR__ . '/ecs.override.php',
]);

Expected Behavior

• Users SHOULD be able to extend the default configuration without copying it entirely
• Upstream updates to ecs.php SHOULD automatically apply unless explicitly overridden
• The system SHOULD support additive and override-based customization

Benefits

• Eliminates duplication
• Reduces maintenance burden
• Improves upgrade safety
• Enables composable configuration
• Aligns with best practices seen in tools like Symfony, PHP-CS-Fixer, and Rector

Additional Context

This becomes especially relevant when integrating additional rule sets (e.g. security sniffs like phpcs-security-audit - PR #5), where users only want to append rules without redefining the entire configuration.

This becomes especially relevant when integrating additional rule sets (e.g. security sniffs like phpcs-security-audit), where users only want to append rules without redefining the entire configuration.