Side Effects Detector Laravel Package

Getting Started

Start by installing the package via Composer: composer require staabm/side-effects-detector. Begin with the basic use case—detecting if a snippet of PHP code (e.g., from a test case or user input) has observable side effects before evaluating it with eval(). The simplest intro is analyzing PHPUnit’s PHPT test snippets: load code, run getSideEffects(), and check the returned list of SideEffect::CONSTANT values. For example, SideEffect::STANDARD_OUTPUT for echo/printf, SideEffect::PROCESS_EXIT for exit(), or SideEffect::SCOPE_POLLUTION for include/global usage.

Implementation Patterns

• Code Evaluation Sandboxing: Use the detector to decide whether to run arbitrary code in-process (with output buffering and isolated closures) or spawn a subprocess for safety.
• Test Optimization: In testing frameworks (e.g., PHPUnit), skip subprocesses for side-effect-free code (e.g., pure expressions or functions known to be side-effect-free), drastically speeding up PHPT test suites.
• Streaming Filters: When accepting user-provided code (e.g., config snippets), classify and reject dangerous side effects (PROCESS_EXIT, SCOPE_POLLUTION) while allowing harmless ones (STANDARD_OUTPUT captured via ob_start).
• Composable Filtering: Build permissive/denial lists by checking in_array($effect, $allowedEffects) to support custom policies (e.g., allow STANDARD_OUTPUT but not EXTENSION_LOAD).

Gotchas and Tips

• null return means unknown side-effect (e.g., userland function calls) — treat as SideEffect::MAYBE and default to safest behavior (e.g., subprocess).
• Side-effect detection is static; it doesn’t inspect attributes, PHPDoc, or runtime behavior—misclassifying trigger_error as unknown (1.0.4+) or vprintf/printf as STANDARD_OUTPUT (1.0.2/1.0.3+), but relies on internal function mapping.
• Output buffering does not prevent all output (e.g., fwrite(STDOUT, ...), header() calls), so combine STANDARD_OUTPUT detection with defensive ob_start() and warn users about limitations.
• Scope pollution (include, global, class/func autoloading) can’t be fully neutralized in-process—subprocess isolation remains the only reliable way.
• Use the test suite as the canonical reference for supported cases, as it’s more up-to-date than the README.