RFC: Context Config Flags for Safe Breaking Changes

[TheoD02]

Problem

Castor needs a safe way to introduce breaking changes (like ContextAwareFilesystem) without breaking existing code.

Right now, there’s no easy way to:

• Let users opt in to new behavior gradually
• Configure features per context
• Keep backward compatibility during transitions

---

Goal

Create a context-based configuration system that lets Castor:

1. Add new features or change feature behind flags
2. Default to old behavior for existing users
3. Warn when defaults will change in the future
4. Allow internal code to adapt automatically

---

Example

Context declaration

#[AsContext()]
function context(): Context
{
    return new Context(
        config: (new Config())
            // Similar fluent API like Context::with*()
            ->withEnabled(ConfigFlag::ContextAwareFilesystem)
            ->withDisabled(ConfigFlag::AnotherFlag, ConfigFlag::FutureFlag)
    );
}

Usage in code

function fs(?Context $context = null): Filesystem|ContextAwareFilesystem
{
    $container = Container::get();
    $context ??= $container->contextRegistry->getCurrentContext();

    // Config ìsEnabled` will trigger the warning if the value is null
    //      Configuration flag "{EnumKey}" is not set and defaults to {true|false}.
    //      This default will change to {true|flase} in version 2.0. 
    //      Please explicitly configure this flag in your Context config to avoid breaking changes.
    //
    if ($context->config->isEnabled(ConfigFlag::ContextAwareFilesystem)) {
        return new ContextAwareFilesystem(
            $container->fs,
            $context->workingDirectory,
        );
    }

    return $container->fs;
}

---

Config Flags

enum ConfigFlag
{
    case ContextAwareFilesystem;

    public function description(): string
    {
        return match ($this) {
            self::ContextAwareFilesystem =>
                'Context-aware filesystem with automatic path resolution',
        };
    }

    public function willBeDefaultInVersion(): string
    {
        return match ($this) {
            self::ContextAwareFilesystem => '2.0',
        };
    }

    public function defaultValueWhenNull(): bool
    {
        return match ($this) {
            self::ContextAwareFilesystem => false,
        };
    }
}

---

Summary

This proposal introduces context-aware config flags so Castor can evolve safely.
It allows developers to opt in to new features while maintaining stable defaults and clear upgrade paths.