Add ability to supply X-Barstool-UUID in a request header

[allmanaj]

Overview of change

This PR adds the ability to send your own custom X-Barstool-UUID in the header of a Saloon request and to have that be the UUID stored against the row in the barstools table.

Reasoning

I have started using Barstool at work to provide visibility of our requests since the codebase relies heavily on calls to external APIs. Barstool is ideal for this, but we have an instance where we want to store more specific data about a certain repeated job and how to connects to other models in our codebase. By checking for the existence of the X-Barstool-UUID header before the package generates a new UUID, it allows us to supply a UUID from our codebase which can be stored on the more detailed log model. This allows us to associate our own log with the barstool record without clogging up the barstools table.

Example Implementation

$barstoolId = Str::uuid();
$request = new RequestWhichAcceptsCustomHeaders(headers: ['X-Barstool-UUID' => $barstoolId]);
$response = $request->send();
if($response->failed()) {
    LogModelWithAddedContext::create([
        'user_id' => auth()->id,
        'barstool_id' => $barstoolId,
    ]);
}

[craigpotter]

Hey

Thanks for this.
One small suggestion please.

[craigpotter]

Suggested change

	$uuid = $data->headers()->get('X-Barstool-UUID');
	$data->headers()->add('X-Barstool-UUID', $uuid);
	if (is_null($uuid)) {
	$uuid = Str::uuid()->toString();
	$data->headers()->add('X-Barstool-UUID', $uuid);
	}
	$uuid = $data->headers()->get('X-Barstool-UUID', Str::uuid()->toString());
	$data->headers()->add('X-Barstool-UUID', $uuid);

[craigpotter]

Hey @allmanaj — thanks again for this PR and sorry for the long silence on it. Having sat with it a while, I've decided not to merge the header override: letting callers set the UUID makes a user-supplied value the updateOrCreate key (a reused UUID would silently merge unrelated recordings into one row), and it turns the internal X-Barstool-UUID header into public API I'd have to preserve through upcoming refactors.

The good news is your use case works today without any changes — the generated UUID is readable straight off the sent request: $response->getPendingRequest()->headers()->get('X-Barstool-UUID'). #13 adds a test locking that in and documents it in the README ("Correlating Barstool records with your own models"). It also adds Barstool::context() for storing extra data (user IDs, etc.) directly on the recording, which may cover the other half of what you were after.

Thanks for using Barstool and for pushing on this — it directly shaped both additions. 🍻