Skip to content

ADR-002-zero-external-dependencies.md

Latest commit

 

History

History
46 lines (30 loc) · 2.1 KB

ADR-002-zero-external-dependencies.md

File metadata and controls

46 lines (30 loc) · 2.1 KB

ADR-002: Zero External Dependencies

Status: Accepted Date: 2025-12-15 Authors: Walmir Silva walmir.silva@kariricode.org

Context

Class discovery is a foundational operation — it runs before the DI container, before the router, before event listeners are registered. Any dependency on external packages introduces:

  1. Circular risk: If ClassDiscovery depends on Package X, and Package X uses ClassDiscovery for its own bootstrapping, we have a circular dependency.
  2. Version conflict: Consumer projects may require different versions of shared dependencies.
  3. Attack surface: Each dependency is a supply-chain vector.
  4. Bootstrap ordering: Discovery must work before Composer's autoloader finishes loading all packages.

The KaririCode Framework follows a zero-external-dependency policy for core infrastructure components (ARFA 1.3 §4.2).

Decision

ClassDiscovery depends exclusively on PHP 8.4+ standard library. Integration with external systems (PSR-16 cache, PSR-11 container, Configurator) is provided via optional bridge classes that type-hint object with PHPStan annotations.

Consequences

Positive:

  • Zero Composer conflicts — installs cleanly in any project
  • No supply-chain risk from transitive dependencies
  • Bootstrap-safe: works before any autoloader or container is configured
  • Package size: minimal (33 files, ~2.8k lines)

Negative:

  • Bridge classes use object typing instead of interface typing for PSR-16/PSR-11
  • Must reimplement utilities that packages like symfony/finder provide (directory traversal, glob matching)
  • Cache implementations cannot leverage existing cache backends without bridge setup

Mitigations:

  • @phpstan-param annotations provide static analysis coverage for bridge classes
  • composer.json suggest section documents optional integrations
  • Built-in cache strategies (Memory, File, Chain) cover 95% of use cases without external packages

References

  • Martin, R. C. (2017). Clean Architecture, Ch. 14 — Component Cohesion.
  • ARFA 1.3 Specification §4.2 — Zero External Dependencies for Infrastructure Components.