Laravel Spy

To customize the behavior of Laravel Spy, you must first publish its configuration file to config/spy.php using the Artisan command.

php artisan vendor:publish --provider="Farayaz\LaravelSpy\LaravelSpyServiceProvider"

Laravel Spy provides a Docker-based testing suite that allows you to run the full PHPUnit test suite without needing PHP installed on your local machine.

Recommended Method

The easiest way to run the tests is using the provided shell script:

./run-tests.sh

Alternative Methods

Using Docker Compose:

docker-compose up --build

Manual Docker Commands: If you need to perform individual steps manually, follow this sequence:

1. Build the image: docker build -t laravel-spy-test .
2. Install dependencies: docker run --rm -v "$(pwd)":/var/www laravel-spy-test composer install
3. Run tests: docker run --rm -v "$(pwd)":/var/www laravel-spy-test vendor/bin/phpunit

When upgrading Laravel Spy, you must re-publish the package's configuration and migrations to ensure your local files are synchronized with the latest version. Use the --force flag to overwrite existing files.

php artisan vendor:publish --provider="Farayaz\LaravelSpy\LaravelSpyServiceProvider" --force

Install the package via Composer. The package uses Laravel's auto-discovery feature. After installation, publish the configuration provider and run the migrations to create the necessary http_logs table in your database.

composer require farayaz/laravel-spy
php artisan vendor:publish --provider="Farayaz\LaravelSpy\LaravelSpyServiceProvider"
php artisan migrate

If you prefer to selectively spy on specific Guzzle clients, or if you are manually instantiating clients using new Client(), use Manual Mode.

1. Set SPY_GUZZLE_ENABLED=false to disable automatic container binding.
2. Attach the spy middleware to your specific client instance using LaravelSpy::handlerStack() within the Guzzle configuration options.

SPY_GUZZLE_ENABLED=false

use Farayaz\LaravelSpy\LaravelSpy;
use GuzzleHttp\Client;

// Spy enabled only on this specific client instance
$client = new Client([
    'handler' => LaravelSpy::handlerStack(),
]);
$client->get('https://www.google.com?1');

Once installed, Laravel Spy automatically intercepts and logs outgoing HTTP requests made via Laravel's Http facade or Guzzle. For every request, it captures:

• Full URL
• HTTP method (e.g., GET, POST, PUT)
• Request Headers
• Request Body
• Response Headers
• Response Body
• Response HTTP Status code
• Request duration (milliseconds)

Logs are stored in the http_logs database table.

Http::get('https://github.com/farayaz/laravel-spy/');

By default, Laravel Spy can automatically intercept Guzzle requests if they are resolved through the Laravel service container. To enable this, set the SPY_GUZZLE_ENABLED environment variable to true.

Crucial Limitation: Auto mode only works for clients instantiated via the container (e.g., using app(Client::class) or via Dependency Injection in constructors). It will not work for clients created using the new Client() syntax.

SPY_GUZZLE_ENABLED=true

// Via app() helper
use GuzzleHttp\Client;
$client = app(Client::class);
$client->get('https://www.google.com');

// OR via Dependency Injection
public function __construct(protected Client $client) {}

public function index() {
    $this->client->get('https://www.google.com');
}

If you want to customize the dashboard's user interface, you can publish the package's views directly into your application's resources directory using the following Artisan command:

php artisan vendor:publish --tag=spy-views

You can target specific parts of the test suite by passing the path to the PHPUnit command within the Docker container.

Run only unit tests:

docker run --rm -v "$(pwd)":/var/www laravel-spy-test vendor/bin/phpunit tests/Unit

Run only feature tests:

docker run --rm -v "$(pwd)":/var/www laravel-spy-test vendor/bin/phpunit tests/Feature

Run a specific test file:

docker run --rm -v "$(pwd)":/var/www laravel-spy-test vendor/bin/phpunit tests/Unit/LaravelSpyTest.php

Run with coverage (requires xdebug):

docker run --rm -v "$(pwd)":/var/www laravel-spy-test vendor/bin/phpunit --coverage-html coverage

The Docker-based testing setup is designed for easy integration into CI/CD pipelines. You can use the run-tests.sh script within a GitHub Actions workflow to ensure consistent testing environments.

Example Workflow Configuration:

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run tests
        run: ./run-tests.sh

To enable the lightweight dashboard for browsing HTTP logs, add the following environment variables to your .env file. By default, the dashboard will be accessible at the /spy path.

SPY_DASHBOARD_ENABLED=true
SPY_DASHBOARD_PREFIX=spy
SPY_DASHBOARD_MIDDLEWARE=web,auth

To maintain database size automatically, add the spy:clean command to your Laravel task scheduler. For example, you can run it once a day in your app/Console/Kernel.php file.

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('spy:clean')->daily();
}