Strategy — Explicit Over Magic

When to use

• The task asks for clear, readable, maintainable code, or the code will be read and extended by a team over time.
• The task is to untangle or clarify code that currently relies on magic methods, global state, or clever indirection.
• The design is tempted to use dynamic properties, __call, __get, or global state to avoid writing out explicit members.

When NOT to use

• Do not fight a framework's own well-documented magic — such as an ORM's dynamic attributes — when using it is the established, expected idiom.
• Do not impose full explicitness ceremony on a tiny throwaway script that will run once and never be read again.

Core guidance

• Declare real properties instead of dynamic ones — Declare each property the class uses with a type, rather than assigning arbitrary dynamic properties at runtime.
• Keep control flow visible and traceable — Keep control flow explicit — return values, thrown exceptions, and direct calls — rather than triggering behavior through hidden hooks or side-effectful magic getters.
• Inject dependencies instead of reaching for globals — Pass dependencies in through the constructor or method parameters rather than reaching for global variables, static singletons, or superglobals inside the body.
• Name things after intent, not mechanism — Give variables, methods, and classes names that state what they mean, and prefer a slightly longer obvious construct over a terse clever one.
• Write named methods instead of __call routing — Write out the methods a class supports as real named methods rather than routing unknown calls through __call or __callStatic.

Never

• Never introduce dynamic properties, __call, or global state to save a few lines when an explicit property, method, or dependency would read clearly.

Prefer

• Prefer declared properties, named methods, and passed-in dependencies so a reader can follow the data and control flow without running the code.

Avoid

• Avoid global variables, singletons, and magic methods that let distant code change behavior invisibly; make every dependency and side effect visible at the call site.

Escalate to user when

• Escalate to the user when a requirement seems to genuinely need a magic mechanism — a proxy, an ORM's __get, or a framework macro — and confirm the trade-off before relying on it.

Quick recipe

1. Identify each magic mechanism in the code — dynamic properties, __call, globals, side-effectful accessors — and note the concrete members or dependencies it stands in for. (verify: You have a list of each magic point and the explicit property, method, or parameter it should become.)
2. Replace each magic point with a declared property, a named method, or an injected dependency, and confirm behavior is unchanged with the existing tests. (verify: No dynamic property, __call route, or global read remains where an explicit member now exists, and the tests still pass.)

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Global state makes behavior order-dependent — Reading and writing global or static state makes a function's result depend on what ran before it, not just its arguments. Fix: Pass the needed state in as parameters or injected dependencies so each call is self-contained and reproducible.
2. __call hides the real API from tooling — Routing calls through __call means the class's real methods are invisible to autocomplete, refactoring tools, and static analysis. Fix: Declare each supported method explicitly; if a large surface must be generated, emit real method stubs rather than dispatching through __call.
3. A typo silently creates a new dynamic property — With dynamic properties, a misspelled assignment quietly creates a new property instead of raising an error. Fix: Declare properties explicitly so a misspelled name is a clear error, and enable strict property handling where the runtime supports it.

Version notes

• Explicit-over-magic discipline is version-agnostic (PHP >=7.4) — Preferring explicit code over magic is a strategy that applies to any PHP version; it constrains which mechanisms the agent leans on, not which language features exist, so it holds from PHP 7.4 upward.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/ai-rules/strategy-explicit-over-magic.yaml.

Additional resources

• references/anti-patterns.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: ai-rules/strategy-minimal-diff, php/typed-properties