👨‍💻 Using Scout with PHP

In this guide we'll provide general instructions on how to send events to Scout using PHP.

At the most basic level, events can be sent to Scout by making an API request. There are several ways to do this depending on whether you are using vanilla PHP or a framework such as Laravel or Symfony.

cURL

<?php

$data = [
    'source_id' => "my-source-id",
    'type' => 'page_view',
    'payload' => [
        'url' => 'https://example.com'
    ]
];

$ch = curl_init('https://api.usescout.io/api/events');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
$error = curl_error($ch);
curl_close($ch);

Laravel

Laravel's HTTP facade provides a handy interface for making requests.

use Illuminate\Support\Facades\Http;

$response = Http::post('https://api.usescout.io/api/events', [
    'source_id' => 'my-source-id',
    'type' => 'page_view',
    'payload' => [
        'url' => 'https://example.com'
    ],
]);

if ($response->successful()) {
    // Event sent successfully
} else {
    // Handle error
    Log::error('Scout event failed', ['response' => $response->body()]);
}

You may want to extract this into a service class or job if you're sending events frequently.

Symfony

In Symfony, you can use the built-in HttpClient component to send requests to Scout.

First, install the HTTP client if you haven't already:

composer require symfony/http-client

use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create();

$response = $client->request('POST', 'https://api.usescout.io/api/events', [
    'headers' => [
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'source_id' => 'my-source-id',
        'type' => 'page_view',
        'payload' => [
            'url' => 'https://example.com'
        ],
    ],
]);

$statusCode = $response->getStatusCode();
$content = $response->getContent(false);

if ($statusCode >= 200 && $statusCode < 300) {
    // Event sent successfully
} else {
    // Handle error
    // You might want to log $content for debugging
}

WordPress

In WordPress, you can use the built-in wp_remote_post() function to send events to Scout. This can be placed in a theme’s functions.php, a plugin, or wherever it fits your architecture.

<?php

$data = [
    'source_id' => 'my-source-id',
    'type' => 'page_view',
    'payload' => [
        'url' => home_url($_SERVER['REQUEST_URI']),
    ],
];

$response = wp_remote_post('https://api.usescout.io/api/events', [
    'headers' => [
        'Content-Type' => 'application/json',
    ],
    'body' => wp_json_encode($data),
]);

if (is_wp_error($response)) {
    error_log('Scout event failed: ' . $response->get_error_message());
} else {
    $code = wp_remote_retrieve_response_code($response);
    if ($code < 200 || $code >= 300) {
        error_log('Scout event failed with status: ' . $code);
    }
}

Drupal

In Drupal, you can send Scout events using the \Drupal::httpClient() service to make HTTP requests. This can be done in a custom module, or injected into an event subscriber, form submit handler, or controller.

Example: Sending a Page View Event

Here’s how you might send a page view event using a custom module:

use Drupal\Core\Routing\RouteMatchInterface;
use Symfony\Component\HttpFoundation\RequestStack;

/**
 * Implements hook_init().
 */
function mymodule_init() {
  $request = \Drupal::service('request_stack')->getCurrentRequest();
  $url = $request->getUri();

  $event = [
    'source_id' => 'my-source-id',
    'type' => 'page_view',
    'payload' => [
      'url' => $url,
    ],
  ];

  try {
    $response = \Drupal::httpClient()->post('https://api.usescout.io/api/events', [
      'headers' => [
        'Content-Type' => 'application/json',
      ],
      'body' => json_encode($event),
    ]);
  }
  catch (\Exception $e) {
    \Drupal::logger('scout')->error('Scout tracking failed: @message', ['@message' => $e->getMessage()]);
  }
}

🧠 Note: hook_init() is only available in non-cached pages (admin pages or logged-in user pages). For more control, consider triggering Scout events in an event subscriber or using hook_page_attachments() for frontend JS tracking.

JavaScript Option

Alternatively, you can use the JavaScript approach in your theme to trigger events client-side. Add this inside your theme’s html.html.twig or via a library:

(function () {
  const event = {
    source_id: "my-source-id",
    type: "page_view",
    payload: {
      url: window.location.href,
    },
  };

  fetch("https://api.usescout.io/api/events", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(event),
  });
})();