Invade Laravel Package

Getting Started

Install with composer require spatie/invade. The package exposes a single global function invade() that bypasses PHP’s visibility modifiers—enabling read/write access to private properties and invocation of private methods on objects or classes.

First use case: Write a unit test for legacy code where internal state isn’t exposed publicly. Use invade($service)->currentState to assert the internal state without modifying the class.

use function Spatie\Invade\invade;

// Object instance: read/write properties
$object = new MyClass();
$state = invade($object)->privateProperty;
invade($object)->privateProperty = 'new value';

// Static context: use `get()`, `set()`, and `method()`
$staticValue = invade(MyClass::class)->get('staticProp');
invade(MyClass::class)
    ->method('privateStaticMethod')
    ->call('arg1', 123);

Start by checking tests/ for patterns—most usage lives in testing, debugging, or integration workarounds.

Implementation Patterns

• Testing internal state: In unit/integration tests, verify private properties that drive behavior without over-coupling tests to public methods. Ideal for complex stateful services (e.g., workflow engines, calculators).

  $sut = new ComplexService();
  invade($sut)->validationErrors = ['error' => 'test'];
  $this->assertTrue(invade($sut)->hasErrors());
  

• Debugging production issues: Temporarily inspect private state in non-critical paths (e.g., logs, dev tools). Never leave invade in production business logic.
• Integrating with closed-source or third-party libraries: When libraries lack required public hooks (e.g., mocking incomplete SDKs), use invade sparingly and encapsulate it behind a test-only helper.
• PHPStan/IDE integration: The package ships with a PHPStan extension. Enable it via phpstan.neon:

  includes:
      - vendor/spatie/invade/extension.php
  

  This suppresses false positives when accessing invade()’s returned proxy.

Gotchas and Tips

• Static vs. instance handling: For static properties/methods, pass the class name (invade(MyClass::class)), not an object instance. Static access uses get()/set()/method() APIs—direct property access fails silently on static members.
• No reflection in v2+: Post-2.0, invade() uses ReflectionProperty::setValue() and Closure::bind() without instantiating Reflection classes manually—more reliable but still incurs overhead. Avoid in hot paths.
• Type hinting pitfalls: PHPStan/IDEs won’t infer types on invade($obj)->privateProp—always cast or document the expected type. Consider:

  /** @var string $value */
  $value = invade($obj)->privateProp;
  

• Encapsulate usage: Wrap invade calls in test helpers (e.g., PrivateAccessor::get($obj, 'prop')) to centralize future refactoring and avoid scattering low-level calls.
• Security caveat: While safe for testing/debugging, invade() does not sanitize inputs. Avoid passing untrusted strings to property/method names (e.g., invade($obj)->{$_GET['prop']}).
• Static property getters/setters require exact keys: invade(MyClass::class)->get('prop') only works for existing static properties. Private static methods require method('methodName')—no magic __get/__call support.