Hard Mode Laravel Package

Getting Started

• Install via Composer: composer require --dev mnapoli/hard-mode
• Add HardMode::enable(); early in your bootstrap (e.g., in public/index.php or a dedicated bootstrap/hard-mode.php loaded before application boot)
• Start with defaults — it enforces rules like strict types, no implicit array-to-string conversions, no silent null-to-string coercion, and throws exceptions for undefined array keys on read/write
• First use case: run your test suite. Expect failures where loose PHP behaviors previously masked bugs — e.g., accessing $arr['missing_key'] without isset(), or string concatenation with null.

Implementation Patterns

• Bootstrap-level activation: Wrap HardMode::enable() in an environment-gated block (e.g., if ($env === 'local' || $env === 'ci')) to avoid breaking production if misconfigured, or use it permanently in non-production environments only.
• Gradual roll-out: Enable only specific rules using configuration (e.g., HardMode::enable(['strictTypes' => true, 'nullToCoercible' => true])) if全量 activation is too aggressive for legacy code.
• With static analysis: Pair with PHPStan or Psalm — HardMode catches runtime issues, while static tools catch type mismatches before runtime. This combo creates a layered defense.
• With testing: Use in TDD workflows — write tests first expecting strict exceptions (e.g., HardMode\RuntimeException), then fix code to be explicit (e.g., add null checks, typed parameters).
• CI integration: Run tests with HardMode enabled in CI to prevent fragile patterns from reaching production.

Gotchas and Tips

• Silent deprecation: Some rules (e.g., notice → exception for array access on undefined keys) may break legacy code unexpectedly; use in staging/CI first, not production.
• Error messages: Exceptions are generic (e.g., Undefined array key "foo" as exception); use stack traces or structured logging to trace problematic lines. Consider custom ErrorHandler if needed for nicer reporting.
• Configuration: The package does not support detailed per-rule toggling in v0.x — full enable/disable only. Check repository for newer versions or fork for granular control if your project needs it.
• Compatibility: Avoid enabling in projects using loosely-typed legacy libs (e.g., old Symfony <4 components). Test dependencies first — some may fail silently in standard PHP but break under HardMode.
• Extension point: Override default behavior by catching and logging exceptions manually (e.g., in a custom set_exception_handler()), turning HardMode into a reporting layer rather than a hard blocker.
• Legacy tip: For large codebases, temporarily suppress known-safe violations using @ operator only as a last resort and file technical debt tickets to fix them explicitly.