phpunit - mockbuilder - set mock object internal property

phpunit - mockbuilder - set mock object internal property

  1. Blog
  2. 15 November 2026
  3. 2 min read

Stefan Bogdanescu

Founder & Senior Architect

Mocking Protected Properties in PHPUnit: A Practical Guide

When testing a class that relies on protected state, standard mocking strategies often hit a wall. Consider a scenario where you have a class A that initializes a protected property $p in its constructor and guards logic based on its value. If you attempt to mock this class using PHPUnit's getMockBuilder while disabling the original constructor, you successfully bypass the initialization logic. However, accessing the internal state remains problematic because PHP does not allow direct assignment to protected properties from outside the class hierarchy.

The core issue in the example provided is that $mockA->p = 2; will trigger a fatal error regarding inaccessible property. Simply adding a public setter like setP() changes the interface of the class under test, which violates the principle of testing implementation details without altering them. If you are aiming to verify that the exception is thrown specifically when $p equals 2, injecting that value directly into the protected property requires a specific PHPUnit feature: reflection.

PHPUnit provides a reflection helper method on the mock builder that allows you to access and manipulate internal state safely. You can call setMethod on the mock object instance to retrieve a reflection of the protected property, then use that to assign a new value. This approach keeps your test isolated; it does not modify the source code of class A nor does it require adding setters or changing the constructor signature.

Here is how you can implement this pattern in a modern PHPUnit setup:

public function testBlahShouldThrowExceptionBy2PValue()
{
    $mockA = $this->getMockBuilder('A')
        ->disableOriginalConstructor()
        ->getMock();

    // Access the protected property via reflection
    $pProperty = new ReflectionProperty($mockA, 'p');
    $pProperty->setAccessible(true);
    
    // Set the value
    $pProperty->setValue($mockA, 2);

    $this->expectException(Exception::class);
    $mockA->blah();
}

This solution works because ReflectionProperty bypasses PHP's visibility modifiers. By calling setAccessible(true), you explicitly tell the reflection API to ignore the protected keyword for that specific instance. This is the standard, non-invasive way to inject state into a mock when no public interface exists.

There are trade-offs to consider with this approach. While powerful, relying on reflection makes tests brittle against refactoring. If the property name changes in class A, the test will fail immediately unless you implement dynamic string handling or use annotations. Furthermore, if the protected property is initialized inside a constructor that you disabled, ensure that no other side effects occur during construction that your mock needs to simulate.

In larger projects, especially those using dependency injection containers like Laravel, this pattern is less common because the application layer typically exposes setters or uses constructor injection for state management. However, when dealing with legacy code or third-party libraries where you cannot modify the source, reflection remains a valid tool in the PHPUnit arsenal. It allows you to verify internal logic without forcing a refactor, provided you accept that these tests are tightly coupled to the current implementation of the class under test.

Our network