Weave Code
Monkey Laravel Package
brain/monkey
Brain Monkey is a PHP testing library for mocking and spying on global functions and class methods, with seamless PHPUnit integration and no dependencies—ideal for testing legacy code, WordPress plugins, and function-heavy PHP applications.
Mocking utility for PHP functions and WordPress plugin API
Frequently asked questions about Monkey
- Is Brain Monkey a Laravel package or a WordPress testing tool?
- No. Brain Monkey is a PHP testing library for WordPress plugins and themes, built on Mockery and integrated with PHPUnit; it is not a Laravel package and has no Laravel-specific API. Use it in a Laravel project only when the test suite covers legacy WordPress code or procedural PHP that calls global functions you cannot inject. For Laravel application code, use the container, facades, Http::fake(), Queue::fake(), and plain Mockery instead.
- How do I install Brain Monkey in a Laravel project with Composer?
- Install it as a dev dependency with composer require --dev brain/monkey. In a Laravel project, keep it out of production requirements and initialize it only in test suites that need WordPress function or hook mocking. The setup API is small: Monkey\setUp() and Monkey\tearDown(), plus Functions\expect/when, Actions\expectAdded, Filters\expectApplied, and Hooks\did_action. Make sure Brain Monkey is initialized before the code under test is loaded.
- Does Brain Monkey work with PHPUnit and Mockery in a Laravel test suite?
- Yes. Brain Monkey is built on Mockery and provides PHPUnit setup/teardown helpers, so it fits suites already using Mockery. In a Laravel test suite it will coexist with Laravel's fakes and Mockery, but keep the two concerns separate: use Laravel fakes for framework services and Brain Monkey only for WordPress-style global functions and hooks. Verify the Mockery version constraint at pin time because 2.7.0 tightened it.
- Which PHP versions does Brain Monkey support, including PHP 8.4 and 8.5?
- Brain Monkey is not coupled to a Laravel version; its constraints are PHP, PHPUnit, and Mockery. Release 2.7.0 confirms PHP 8.4 and 8.5 compatibility, which removes part of the version-support uncertainty for modern CI matrices. You still need to verify the tightened Mockery constraint and your PHPUnit version in your own composer.lock before adopting it.
- How do I mock WordPress functions such as get_option or wp_remote_get with Brain Monkey?
- Use Functions\expect('get_option')->with(...)->andReturn(...) when you need an expectation, or Functions\when('get_option')->justReturn(...) for a simple stub. The same pattern applies to wp_remote_get, wp_schedule_event, time, file_get_contents, and other global or namespaced function calls. Brain Monkey 2.x intercepts function calls by rewriting files at include time, so the mock setup must happen before the file containing the call is loaded. Be careful with justReturn(null) defaults, which can let a test pass while production behavior diverges.
- Can Brain Monkey assert that WordPress actions and filters were added, applied, or executed?
- Yes. Brain Monkey provides Actions\expectAdded, Filters\expectApplied, Hooks\did_action, and related helpers for asserting WordPress hook behavior without loading WordPress. In 2.7.0, has_filter() and has_action() mocks accept a $priority argument, so you can assert that a callback was registered at priority 20 instead of asserting nothing. That closes a real assertion gap for common hook patterns and tracks WordPress 6.9 behavior.
- Why do Brain Monkey tests fail when a function is already defined or code loads too early?
- Brain Monkey 2.x works by intercepting function calls and rewriting files at include time, so it must be initialized before the code under test is loaded. Functions in files that are already loaded cannot be redefined, which produces confusing failures rather than a clear error. Put Monkey\setUp() in your PHPUnit bootstrap or early test setup, and load the code under test after that point. This is a read-the-docs-once constraint, but violating it silently breaks mocks.
- Can I test WordPress plugins without loading WordPress or a database?
- Yes. Brain Monkey mocks WordPress functions and hooks without a WordPress bootstrap or database, so tests stay fast and isolated. That makes it practical to unit-test plugin or theme code that calls get_option, wp_remote_get, add_action, apply_filters, and similar APIs. It does not replace integration or end-to-end tests against a real WordPress install; it replaces the need to load WordPress for unit-level isolation.
- What are the alternatives to Brain Monkey for WordPress and Laravel testing?
- Brain Monkey is the modern successor to the 10up/wp_mock pattern and is the de-facto standard in the WordPress plugin ecosystem, used by projects such as WP-CLI and Yoast or their conventions. For WordPress-oriented unit tests, its main alternatives are wp_mock-style libraries, handwritten function stubs, or running a full WordPress test environment. For Laravel application code, the better alternatives are Laravel's container, facades, Http::fake(), Queue::fake(), and plain Mockery, because Brain Monkey solves global-function and hook mocking rather than framework service faking.
- Is Brain Monkey dev-only, and what CI risks should I check before upgrading to 2.7.0?
- Brain Monkey is a dev-only dependency: install it with composer require --dev brain/monkey and do not ship it as production runtime code. Upgrading from 2.6.x to 2.7.0 is a drop-in, non-breaking patch-level bump, but the mock default alignment for doing_action(), doing_filter(), do_action_deprecated(), apply_filters_deprecated(), has_filter(), and has_action() can turn existing green tests red if they were written against the old incorrect defaults. The main residual CI risk is the stream-wrapper/opcache interaction: code-coverage drivers, opcache.preload, and some CI container images are known friction points, so prove it in your CI rather than assuming it works.
Weaver
How can I help you explore Laravel packages today?