$request, \Hypervel\Saloon\Http\Faking\MockClient|null $mockClient = null)
- * @method static \Hypervel\Saloon\Http\Sender sender()
* @method static void setEventDispatcher(\Hypervel\Contracts\Events\Dispatcher $events)
* @method static \Hypervel\Saloon\SaloonManager throwOnMissingFixtures(bool $throw = true)
* @method static bool throwsOnMissingFixtures()
diff --git a/src/saloon/src/SaloonManager.php b/src/saloon/src/SaloonManager.php
index 290c026851..79c2247e8b 100644
--- a/src/saloon/src/SaloonManager.php
+++ b/src/saloon/src/SaloonManager.php
@@ -280,30 +280,6 @@ public function createPendingRequest(Connector $connector, Request $request): Pe
return $pendingRequest->executeRequestPipeline();
}
- /**
- * Get the Saloon sender.
- */
- public function sender(): Sender
- {
- return $this->sender;
- }
-
- /**
- * Get the cache factory.
- */
- public function cache(): CacheFactory
- {
- return $this->cache;
- }
-
- /**
- * Get the rate limiter manager.
- */
- public function rateLimiter(): RateLimiter
- {
- return $this->rateLimiter;
- }
-
/**
* Inspect a connector or request rate limit without consuming it.
*
diff --git a/src/saloon/stubs/saloon.authenticator.stub b/src/saloon/stubs/saloon.authenticator.stub
index cced117ecc..9cffc98729 100644
--- a/src/saloon/stubs/saloon.authenticator.stub
+++ b/src/saloon/stubs/saloon.authenticator.stub
@@ -9,10 +9,19 @@ use Hypervel\Saloon\Http\PendingRequest;
class {{ class }} implements Authenticator
{
+ /**
+ * Create a new authenticator instance.
+ */
+ public function __construct()
+ {
+ //
+ }
+
/**
* Apply the authentication to the request.
*/
public function set(PendingRequest $pendingRequest): void
{
+ //
}
}
diff --git a/src/saloon/stubs/saloon.plugin.stub b/src/saloon/stubs/saloon.plugin.stub
index 9b00e4b54a..3451012c52 100644
--- a/src/saloon/stubs/saloon.plugin.stub
+++ b/src/saloon/stubs/saloon.plugin.stub
@@ -13,5 +13,6 @@ trait {{ class }}
*/
public function boot{{ class }}(PendingRequest $pendingRequest): void
{
+ //
}
}
diff --git a/src/saloon/stubs/saloon.response.stub b/src/saloon/stubs/saloon.response.stub
index 1877ea0d01..dc2f30ff8b 100644
--- a/src/saloon/stubs/saloon.response.stub
+++ b/src/saloon/stubs/saloon.response.stub
@@ -8,4 +8,5 @@ use Hypervel\Saloon\Http\Response;
class {{ class }} extends Response
{
+ //
}
diff --git a/tests/Saloon/PackageMetadataTest.php b/tests/Saloon/PackageMetadataTest.php
index 798856ab94..d2326908e2 100644
--- a/tests/Saloon/PackageMetadataTest.php
+++ b/tests/Saloon/PackageMetadataTest.php
@@ -29,6 +29,7 @@ public function testDirectRuntimeDependenciesAreDeclared(): void
'ext-simplexml',
'guzzlehttp/guzzle',
'guzzlehttp/psr7',
+ 'guzzlehttp/uri-template',
'hypervel/cache',
'hypervel/collections',
'hypervel/conditionable',
@@ -43,7 +44,6 @@ public function testDirectRuntimeDependenciesAreDeclared(): void
'hypervel/macroable',
'hypervel/prompts',
'hypervel/rate-limiter',
- 'hypervel/reflection',
'hypervel/support',
'nesbot/carbon',
'psr/http-message',
diff --git a/tests/Saloon/Unit/PendingRequestTest.php b/tests/Saloon/Unit/PendingRequestTest.php
index 3b81203453..d89766c46a 100644
--- a/tests/Saloon/Unit/PendingRequestTest.php
+++ b/tests/Saloon/Unit/PendingRequestTest.php
@@ -154,7 +154,7 @@ public function testUrlParametersAreExpandedWithoutChangingTheRequest(): void
$request = (new PendingRequestRequestStub)
->withUrl('https://{region}.example.com/{version}/users')
->withUrlParameters(['region' => 'eu', 'version' => 'v1']);
- $pendingRequest = $this->pendingRequest(new PendingRequestConnectorWithoutBodyStub, $request);
+ $pendingRequest = new PendingRequest(new PendingRequestConnectorWithoutBodyStub, $request);
$this->assertSame('https://eu.example.com/v1/users', (string) $pendingRequest->finalizeUri()->uri());
@@ -167,7 +167,7 @@ public function testUrlParametersAreExpandedWithoutChangingTheRequest(): void
public function testUrlParametersAreExpandedInTheBaseUrlAndEndpoint(): void
{
$request = (new PendingTemplateRequestStub)->withUrlParameters(['tenant' => 'acme', 'id' => 'a b/c']);
- $pendingRequest = $this->pendingRequest(new PendingTemplateConnectorStub, $request);
+ $pendingRequest = new PendingRequest(new PendingTemplateConnectorStub, $request);
$this->assertSame('https://acme.example.com/v1/users/a%20b%2Fc', (string) $pendingRequest->uri());
}
@@ -185,7 +185,7 @@ public function testConstructionOnlySnapshotsOperationState(): void
++PendingRequestRequestStub::$middlewareCalls;
});
- $pendingRequest = $this->pendingRequest($connector, $request);
+ $pendingRequest = new PendingRequest($connector, $request);
$this->assertSame(0, PendingRequestConnectorStub::$bootCalls);
$this->assertSame(0, PendingRequestRequestStub::$bootCalls);
@@ -222,7 +222,7 @@ public function testUriAndBodyAreFinalizedAfterRequestMiddleware(): void
public function testRawQuerySnapshotsDefaultsAndReplacesBothUrlQueries(): void
{
$request = new PendingRawQueryRequestStub;
- $pendingRequest = $this->pendingRequest(new PendingRawQueryConnectorStub, $request);
+ $pendingRequest = new PendingRequest(new PendingRawQueryConnectorStub, $request);
$request->withQueryString('changed=after-snapshot');
$pendingRequest->finalizeUri();
@@ -242,7 +242,7 @@ public function testRawQueryReplacementRetainsArrayAndAuthenticationOverlays():
$request = (new PendingRawQueryRequestStub)
->withQueryString('tag=a&tag=b&token=old&token=older')
->withQueryParameters(['limit' => 10]);
- $pendingRequest = $this->pendingRequest(new PendingRequestConnectorStub, $request);
+ $pendingRequest = new PendingRequest(new PendingRequestConnectorStub, $request);
$pendingRequest->authenticate(new QueryAuthenticator('token', 'secret'))->finalizeUri();
@@ -257,7 +257,7 @@ public function testRawQueryReplacementRetainsArrayAndAuthenticationOverlays():
public function testNullRawQueryKeepsTheOriginalUrlQuery(): void
{
- $pendingRequest = $this->pendingRequest(new PendingRawQueryConnectorStub, new PendingRequestRequestStub);
+ $pendingRequest = new PendingRequest(new PendingRawQueryConnectorStub, new PendingRequestRequestStub);
$this->assertNull($pendingRequest->queryString());
$this->assertSame('base=old', $pendingRequest->uri()->getQuery());
@@ -268,7 +268,7 @@ public function testFullUrlOverrideIsVisibleToAuthenticationAndKeepsQueryOverlay
$request = (new PendingRequestRequestStub)
->withUrl('https://uploads.example.com/files?tag=a&tag=b&token=old')
->withQueryParameters(['limit' => 10]);
- $pendingRequest = $this->pendingRequest(new PendingRequestConnectorStub, $request);
+ $pendingRequest = new PendingRequest(new PendingRequestConnectorStub, $request);
$pendingRequest
->authenticate(new CookieAuthenticator('session', 'secret'))
@@ -287,7 +287,7 @@ public function testFullUrlOverrideIsVisibleToAuthenticationAndKeepsQueryOverlay
#[DataProvider('invalidFullUrls')]
public function testFullUrlOverrideRequiresAnAbsoluteHttpUrl(string $url): void
{
- $pendingRequest = $this->pendingRequest(
+ $pendingRequest = new PendingRequest(
new PendingRequestConnectorStub,
(new PendingRequestRequestStub)->withUrl($url),
);
@@ -310,13 +310,13 @@ public function testConnectorAndRequestBodyTypesMustMatch(): void
$this->expectException(PendingRequestException::class);
$this->expectExceptionMessage('Connector and request body types must be the same.');
- $this->pendingRequest(new PendingRequestConnectorStub, new PendingRequestStringBodyStub);
+ new PendingRequest(new PendingRequestConnectorStub, new PendingRequestStringBodyStub);
}
public function testLogicalPsrRequestReusesAnAlreadyPreparedBody(): void
{
CountingBodyRepository::$streamCalls = 0;
- $pendingRequest = $this->pendingRequest(
+ $pendingRequest = new PendingRequest(
new PendingRequestConnectorWithoutBodyStub,
new PendingRequestCountingBodyStub,
);
@@ -330,7 +330,7 @@ public function testLogicalPsrRequestReusesAnAlreadyPreparedBody(): void
public function testRequiresAuthRetainsItsProtectedMessageHook(): void
{
- $pendingRequest = $this->pendingRequest(
+ $pendingRequest = new PendingRequest(
new PendingRequestConnectorWithoutBodyStub,
new CustomRequiresAuthRequestStub,
);
@@ -343,7 +343,7 @@ public function testRequiresAuthRetainsItsProtectedMessageHook(): void
public function testAuthenticatorsReplaceLogicalHeadersRegardlessOfCase(): void
{
- $pendingRequest = $this->pendingRequest(
+ $pendingRequest = new PendingRequest(
new PendingRequestConnectorWithoutBodyStub,
new PendingRequestRequestStub,
);
@@ -384,14 +384,6 @@ protected function setUp(): void
PendingRequestRequestStub::$bootCalls = 0;
PendingRequestRequestStub::$middlewareCalls = 0;
}
-
- /**
- * Create a pending request with isolated framework dependencies.
- */
- protected function pendingRequest(Connector $connector, Request $request): PendingRequest
- {
- return new PendingRequest($connector, $request);
- }
}
class PendingRequestConnectorStub extends Connector
diff --git a/tests/Saloon/Unit/ResponseTest.php b/tests/Saloon/Unit/ResponseTest.php
index f1e24eec72..2855690fb1 100644
--- a/tests/Saloon/Unit/ResponseTest.php
+++ b/tests/Saloon/Unit/ResponseTest.php
@@ -631,7 +631,7 @@ public function testThrowPolicyCanSuppressAResponseThatStillReportsFailed(): voi
public function testNonSeekableBodyIsBufferedOnce(): void
{
- $pendingRequest = $this->pendingRequest(new ResponseConnectorStub, new ResponseRequestStub);
+ $pendingRequest = new PendingRequest(new ResponseConnectorStub, new ResponseRequestStub);
$psrRequest = new PsrRequest('GET', 'https://api.example.com/users');
$httpResponse = new HttpResponse(new PsrResponse(
body: new NoSeekStream(Utils::streamFor('response body')),
@@ -753,7 +753,7 @@ protected function response(
): Response {
$connector ??= new ResponseConnectorStub;
$request ??= new ResponseRequestStub;
- $pendingRequest ??= $this->pendingRequest($connector, $request);
+ $pendingRequest ??= new PendingRequest($connector, $request);
$psrRequest = new PsrRequest($request->method()->value, 'https://api.example.com/users');
return Response::fromResponse(
@@ -762,14 +762,6 @@ protected function response(
$psrRequest,
);
}
-
- /**
- * Create a pending request with isolated framework dependencies.
- */
- protected function pendingRequest(Connector $connector, Request $request): PendingRequest
- {
- return new PendingRequest($connector, $request);
- }
}
class ResponseConnectorStub extends Connector
diff --git a/tests/Saloon/Unit/SenderTest.php b/tests/Saloon/Unit/SenderTest.php
index 7c4124d7af..0ae623c608 100644
--- a/tests/Saloon/Unit/SenderTest.php
+++ b/tests/Saloon/Unit/SenderTest.php
@@ -12,7 +12,6 @@
use Hypervel\Http\Client\Factory;
use Hypervel\Http\Client\Request as HttpRequest;
use Hypervel\Saloon\Enums\Method;
-use Hypervel\Saloon\Facades\Saloon;
use Hypervel\Saloon\Http\Auth\BasicAuthenticator;
use Hypervel\Saloon\Http\Connector;
use Hypervel\Saloon\Http\PendingRequest;
@@ -34,7 +33,7 @@ class SenderTest extends TestCase
public function testTheDefaultConnectionOnAllConnectorsIsTheSaloonConnection(): void
{
$connector = new TestConnector;
- $sender = Saloon::sender();
+ $sender = $this->app->make(Sender::class);
$pendingRequest = $connector->createPendingRequest(new UserRequest);
@@ -42,7 +41,7 @@ public function testTheDefaultConnectionOnAllConnectorsIsTheSaloonConnection():
// Test the same instance is re-used
- $this->assertSame($sender, Saloon::sender());
+ $this->assertSame($sender, $this->app->make(Sender::class));
}
// Upstream also overrides the sender through a connector property; connectors select their connection only
@@ -95,7 +94,7 @@ public function testItSendsTheFinalOperationThroughTheSelectedHttpConnection():
->withTelescopeTags(['operation'])
->authenticate(new BasicAuthenticator('taylor', 'secret'))
->withData(['name' => 'Taylor']);
- $pendingRequest = $this->pendingRequest(new SenderConnectorStub, $request)
+ $pendingRequest = (new PendingRequest(new SenderConnectorStub, $request))
->applyAuthentication()
->executeRequestPipeline()
->finalizeUri()
@@ -133,7 +132,7 @@ public function testOperationCanDisableTelescopeWithoutLosingTheCanonicalTag():
return Factory::response();
});
$request = (new SenderRequestStub)->withoutTelescope();
- $pendingRequest = $this->pendingRequest(new SenderConnectorStub, $request)
+ $pendingRequest = (new PendingRequest(new SenderConnectorStub, $request))
->finalizeUri()
->prepareBody();
$sender = new Sender($http, $this->config());
@@ -162,14 +161,6 @@ protected function setUp(): void
SenderRequestStub::$psrHookCalls = 0;
}
- /**
- * Create a pending request with isolated framework dependencies.
- */
- protected function pendingRequest(Connector $connector, Request $request): PendingRequest
- {
- return new PendingRequest($connector, $request);
- }
-
/**
* Create package configuration for the sender.
*/
From f524cf2ba80a2761b3130192d8657a96d6780e6e Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Wed, 7 Oct 2026 04:46:40 +0000
Subject: [PATCH 18/26] Map the remaining Saloon plugin surfaces and open
CacheKey
Comparing the public and protected surfaces of upstream's cache,
pagination and rate-limit plugins with Hypervel's found no code gaps,
but the README did not name the Hypervel equivalents for several
upstream APIs. It now covers CacheKeyHelper, the cache middleware and
expiry methods, LimitException, Limit::allow()'s threshold,
Limit::custom(), RetryAfterHelper, $detectTooManyAttempts, the
exceeded-limit hooks and per-user limit names.
CacheKey is no longer final, since it protects no invariant. A short
comment explains why it hashes with sha256 instead of xxh128: the
request identity includes credentials, so a forged collision would
return another caller's cached response.
The private SDK generator and generated SDKs were verified against
this branch, with two test updates made in that repository.
Validation: the Saloon suite (ParaTest), tests/Saloon/Cache,
composer analyse and php-cs-fixer; the private SDK generator suite,
its analysis configurations, the seven generated SDK test suites and
generated-code analysis.
---
src/saloon/README.md | 4 ++--
src/saloon/src/Cache/CacheKey.php | 4 +++-
2 files changed, 5 insertions(+), 3 deletions(-)
diff --git a/src/saloon/README.md b/src/saloon/README.md
index 70a1dbc867..8fa31ea927 100644
--- a/src/saloon/README.md
+++ b/src/saloon/README.md
@@ -20,11 +20,11 @@ Retries use `retry($times, $sleepMilliseconds, $when, $throw)` and a `defaultRet
Pools send requests concurrently through coroutines instead of promises, so there is no `sendAsync()`, pending requests have no `isAsynchronous()` or `setAsynchronous()`, and pools accept requests but not promises. A pool's `send()` waits for every request and returns the successful responses keyed and ordered as the requests were given; `process()` sends them without keeping the responses. Concurrency is a positive integer: upstream's callable and unlimited `0` forms are not supported, because the coroutine pool has a fixed number of slots. Handlers receive the response or exception and the request's key, without upstream's aggregate promise. Ending a request generator stops further requests, but a request already waiting for a slot still starts and running requests are not canceled. Every response that `toException()` treats as failed, including through custom failure hooks, goes to the exception handler; upstream's real asynchronous path checks them only after Guzzle rejects a transfer. Unhandled request failures, handler failures and invalid items throw `PoolException` once every started request has finished, instead of being ignored or ending the pool early. `requests()` replaces `getRequests()` and calls a request callback each time the pool is sent, so a callback that returns a new iterable lets the pool be sent again. See [Concurrent Requests](https://hypervel.org/docs/saloon#concurrent-requests).
-Caching uses Hypervel's cache stores. `Cacheable` declares `cacheFor()` and `cacheStore()` instead of upstream's `resolveCacheDriver()` and `cacheExpiryInSeconds()`, so there is no `Driver` contract and no Flysystem, PSR or Laravel driver; add other caches as framework cache stores. `CachingException` replaces `HasCachingException`. Connectors are read-only, so they implement `Cacheable` without the `HasCaching` request controls and override `cacheKey()` and `cacheableMethods()`, which replaces `getCacheableMethods()`. GET, HEAD, OPTIONS and QUERY requests are cacheable by default. See [Caching](https://hypervel.org/docs/saloon#caching).
+Caching uses Hypervel's cache stores. `Cacheable` declares `cacheFor()` and `cacheStore()` instead of upstream's `resolveCacheDriver()` and `cacheExpiryInSeconds()`, so there is no `Driver` contract and no Flysystem, PSR or Laravel driver; add other caches as framework cache stores. `CachingException` replaces `HasCachingException`. Connectors are read-only, so they implement `Cacheable` without the `HasCaching` request controls and override `cacheKey()` and `cacheableMethods()`, which replaces `getCacheableMethods()`. GET, HEAD, OPTIONS and QUERY requests are cacheable by default. There is no `CacheKeyHelper`: a custom `cacheKey()` replaces the default request identity, and `Saloon::resolveCacheScopeUsing()` adds a scope, such as the tenant, to every key. Cached entries are `CachedResponse` values holding the status, headers and body, and they expire through the cache store, so `CacheMiddleware`, `CacheRecorderMiddleware`, `hasExpired()` and `getFakeResponse()` are not included. See [Caching](https://hypervel.org/docs/saloon#caching).
Paginators set their values with `maxPages()`, `perPageLimit()` and `startPage()`, and `totalResults()`, `request()` and `currentPage()` replace `getTotalResults()`, `getOriginalRequest()` and `getCurrentPage()`. The deprecated `getPage()` and `$page` are not included; custom `applyPagination()` methods read the protected `$pageNumber`. Page and offset paginators send their pages concurrently with `pool()`, which sends the first page, then the rest through a coroutine pool, and returns the responses keyed by page position, so there is no `async()`, `isAsyncPaginationEnabled()` or `HasAsyncPagination` and no promises to iterate. Cursor paginators can't be pooled because each cursor comes from the previous response. Iterator keys and `currentPage()` count from zero at the start page, and `maxPages()` counts pages from the start page. Upstream starts keys at `startPage - 1` and compares `maxPages` with page numbers, so `startPage(3)` with `maxPages(2)` returns no pages there. See [API Pagination](https://hypervel.org/docs/saloon#api-pagination).
-Rate limits use Hypervel's rate limiter. `resolveRateLimits()` returns framework admission policies for the pending request instead of upstream's `resolveLimits()` with `Limit` and `Bucket` objects, and state lives in the rate-limiter store chosen by `resolveRateLimitStore()` or `saloon.rate_limiter.store`, so there is no `RateLimitStore` contract or plugin store. `Limit::perMinute()` and the other `Limit` factories replace upstream's `every*()` intervals, `LeakyBucket` replaces `Bucket`, and `CalendarWindow` replaces `untilEndOfMinute()`, `untilEndOfHour()`, `untilMidnightTonight()`, `everyDayUntil()` and `untilEndOfMonth()`. The rate limiter's Redis, Swoole, database and worker-array stores replace upstream's stores. There are no file, Laravel cache or PSR cache stores, since a general cache can't apply these policies atomically, and no Predis store, since the Redis store uses the framework's PhpRedis connections. Identical policies share one state and each charges it, rather than throwing upstream's duplicate-name exception. `waitForRateLimits($policy, $result)` replaces `sleep()` on each limit, `resolveRateLimiterName()` replaces `getLimiterPrefix()` (use `by()` keys for per-user limits), and Saloon fakes and cache hits consume no capacity. A 429 records a cooldown, 60 seconds when `Retry-After` is missing or invalid, through `resolveRateLimitCooldown()` in place of `handleTooManyAttempts()`, `getTooManyAttemptsLimiter()` and `$detectTooManyAttempts`. The 429 goes through normal response and error handling, and an active cooldown applies to later requests. Nothing is resent automatically, so combine `waitForRateLimits()` with a retry policy to wait and send again.
+Rate limits use Hypervel's rate limiter. `resolveRateLimits()` returns framework admission policies for the pending request instead of upstream's `resolveLimits()` and `getLimits()` with `Limit` and `Bucket` objects, and state lives in the rate-limiter store chosen by `resolveRateLimitStore()` or `saloon.rate_limiter.store`, so there is no `RateLimitStore` contract, `rateLimitStore()` or plugin store. `LimitException` is not included; invalid policies and store state throw the rate limiter's own exceptions. `Limit::perMinute()` and the other `Limit` factories replace upstream's `every*()` intervals, `LeakyBucket` replaces `Bucket`, and `CalendarWindow` replaces `untilEndOfMinute()`, `untilEndOfHour()`, `untilMidnightTonight()`, `everyDayUntil()` and `untilEndOfMonth()`. Set a lower limit in place of `Limit::allow()`'s threshold. The rate limiter's Redis, Swoole, database and worker-array stores replace upstream's stores. There are no file, Laravel cache or PSR cache stores, since a general cache can't apply these policies atomically, and no Predis store, since the Redis store uses the framework's PhpRedis connections. Identical policies share one state and each charges it, rather than throwing upstream's duplicate-name exception. `waitForRateLimits($policy, $result)` replaces `sleep()` on each limit and the `handleExceededLimit()` and `throwLimitException()` hooks, `resolveRateLimiterName()` replaces `getLimiterPrefix()` (use `by()` keys in place of `name()` for per-user limits), and Saloon fakes and cache hits consume no capacity. A 429 records a cooldown, 60 seconds when `Retry-After` is missing or invalid, through `resolveRateLimitCooldown()` in place of `handleTooManyAttempts()`, `getTooManyAttemptsLimiter()`, `Limit::custom()`, `RetryAfterHelper` and `$detectTooManyAttempts`; override it to read other responses, or return `null` to record nothing. The 429 goes through normal response and error handling, and an active cooldown applies to later requests. Nothing is resent automatically, so combine `waitForRateLimits()` with a retry policy to wait and send again.
Connectors are read-only, so `rateLimitingEnabled(PendingRequest)` replaces `useRateLimitPlugin()` and `$rateLimitingEnabled`, and `Saloon::inspectRateLimit()` replaces `hasReachedRateLimit()` and `getExceededLimit()`; compare `remaining()` with `limit()` in place of a threshold. `RateLimitReachedException` exposes `policy()` and `result()` instead of `getLimit()`, and the job middleware is `Queue\ReleaseOnRateLimit` instead of `Helpers\ApiRateLimited`. See [Rate Limiting](https://hypervel.org/docs/saloon#rate-limiting).
diff --git a/src/saloon/src/Cache/CacheKey.php b/src/saloon/src/Cache/CacheKey.php
index b47bcf6b4f..dd5bc98383 100644
--- a/src/saloon/src/Cache/CacheKey.php
+++ b/src/saloon/src/Cache/CacheKey.php
@@ -9,7 +9,7 @@
use Hypervel\Saloon\Http\HeaderNormalizer;
use Hypervel\Saloon\Http\PendingRequest;
-final class CacheKey
+class CacheKey
{
/**
* Options that can change a successful response.
@@ -50,6 +50,8 @@ public function make(
? $this->requestIdentity($pendingRequest, $transportOptions)
: ['custom' => $customKey];
+ // sha256 rather than xxh128: the identity includes credentials, and a forged collision would return another
+ // caller's cached response.
return 'saloon:' . hash('sha256', $this->encode([$identity, 'scope' => $scope]));
}
From 2fcdbcaa8095853aa76579f1609ded48a0a3d657 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Wed, 7 Oct 2026 05:08:38 +0000
Subject: [PATCH 19/26] Reconcile the core Saloon guide with upstream's
documentation
The guide was compared with Saloon v3's documentation from connectors
through concurrency and testing, and every claim and example was
checked against Hypervel's source.
Corrections: the shouldThrowRequestException example could never stop
a 404 from throwing, since a response throws when either the request's
or the connector's hook returns true. The guide now separates failure
classification from throwing, retries and caching. Request data
conversion applies to Hypervel's Stringable, not any stringable value.
The differences list no longer mentions OAuth 1, which upstream never
had.
Added coverage includes the HTTP connection defaults and rejected
request-shaping options, standalone request credentials, query string
encoding, built-in and combined authenticators, multipart bodies,
request-instance middleware and fake responses, data objects, the
status exception table, retry forms and exhaustion, debug output,
OAuth endpoint defaults, scopes, state and token storage, pool
concurrency, mock client assertions and fixture recording.
Fixture recording stays subject to Http::preventStrayRequests(); the
guide and README say to allow the API's URLs while recording.
Validation: documentation only; every in-page link resolves to an
anchor.
---
src/docs/saloon.md | 309 +++++++++++++++++++++++++++++++++++--------
src/saloon/README.md | 2 +-
2 files changed, 257 insertions(+), 54 deletions(-)
diff --git a/src/docs/saloon.md b/src/docs/saloon.md
index 0742d50edb..3642f947a4 100644
--- a/src/docs/saloon.md
+++ b/src/docs/saloon.md
@@ -252,6 +252,17 @@ public function boot(PendingRequest $pendingRequest): void
### Organizing SDKs
+A connector may serve as an SDK's entry point by offering methods that send its requests:
+
+```php
+use Hypervel\Saloon\Http\Response;
+
+public function user(string $username): Response
+{
+ return $this->send(new GetUser($username));
+}
+```
+
When an integration contains many endpoints, you may group related requests into resource classes. Extend `BaseResource` and use the `@extends` annotation to specify your connector type:
```php
@@ -288,9 +299,18 @@ Your resource may access the connector through its protected, readonly `$connect
### HTTP Connections
-Saloon registers one named Hypervel HTTP connection, named `saloon` by default. Synchronous requests through this connection reuse the low-level transport, allowing cURL to retain keep-alive sockets, DNS information, and TLS sessions. Each operation still receives its own pending request, client, middleware stack, and cookie jar.
+Saloon registers one named Hypervel [HTTP connection](/docs/{{version}}/http-client#connections), named `saloon` by default. Synchronous requests through this connection reuse the low-level transport, allowing cURL to retain keep-alive sockets, DNS information, and TLS sessions. Each operation still receives its own pending request, client, middleware stack, and cookie jar.
-You may publish the configuration file to change the default connection options. A connector may also select another connection that your application registered during worker boot:
+The `saloon` connection uses a 10-second connection timeout and a 30-second request timeout. You may [publish the configuration file](#publishing-configuration-and-stubs) to change its options. A connector may also select another connection that your application registers during worker boot:
+
+```php
+use Hypervel\Support\Facades\Http;
+
+Http::registerConnection('github', [
+ 'connect_timeout' => 5,
+ 'timeout' => 60,
+]);
+```
```php
public function resolveHttpConnection(): ?string
@@ -299,6 +319,8 @@ public function resolveHttpConnection(): ?string
}
```
+A connection used by Saloon may not contain options that shape the request, such as `headers`, `query`, `cookies`, `json`, and `auth`, because Saloon builds those from the connector and request. Define them on the connector instead. Saloon requests also receive the HTTP client's [global options](/docs/{{version}}/http-client#global-options) and [global middleware](/docs/{{version}}/http-client#global-middleware).
+
Connection names must come from a fixed, bounded set. Do not create a connection name from a tenant ID, hostname, or credential, since registered connections and their handlers remain in memory for the worker lifetime. One fixed connection may safely send requests to many tenant-selected hosts.
Connection options do not provide an aggregate connection cap. The unsafe Guzzle `max_host_connections` and `max_total_connections` options are rejected. Bound each concurrent operation with a [Saloon pool](#concurrent-requests), and use [rate limits](#rate-limiting) to control request rates. Saloon does not use object pooling because each request needs its own client, middleware stack, and cookie jar.
@@ -410,6 +432,11 @@ class GetStatus extends SoloRequest
$response = (new GetStatus)->send();
```
+Standalone requests define their headers, query parameters, options, authentication, and body using the same [default methods](#request-defaults) as other requests.
+
+> [!WARNING]
+> A standalone request sends its headers and credentials to whatever URL `resolveEndpoint` returns. Do not build the endpoint from user input.
+
A request that always uses the same connector may send itself with the `HasConnector` trait. Define the connector class in a `$connector` property:
```php
@@ -564,6 +591,8 @@ $request->withQueryParameters([
Request values replace connector values with the same key. Values added later by middleware replace earlier values. Query parameters already present in the connector base URL or request endpoint are preserved unless the request contains the same top-level key.
+Query parameters are encoded using PHP's `http_build_query` function, so arrays use bracketed names such as `filter[active]=1`, booleans become `1` or `0`, and `null` values are left out. When an API expects another format, use the `withQueryString` method described below.
+
The `withoutQueryParameters` method removes parameters added through `withQueryParameters` or `defaultQuery`. As with headers, removing a parameter from a request does not remove a connector default; remove it from the pending request instead. Values embedded in the base URL, endpoint, or `withQueryString` query are unchanged:
```php
@@ -616,6 +645,31 @@ $request->withBasicAuth($username, $password);
$request->withDigestAuth($username, $password);
```
+These methods create authenticators, which you may also use directly. Return an authenticator from a connector or request's `defaultAuth` method, or pass one to `authenticate`. Saloon includes header, query, cookie, token, basic, digest, certificate, access-token, and multi-authenticator implementations under `Hypervel\Saloon\Http\Auth`:
+
+```php
+use Hypervel\Saloon\Contracts\Authenticator;
+use Hypervel\Saloon\Http\Auth\HeaderAuthenticator;
+
+protected function defaultAuth(): ?Authenticator
+{
+ return new HeaderAuthenticator($this->key, 'X-Api-Key');
+}
+```
+
+A request's authenticator replaces its connector's. When an API requires more than one form of authentication, such as a client certificate and a token, combine them using `MultiAuthenticator`:
+
+```php
+use Hypervel\Saloon\Http\Auth\CertificateAuthenticator;
+use Hypervel\Saloon\Http\Auth\MultiAuthenticator;
+use Hypervel\Saloon\Http\Auth\QueryAuthenticator;
+
+$request->authenticate(new MultiAuthenticator(
+ new CertificateAuthenticator('/path/to/client.pem', $password),
+ new QueryAuthenticator('api_key', $key),
+));
+```
+
Built-in NTLM authentication is not provided. Integrations requiring NTLM must supply their own authenticator and transport middleware.
You may create a reusable authenticator by implementing `Hypervel\Saloon\Contracts\Authenticator`:
@@ -628,24 +682,26 @@ class ApiKeyAuthenticator implements Authenticator
{
public function __construct(
private readonly string $key,
+ private readonly string $accountId,
) {
}
public function set(PendingRequest $pendingRequest): void
{
- $pendingRequest->withHeader('X-Api-Key', $this->key);
+ $pendingRequest->withHeaders([
+ 'X-Api-Key' => $this->key,
+ 'X-Account-Id' => $this->accountId,
+ ]);
}
}
```
-Apply a custom authenticator using `authenticate`, or return it from a connector's `defaultAuth` method:
+Use a custom authenticator like the built-in ones:
```php
-$request->authenticate(new ApiKeyAuthenticator($key));
+$request->authenticate(new ApiKeyAuthenticator($key, $accountId));
```
-Saloon also includes header, query, cookie, token, basic, digest, certificate, access-token, and multi-authenticator implementations under `Hypervel\Saloon\Http\Auth`.
-
For APIs that authenticate using a cookie, use `CookieAuthenticator`:
```php
@@ -704,7 +760,7 @@ class CreateIssue extends Request
}
```
-The JSON, form, and XML traits supply the appropriate content type unless you already defined one. A multipart body always receives `multipart/form-data` with its boundary unless the content type you define declares a boundary. String and stream bodies do not assume a content type, so specify one using `contentType` or `defaultHeaders`. Body traits may also be used on connectors when every request shares the same body format; request body values take precedence over connector values.
+The JSON, form, and XML traits supply the appropriate content type unless you already defined one. A multipart body always receives `multipart/form-data` with its boundary unless the content type you define declares a boundary. String and stream bodies do not assume a content type, so specify one using `contentType` or `defaultHeaders`. Body traits may also be used on connectors when every request shares the same body format. A request's JSON and form values are merged into the connector's, replacing values with the same key, and its multipart parts are added after the connector's. A request's string, XML, or stream body replaces the connector's.
When both a connector and request define a body, their body repositories must be the same type. For example, a request using `HasFormBody` cannot be sent through a connector using `HasJsonBody`. Saloon throws a `PendingRequestException` when the body types do not match.
@@ -717,6 +773,8 @@ $request->withBody($stream, 'application/octet-stream');
$request->withBody($stream, null);
```
+The `withBody` method accepts a string, stream, or resource. Like the HTTP client's method of the same name, it sets an `application/json` content type unless you pass another one, or `null` to leave the content type unchanged.
+
The `withData` method merges structured values into the current JSON or form body. If the request has no JSON, form, or multipart body, the method creates a JSON body:
```php
@@ -725,7 +783,7 @@ $request->withData(['active' => true]);
On a multipart body, `withData` adds each value as a field after the existing parts. Fields are appended, so repeating a name adds another field instead of replacing the first. Nested arrays are sent as bracketed field names such as `roles[0]`, `true` is sent as `1`, and `false` and `null` are sent as empty fields.
-Laravel `Arrayable` objects, `JsonSerializable` objects, and stringable values are normalized recursively in JSON, form, and query data.
+`Arrayable` and `JsonSerializable` objects, and the fluent strings returned by `Str::of`, are converted recursively in JSON, form, and query data.
JSON bodies use `JSON_THROW_ON_ERROR` by default. To use other encoding flags, return a configured `JsonBodyRepository` from `defaultBodyRepository`:
@@ -769,6 +827,30 @@ When a request has a body in another format, `attach` replaces it with a multipa
Saloon preserves multipart streams, filenames, headers, order, and the generated boundary. Caller-owned streams are not buffered automatically.
+A request using the `HasMultipartBody` trait returns its default parts from `defaultBody` as `MultipartValue` instances, each containing the part's name, contents, and an optional filename and headers. String contents are sent as they are, so open files using `fopen`:
+
+```php
+use Hypervel\Saloon\Data\MultipartValue;
+use Hypervel\Saloon\Traits\Body\HasMultipartBody;
+
+class UploadAvatar extends Request
+{
+ use HasMultipartBody;
+
+ // ...
+
+ protected function defaultBody(): array
+ {
+ return [
+ new MultipartValue('avatar', fopen($this->path, 'rb'), 'avatar.png', [
+ 'Content-Type' => 'image/png',
+ ]),
+ new MultipartValue('description', 'Profile photo'),
+ ];
+ }
+}
+```
+
### Custom Body Repositories
@@ -869,6 +951,8 @@ $request
The `timeout` and `connectTimeout` methods accept seconds, while `delay` accepts milliseconds. Saloon waits for the delay before every attempt, including attempts answered by a mock or fake response, so `Sleep::fake()` can assert it in your tests. Responses served from the cache are not delayed.
+The `withoutRedirecting` method disables redirects, and the `sink` method writes the response body to a path or resource as it is received.
+
The `withoutOptions` method removes options from the request, so the connector's value or the HTTP connection's configured value applies again. To remove a connector default, call `withoutOptions` on the pending request:
```php
@@ -914,7 +998,7 @@ Request-shaping options such as `headers`, `query`, `cookies`, `body`, `json`, `
## Middleware
-Middleware may inspect or change the pending request, response, or fatal transport exception. You may register middleware from a connector or request's `boot` method, through a reusable plugin, or globally during application boot.
+Middleware may inspect or change the pending request, response, or fatal transport exception. You may register middleware on a request before sending it, from a connector or request's `boot` method, through a reusable plugin, or globally during application boot.
### Request Middleware
@@ -936,7 +1020,17 @@ public function boot(PendingRequest $pendingRequest): void
}
```
-Request middleware may return a `MockResponse` or another implementation of `FakeResponse` to short-circuit the network request. Other return values are ignored, so change the pending request it receives rather than returning a new one.
+Requests have the same middleware pipeline, so you may also add middleware to a request before sending it:
+
+```php
+$request = GetUser::make('hypervel');
+
+$request->middleware()->onRequest(function (PendingRequest $pendingRequest) use ($traceId): void {
+ $pendingRequest->withHeader('X-Trace-ID', $traceId);
+});
+```
+
+Request middleware may return a `MockResponse` or another implementation of `FakeResponse` to short-circuit the network request. The remaining request middleware still runs, and the last fake response returned is used. A fake response supplied by middleware bypasses the [response cache](#caching) and [mock clients](#faking-responses), and consumes no [rate limit](#rate-limiting) capacity. Other return values are ignored, so change the pending request it receives rather than returning a new one.
For reusable middleware, create an invokable class that implements `RequestMiddleware`:
@@ -959,7 +1053,9 @@ class AddRequestId implements RequestMiddleware
Register the class in the same way as a closure: `$pendingRequest->middleware()->onRequest(new AddRequestId)`.
-Middleware runs in registration order. Saloon registers [global middleware](#global-middleware) first, followed by plugin middleware, middleware added by the connector's `boot` method, the request's own middleware, and middleware added by the request's `boot` method. You may pass `PipeOrder::FIRST` or `PipeOrder::LAST` using the `order` argument when a middleware must run before or after the normal group. Named middleware must have a unique name within its pipeline.
+Middleware runs in registration order. Saloon registers [global middleware](#global-middleware) first, followed by plugin middleware, middleware added by the connector's `boot` method, the request's own middleware, and middleware added by the request's `boot` method. You may pass `PipeOrder::FIRST` or `PipeOrder::LAST` using the `order` argument when a middleware must run before or after the normal group.
+
+These sources are merged into the operation's pipelines, so a name may be used only once among its request middleware, and likewise among its response and fatal exception middleware. A duplicate name throws a `DuplicatePipeNameException`. Request middleware may register response middleware, but request middleware added while the request pipeline is running does not run for that operation.
### Response Middleware
@@ -1174,7 +1270,7 @@ class GetUser extends Request
}
```
-Call `dto` to create the configured value. The `dtoOrFail` method refuses to create it when the integration considers the response failed:
+Call `dto` to create the configured value. The `dto` method converts every response, including failed ones, so you may also map error responses. The `dtoOrFail` method instead throws a `LogicException` when the integration considers the response [failed](#error-handling). When the response would also throw, its request exception is available as the `LogicException`'s previous exception:
```php
$user = $github->send(new GetUser('hypervel'))->dtoOrFail();
@@ -1239,27 +1335,45 @@ if ($response->failed()) {
$response->throw();
```
-Common statuses throw an exception named after them from the `Hypervel\Saloon\Exceptions\Request\Statuses` namespace, such as `NotFoundException` or `TooManyRequestsException`. These extend `ClientException` for 4xx responses and `ServerException` for 5xx responses, which other 4xx and 5xx responses throw directly. Other integration-defined failures throw `RequestException`.
+Common statuses throw an exception named after them from the `Hypervel\Saloon\Exceptions\Request\Statuses` namespace:
+
+| Status | Exception |
+|---|---|
+| 400 | `BadRequestException` |
+| 401 | `UnauthorizedException` |
+| 402 | `PaymentRequiredException` |
+| 403 | `ForbiddenException` |
+| 404 | `NotFoundException` |
+| 405 | `MethodNotAllowedException` |
+| 408 | `RequestTimeOutException` |
+| 409 | `ConflictException` |
+| 422 | `UnprocessableEntityException` |
+| 429 | `TooManyRequestsException` |
+| 500 | `InternalServerErrorException` |
+| 502 | `BadGatewayException` |
+| 503 | `ServiceUnavailableException` |
+| 504 | `GatewayTimeoutException` |
+
+These extend `ClientException` for 4xx responses and `ServerException` for 5xx responses, which other 4xx and 5xx responses throw directly. All of them extend `RequestException`, which other integration-defined failures throw.
A request that could not complete throws `FatalRequestException`. This includes failed connections and transfers that break while the response is being received, whatever status the partial response has.
-You may define provider-specific failure behavior on a request or connector:
+Some APIs report errors in a successful response. A request or connector may override `hasRequestFailed` to decide whether a response failed, returning `null` to fall back to the status code:
```php
+use Hypervel\Saloon\Http\Response;
+
public function hasRequestFailed(Response $response): ?bool
{
return $response->json('ok') === false ? true : null;
}
-
-public function shouldThrowRequestException(Response $response): bool
-{
- return $response->status() !== 404 && $response->failed();
-}
```
-In this example, the integration treats a 404 response as an empty result instead of an exception.
+In this example, a response whose body contains `"ok": false` is treated as failed whatever its status. A request's non-null decision takes precedence over its connector's. Failed responses are not [cached](#caching), and by default they throw from `throw` and trigger [retries](#retries).
-A non-null request failure decision takes precedence over the connector decision, which takes precedence over the status-code fallback. You may return a custom Saloon request exception from `getRequestException`, and a request's exception takes precedence over its connector's. To give a custom exception its own message, override its `prepareMessage` method:
+A response throws when the `shouldThrowRequestException` method of either its request or its connector returns `true`. Both return `failed()` by default. To stop a failed response from throwing while keeping it failed, return `false` from both methods. Returning `false` from `hasRequestFailed` instead makes the response successful, so it may also be cached and converted by `dtoOrFail`.
+
+You may return a custom Saloon request exception from `getRequestException`, and a request's exception takes precedence over its connector's. To give a custom exception its own message, override its `prepareMessage` method:
```php
use Hypervel\Http\Client\Response;
@@ -1274,28 +1388,41 @@ class GitHubException extends RequestException
}
```
+Then return it from the request or connector:
+
+```php
+use Hypervel\Saloon\Exceptions\Request\RequestException;
+use Hypervel\Saloon\Http\Response;
+
+public function getRequestException(Response $response): ?RequestException
+{
+ return new GitHubException($response);
+}
+```
+
The `AlwaysThrowOnErrors` plugin calls `throw` automatically after each response.
### Retries
-Use `retry` to specify the number of attempts and delay between attempts:
+The `retry` method accepts the maximum number of times a request should be attempted and the number of milliseconds to wait between attempts. A request is retried when its response would [throw](#error-handling) or the request could not complete:
```php
$request->retry(3, 100);
```
-You may supply an array of delays or calculate the delay using a closure:
+You may calculate the delay using a closure, or pass an array of delays as the first argument, which makes one more attempt than it contains delays:
```php
+$request->retry(3, fn (int $attempt) => $attempt * 100);
+
$request->retry([100, 250, 500]);
+```
-$request->retry(
- 4,
- fn (int $attempt) => $attempt * 100,
- when: fn ($exception, $pendingRequest) => $exception->getCode() !== 401,
- throw: false,
-);
+When a request with more than one attempt runs out of attempts, Saloon throws the last attempt's `RequestException` or `FatalRequestException`. A request with one attempt, such as `retry(1)`, returns a failed response as usual. Pass `throw: false` to return the last response instead of throwing. A `FatalRequestException` is still thrown, because there is no response to return, as is a request exception thrown by response middleware, such as the `AlwaysThrowOnErrors` plugin's:
+
+```php
+$request->retry(3, 100, throw: false);
```
Each attempt receives a fresh pending request, so middleware and authentication run again. Seekable request bodies are restored before another attempt. Saloon throws a `BodyException` rather than retrying a consumed non-seekable body.
@@ -1341,7 +1468,26 @@ $request->debugRequest();
$request->debugResponse();
```
-To debug every request sent through a connector, call the same methods on the pending request from the connector's `boot` method. The `debugRequest` and `debugResponse` methods accept a custom callback. All three methods accept `die: true`, which stops the current request or command after the output and is intended only for local debugging.
+To debug every request sent through a connector, call the same methods on the pending request from the connector's `boot` method. All three methods accept `die: true`, which stops the current request or command after the output and is intended only for local debugging.
+
+Saloon dumps the request and response using Symfony's VarDumper. The request is shown as Saloon passes it to the HTTP client, after [PSR-7 request hooks](#psr-request-hooks) have run, so headers that HTTP client middleware or Guzzle add later are not included. The response is shown before response middleware that uses the default [order](#middleware).
+
+The `debugRequest` and `debugResponse` methods also accept a callback, such as one that writes to your logs instead:
+
+```php
+use Hypervel\Saloon\Http\PendingRequest;
+use Hypervel\Saloon\Http\Response;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+$request->debugRequest(function (PendingRequest $pendingRequest, RequestInterface $psrRequest): void {
+ logger()->debug('Saloon request', ['uri' => (string) $psrRequest->getUri()]);
+});
+
+$request->debugResponse(function (Response $response, ResponseInterface $psrResponse): void {
+ logger()->debug('Saloon response', ['status' => $response->status()]);
+});
+```
> [!WARNING]
> Debug output contains raw headers and bodies and may expose credentials or other sensitive values. Custom callbacks are also responsible for any stream reads they perform.
@@ -1382,7 +1528,9 @@ class GitHubConnector extends Connector
}
```
-The `allowBaseUrlOverride` option is required here because GitHub's trusted authorization and token endpoints use a different host from the connector's API base URL. Leave this option disabled when the OAuth endpoints are relative to the connector base URL.
+The authorize, token, and user endpoints default to `authorize`, `token`, and `user`, relative to the connector's base URL. The `allowBaseUrlOverride` option is required here because GitHub's trusted authorization and token endpoints use a different host from the connector's API base URL. Leave this option disabled when the OAuth endpoints are relative to the connector base URL.
+
+If each tenant has its own OAuth client, pass the client credentials to the connector's constructor and use them in `defaultOAuthConfig`.
The `authorizationUrl` method returns the URL together with its generated state. Store the state for the current authorization attempt before redirecting the user:
@@ -1394,7 +1542,7 @@ session(['github_oauth_state' => $authorization->state]);
return redirect((string) $authorization);
```
-The `authorizationUrl` method also accepts a `scopeSeparator` and an array of `additionalQueryParameters`. Additional parameters may replace the standard ones, such as `response_type` for an OpenID Connect hybrid flow, but the URL's `state` always matches the returned state.
+The given scopes are added to the configuration's `defaultScopes`. The state is a random 32-character string unless you pass your own `state` argument. The `authorizationUrl` method also accepts a `scopeSeparator` and an array of `additionalQueryParameters`. Additional parameters may replace the standard ones, such as `response_type` for an OpenID Connect hybrid flow, but the URL's `state` always matches the returned state.
After the provider redirects to your application, exchange the code and validate the returned state:
@@ -1410,7 +1558,7 @@ $response = $github->send(
);
```
-If either state value is supplied, both values must be non-empty and equal. Keeping the state beside each authorization attempt allows one connector to support concurrent tabs and users without shared mutable state.
+If either state value is supplied, both values must be non-empty and equal, or Saloon throws an `InvalidStateException`. If the provider rejects the code, `getAccessToken` throws the token response's [request exception](#error-handling). Keeping the state beside each authorization attempt allows one connector to support concurrent tabs and users without shared mutable state.
You may pass a PKCE code challenge to `authorizationUrl` and the corresponding verifier to `getAccessToken`:
@@ -1448,7 +1596,7 @@ class ServiceConnector extends Connector
$authenticator = $connector->getAccessToken(['reports:read']);
```
-Use `ClientCredentialsBasicAuthGrant` when the provider requires the client credentials in an HTTP Basic authentication header.
+The given scopes are added to the configuration's `defaultScopes` and separated by spaces unless you pass a `scopeSeparator`. Client credentials connectors need no `redirectUri`. Use `ClientCredentialsBasicAuthGrant` when the provider requires the client credentials in an HTTP Basic authentication header.
OAuth token grant methods return an OAuth authenticator by default. Pass `returnResponse: true` when you need the original Saloon response instead:
@@ -1470,6 +1618,18 @@ if ($authenticator->hasExpired() && $authenticator->isRefreshable()) {
}
```
+To keep tokens between requests, store the authenticator's `accessToken`, `refreshToken`, and `expiresAt` properties and create a new authenticator from them when you need it. For example, you may store the tokens in [encrypted](/docs/{{version}}/eloquent-mutators#encrypted-casting) model attributes and [cast](/docs/{{version}}/eloquent-mutators#date-casting) the expiry attribute to `immutable_datetime`:
+
+```php
+use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
+
+$authenticator = new AccessTokenAuthenticator(
+ $user->github_access_token,
+ $user->github_refresh_token,
+ $user->github_token_expires_at,
+);
+```
+
OAuth token expiry values use immutable dates. Saloon rejects negative or unrepresentable expiry durations instead of creating an already-expired token.
Refresh requests use the configured `tokenEndpoint` by default. If your provider uses a separate endpoint, set `refreshEndpoint` on your `OAuthConfig`:
@@ -1563,7 +1723,7 @@ $responses = $github->pool(function (Connector $connector) use ($usernames) {
The callback runs each time the pool is sent, so a pool whose callback returns a new iterable each time may be sent again. A generator passed directly can only be sent once.
-The concurrency value must be a positive integer. Scheduling blocks when the bound is full, so a lazy iterable does not create an unbounded queue of child coroutines.
+The concurrency defaults to 5 and must be a positive integer. Each request is sent as the connector's `send` method would send it, so its retry policy, middleware, caching, and rate limits still apply. Scheduling blocks when the bound is full, so a lazy iterable does not create an unbounded queue of child coroutines.
You may also create an empty pool and configure it fluently before sending:
@@ -1585,7 +1745,7 @@ If a response handler owns each result and you do not need a response array, cal
$github->pool(
requests: $requests,
concurrency: 10,
- responseHandler: function (Response $response, string $key): void {
+ responseHandler: function (Response $response, int|string $key): void {
ProcessImportedUser::dispatch($key, $response->json());
},
)->process();
@@ -1601,7 +1761,7 @@ You may handle request failures while allowing the remaining requests to finish:
```php
$responses = $github->pool(
requests: $requests,
- exceptionHandler: function (Throwable $exception, string $key): void {
+ exceptionHandler: function (Throwable $exception, int|string $key): void {
report($exception);
},
)->send();
@@ -2303,7 +2463,25 @@ Saloon::fake([
]);
```
-Calling `fake` again adds responses to the same mock client, so a test may extend the fakes registered in its `setUp` method. To replace the global mock client instead, pass a `MockClient` instance to `fake`.
+The `make` method accepts a body, status code, and headers. An array body is encoded as JSON, while a string body is returned as it is:
+
+```php
+MockResponse::make(['message' => 'Not Found'], 404, [
+ 'Content-Type' => 'application/json',
+]);
+```
+
+To simulate a failed connection, pass an exception to the mock response's `throw` method. Saloon reports a `ConnectionException` as a `FatalRequestException`, just like a real connection failure:
+
+```php
+use Hypervel\Http\Client\ConnectionException;
+
+Saloon::fake([
+ GetUser::class => MockResponse::make()->throw(new ConnectionException('Connection refused')),
+]);
+```
+
+The fake belongs to the test application, so each test starts without one. Calling `fake` again adds responses to the same mock client, so a test may extend the fakes registered in its `setUp` method. To replace the global mock client instead, pass a `MockClient` instance to `fake`.
Responses may be matched by request class, connector class, or wildcard URL. Request matches take precedence over connector matches, followed by URL matches and sequence responses:
@@ -2321,6 +2499,21 @@ Each matching value may also be a callback that receives the pending request and
You may attach a mock client to one request using `withMockClient`, or pass it as the second argument to `Connector::send`. An explicitly supplied client takes precedence over a request client, which takes precedence over the facade's global test client. Mock responses are matched after request middleware has run and the URL is final, so URL matches see any changes middleware made.
+A local mock client is useful when testing an SDK's requests directly. It records every request sent with it, so you may make assertions on it:
+
+```php
+use Hypervel\Saloon\Http\Faking\MockClient;
+use Hypervel\Saloon\Http\Faking\MockResponse;
+
+$mockClient = new MockClient([
+ CreateIssue::class => MockResponse::make(['id' => 1], 201),
+]);
+
+$github->send(new CreateIssue('Bug report'), $mockClient);
+
+$mockClient->assertSent(fn (CreateIssue $request) => $request->body() === ['title' => 'Bug report']);
+```
+
Mock clients are strict by default. An unmatched request throws `NoMockResponseFoundException` instead of reaching the network.
To prevent every unmocked HTTP request from reaching the network, including a Saloon request sent without a mock client, use Hypervel HTTP's application-wide guard:
@@ -2374,6 +2567,7 @@ Saloon::assertSent(GetUser::class);
Saloon::assertSent('https://api.github.com/users/*');
Saloon::assertNotSent(DeleteUser::class);
Saloon::assertSentCount(1);
+Saloon::assertSentCount(1, GetUser::class);
Saloon::assertNothingSent();
```
@@ -2401,7 +2595,11 @@ Saloon::fake([
]);
```
-By default, fixtures are stored under `tests/Fixtures/Saloon`. Fixture names use portable path segments separated by forward slashes. Absolute paths, backslashes, empty segments, and `.` or `..` segments are rejected.
+You may also create a fixture using `MockResponse::fixture('github/users/hypervel')`. By default, fixtures are stored as JSON files under `tests/Fixtures/Saloon`, so this fixture is written to `tests/Fixtures/Saloon/github/users/hypervel.json`. To record a fixture again, delete its file and run the test.
+
+Fixture names use portable path segments separated by forward slashes. Absolute paths, backslashes, empty segments, and `.` or `..` segments are rejected. Lowercase names avoid fixtures going missing when a test suite moves between case-insensitive and case-sensitive filesystems.
+
+When `Http::preventStrayRequests()` is active, recording a missing fixture is a stray request and throws. Allow the API's URLs while recording, such as by calling `Http::allowStrayRequests(['https://api.github.com/*'])`.
To redact sensitive response data, extend `Fixture` and define header, JSON, or regular-expression replacement rules:
@@ -2425,7 +2623,7 @@ class GitHubFixture extends Fixture
}
```
-Header rules apply to each value of a matching header, so a closure receives one value and returns its replacement. Invalid or failed regular expressions prevent the fixture from being written. You may use `merge` or `through` to adjust a recorded JSON object or array during replay, and `withContext` to store additional fixture metadata.
+Header rules apply to each value of a matching header, so a closure receives one value and returns its replacement. Invalid or failed regular expressions prevent the fixture from being written. The rules change the stored file, so the test that records a fixture still receives the real response. A fixture class may also override `defineName` to return its name, so it can be created without arguments. You may use `merge` or `through` to adjust a recorded JSON object or array during replay, and `withContext` to store additional fixture metadata.
Mock responses and fixtures are cached like network responses. Once a cacheable request has been cached, later sends return the cached response instead of the next mock response or an updated fixture file, and a missing fixture is not recorded. Call `withoutCache` on the mock client to keep its requests from reading, writing, or invalidating the cache:
@@ -2442,7 +2640,7 @@ Saloon::fixturePath(base_path('tests/Fixtures/Api'));
Saloon::throwOnMissingFixtures();
```
-These are tests-only settings and are cleared when the test application is destroyed.
+These are tests-only settings and are cleared when the test application is destroyed. To fail on missing fixtures in every run, such as in CI, set the `saloon.fixtures.throw_on_missing` configuration option instead.
## Publishing Configuration and Stubs
@@ -2466,21 +2664,26 @@ Set `saloon.integrations_path` to change where generated files are written. When
## Differences From Saloon
-Hypervel Saloon keeps the connector, request, middleware, authentication, response, testing, OAuth 2, caching, pagination, and rate-limit concepts of Saloon while using Hypervel's framework services directly.
+Hypervel Saloon keeps the connector, request, middleware, authentication, response, testing, OAuth 2, caching, pagination, and rate-limit concepts of Saloon while using Hypervel's framework services directly. When porting an existing integration, note the following differences:
+
+
-- Hypervel HTTP is the only transport. Sender factories, configurable Guzzle senders, and process-global Saloon configuration are not included.
-- Request customization uses Hypervel HTTP names such as `withHeader`, `withQueryParameters`, `withOptions`, `timeout`, `withToken`, and `retry`.
-- Connectors contain stable defaults. Operation-specific authentication, caching, debugging, middleware, retries, and mocks belong to requests and pending requests.
-- Coroutine-native pools replace promises and `sendAsync`. Paginator concurrency uses the same bounded pool.
-- Cache, pagination, and rate limiting are included in `hypervel/saloon` and use Hypervel's cache, collections, coroutine, and rate-limiter services.
+- The Laravel plugin and the cache, pagination, and rate-limit plugins are built in, using Hypervel's cache, collections, coroutine, and rate-limiter services.
+- Hypervel HTTP is the only transport. Requests are sent through a named [HTTP connection](#http-connections) instead of a sender, and there is no process-global `Config` class; register global middleware through `Saloon::middleware()`.
+- Requests and pending requests use the HTTP client's method names, such as `withHeader`, `withQueryParameters`, `withOptions`, `timeout`, and `withToken`, and their getters return plain values instead of upstream's repositories.
+- Connectors are read-only, since one connector may be shared by concurrent requests. Operation-specific authentication, middleware, debugging, mocks, and retries belong to requests, the `send` call, or the connector's `boot` method.
+- Retries use `retry` and `defaultRetryPolicy` instead of the `$tries`, `$retryInterval`, `$useExponentialBackoff`, and `$throwOnMaxTries` properties.
+- Coroutine-native [pools](#concurrent-requests) replace `sendAsync` and promises. Paginator concurrency uses the same bounded pool.
+- Responses extend Hypervel HTTP responses. Request exceptions extend the HTTP client's `RequestException` rather than `SaloonException`, so catch `RequestException` for failed responses.
+- Mock clients are matched when the request is sent, after request middleware has run. Fixture settings are configured through the `Saloon` facade and configuration file, and application-wide stray-request protection uses `Http::preventStrayRequests()`, which also applies to fixture recording.
+- OAuth 2 configuration is immutable, and authorization URLs return their paired state.
+- NTLM authentication is not included.
- Rate limits use Hypervel `AdmissionPolicy` instances instead of Saloon's mutable limit and store abstractions.
-- OAuth 2 configuration is immutable, authorization URLs return their paired state, and OAuth 1 is not included.
-- Saloon responses extend Hypervel HTTP responses rather than forwarding a selected subset of methods.
-- Test fixture settings are configured through the `Saloon` facade instead of a process-global mock configuration object.
-- Application-wide stray-request protection uses `Http::preventStrayRequests()`. Saloon mock clients separately control unmatched requests while they are active.
- The `xmlReader` response method is not included. Use the `xml` or `dom` methods, or install [XML Wrangler](https://github.com/saloonphp/xml-wrangler) and pass `$response->toPsrResponse()` to `XmlReader::fromPsrResponse()`.
-These differences remove framework-neutral adapter layers while retaining the public concepts needed to build complete integrations and reusable SDKs for Hypervel.
+
+
+The [package README](https://github.com/hypervel/components/blob/0.4/src/saloon/README.md) documents API differences and their Hypervel equivalents.
## Credits
diff --git a/src/saloon/README.md b/src/saloon/README.md
index 8fa31ea927..5322137e8f 100644
--- a/src/saloon/README.md
+++ b/src/saloon/README.md
@@ -8,7 +8,7 @@ Requests and pending requests use fluent methods in the style of Hypervel's HTTP
Connectors are read-only. Their headers, query parameters, options, body, authenticator and delay come from their `default*` methods and constructor values, because a connector may be shared by concurrent requests. Apply per-operation values to the request, or change connector defaults on the pending request in a hook or middleware. Connectors have no `middleware()` or debugging methods; register middleware and debuggers on the pending request from `boot()` or a plugin. For the same reason, requests and connectors allow absolute endpoints by overriding `allowsBaseUrlOverride()`; upstream's public `$allowBaseUrlOverride` property has no effect. `HasApiVersion` has no `setApiVersion()`: assign `$apiVersion` in the constructor or override `getApiVersion()`.
-There is no process-global `Config` class and no pluggable sender. Global middleware is `Saloon::middleware()`. Requests are sent through Hypervel's HTTP client on a named connection, `saloon.connection.name` or the connector's `resolveHttpConnection()`, so `sender()`, `defaultSender()`, sender resolvers, handler stacks and the sender's factory collection are not available; use the connection's options, `Http::globalMiddleware()`, or Saloon's PSR request hooks and middleware. Body repositories' `toStream()` and fake responses' `createPsrResponse()` take no PSR factories. Telescope's HTTP client watcher records Saloon requests with the `saloon` tag in place of the plugin's Telescope middleware, so fakes and cache hits are not recorded. The plugin's Pulse and Nightwatch middleware are not included, since Hypervel has neither package; OpenTelemetry's HTTP client instrumentation traces Saloon requests like other HTTP client requests. Prevent stray requests with `Http::preventStrayRequests()`, which throws the HTTP client's `StrayRequestException`, fake sleeping with `Sleep::fake()`, and control the clock through the framework `Date` clock.
+There is no process-global `Config` class and no pluggable sender. Global middleware is `Saloon::middleware()`. Requests are sent through Hypervel's HTTP client on a named connection, `saloon.connection.name` or the connector's `resolveHttpConnection()`, so `sender()`, `defaultSender()`, sender resolvers, handler stacks and the sender's factory collection are not available; use the connection's options, `Http::globalMiddleware()`, or Saloon's PSR request hooks and middleware. Body repositories' `toStream()` and fake responses' `createPsrResponse()` take no PSR factories. Telescope's HTTP client watcher records Saloon requests with the `saloon` tag in place of the plugin's Telescope middleware, so fakes and cache hits are not recorded. The plugin's Pulse and Nightwatch middleware are not included, since Hypervel has neither package; OpenTelemetry's HTTP client instrumentation traces Saloon requests like other HTTP client requests. Prevent stray requests with `Http::preventStrayRequests()`, which throws the HTTP client's `StrayRequestException`, including for a request that would record a missing fixture, so allow the API's URLs with `Http::allowStrayRequests()` while recording. Fake sleeping with `Sleep::fake()`, and control the clock through the framework `Date` clock.
`createPendingRequest()` takes no mock client. Mock clients are chosen and matched when the request is sent, after request middleware has run and the URL is final, so middleware does not see a mock response and pending requests have no `hasMockClient()` or `getMockClient()`.
From e7d907fa781e67e8beed306202348952f43bf772 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Wed, 7 Oct 2026 05:25:20 +0000
Subject: [PATCH 20/26] Reconcile the remaining Saloon documentation with
upstream
The rest of Saloon v3's documentation was compared with the guide:
pagination, caching, rate limits, the Laravel plugin, building
plugins, the how-to guides and the upgrade and known-issue pages.
Every claim and example was checked against Hypervel's source.
Added: plugin boot methods must be public, plugins change the pending
request, and a plugin on both a connector and its request boots twice.
Fetching a token from a connector's boot method, which can't be
combined with RequiresAuth because its check runs first. Choosing the
cacheable methods. Paginators yield one page response at a time, keep
only that page in memory and throw for a failed page; iterator_count
cannot find the last page; the default page size, offsets and custom
paginators. Saloon accepts fixed, calendar and sliding windows and
leaky buckets, per-user by keys, the exception's wait time, the
default store and disabling 429 cooldowns. Requests require TLS 1.2
unless the connection changes crypto_method.
The README's differences heading now names Saloon and lists all five
upstream repositories. The sync notes say where future upstream
changes, plugin test cases and documentation belong, and which
upstream pages have no Hypervel equivalent. A colon in one note made
sync.yaml invalid YAML; it parses again.
Validation: documentation only. A nested send from a connector's boot
method was confirmed with a temporary test. Every guide link and README
anchor resolves.
---
docs/upstream-sync/sync.yaml | 6 ++--
src/docs/saloon.md | 61 +++++++++++++++++++++++++++---------
src/saloon/README.md | 10 ++++--
3 files changed, 58 insertions(+), 19 deletions(-)
diff --git a/docs/upstream-sync/sync.yaml b/docs/upstream-sync/sync.yaml
index 55cb1da254..749c225473 100644
--- a/docs/upstream-sync/sync.yaml
+++ b/docs/upstream-sync/sync.yaml
@@ -182,14 +182,14 @@ saloonphp/saloon:
checked_through: null
last_reviewed_pr: null
sync_date: null
- notes: Core of the unified hypervel/saloon package, together with the four plugin entries and shared documentation below. Upstream's connector send path and senders map to SaloonManager and Http/Sender, which use Hypervel's HTTP client; pools use coroutines. The PendingRequest constructor lifecycle maps to SaloonManager::createPendingRequest (properties merge in the PendingRequest constructor and plugins boot after it), mock clients are selected and matched in SaloonManager::send after request middleware rather than stored on the pending request, and Helpers/URLHelper maps to Http/UrlResolver. Upstream's Config maps to the manager's global middleware, the saloon.connection settings and the framework Date, Sleep and Http stray-request APIs; Helpers/RequestExceptionHelper maps to Response::newRequestException. Upstream's retry loop and DelayMiddleware map to SaloonManager::send, and its retry properties and handleRetry() methods map to Data/RetryPolicy and the defaultRetryPolicy() hooks. Helpers/OAuth2/OAuthConfig maps to the immutable Data/OAuthConfig, and token-response parsing shared by the OAuth grant traits lives in Traits/OAuth2/ParsesOAuthTokenResponses. Assess upstream changes against these framework integrations and preserve supported SDK-generator extension points. Upstream tests and fixtures map to the same paths under tests/Saloon/{Unit,Feature,Fixtures}; cases that call upstream's live test API use the engine test server under tests/Integration/Saloon instead. Public contract differences belong in src/saloon/README.md.
+ notes: Core of the unified hypervel/saloon package, together with the four plugin entries and shared documentation below. Upstream's connector send path and senders map to SaloonManager and Http/Sender, which use Hypervel's HTTP client; pools use coroutines. The PendingRequest constructor lifecycle maps to SaloonManager::createPendingRequest (properties merge in the PendingRequest constructor and plugins boot after it), mock clients are selected and matched in SaloonManager::send after request middleware rather than stored on the pending request, and Helpers/URLHelper maps to Http/UrlResolver. Upstream's Config maps to the manager's global middleware, the saloon.connection settings and the framework Date, Sleep and Http stray-request APIs; Helpers/RequestExceptionHelper maps to Response::newRequestException. Upstream's retry loop and DelayMiddleware map to SaloonManager::send, and its retry properties and handleRetry() methods map to Data/RetryPolicy and the defaultRetryPolicy() hooks. Helpers/OAuth2/OAuthConfig maps to the immutable Data/OAuthConfig, and token-response parsing shared by the OAuth grant traits lives in Traits/OAuth2/ParsesOAuthTokenResponses. Assess upstream changes against these framework integrations and preserve supported SDK-generator extension points. Upstream tests and fixtures map to the same paths under tests/Saloon/{Unit,Feature,Fixtures}; cases that call upstream's live test API use the engine test server under tests/Integration/Saloon instead. src/saloon/README.md lists the deliberate public differences across all five entries, with their reasons and Hypervel equivalents; check them against current source before applying an upstream change they affect, and keep the README current.
saloonphp/laravel-plugin:
branch: v4
checked_through: null
last_reviewed_pr: null
sync_date: null
- notes: Part of the unified src/saloon package; reconcile alongside the core entry rather than creating a separate package. Provider, config, console, facade and event changes map to SaloonServiceProvider, config/saloon.php, Console, Facades and Events. Upstream's HTTP layer is a mock client and middleware, not a sender. Fakes and fixture recording map to SaloonManager and Http/Faking, SaloonManager dispatches the request events, and Telescope support comes from the framework HTTP client watcher through Http/Sender's Telescope tags. Tests map to tests/Saloon/Hypervel and use the core fixtures, which the plugin's fixtures copy; the plugin's Feature/PoolTest and Feature/RequestTest repeat core cases and are covered by the core tests.
+ notes: Part of the unified src/saloon package; reconcile alongside the core entry rather than creating a separate package. Provider, config, console, facade and event changes map to SaloonServiceProvider, config/saloon.php, Console, Facades and Events. Upstream's Http directory holds a MockClient subclass and observability middleware rather than a sender. Fakes and fixture recording map to SaloonManager and Http/Faking, SaloonManager dispatches the request events, and Telescope support comes from the framework HTTP client watcher through Http/Sender's Telescope tags. Tests map to tests/Saloon/Hypervel and use the core fixtures, which the plugin's fixtures copy. The plugin's Feature/PoolTest and Feature/RequestTest repeat core cases, so merge their new or changed cases into tests/Saloon/Feature/PoolTest and tests/Integration/Saloon/Feature/{PoolTest,RequestTest}, keeping plugin-specific setup such as Saloon::fake(), rather than adding separate copies.
saloonphp/cache-plugin:
branch: v3
@@ -217,7 +217,7 @@ Sammyjo20/saloon-docs:
checked_through: null
last_reviewed_pr: null
sync_date: null
- notes: Shared documentation for the unified src/saloon package and all four plugin entries above, mapped to src/docs/saloon.md. The v3 branch includes v4 guidance; verify examples against the tracked source and Hypervel's integrations, using Laravel-style prose.
+ notes: Shared documentation for the unified src/saloon package and all four plugin entries above. Reconcile applicable core and plugin pages into the existing sections of the single src/docs/saloon.md rather than separate plugin guides, keeping Hypervel's additions and checking examples against current source, in Laravel-style prose matching the guide. The v3 branch includes v4 guidance. Installation commands, supported versions, upgrade guides, release notes, showcase, tutorials, the book and the third-party Lawman and SDK generator pages have no Hypervel equivalent; check them only for behavior the guide must still describe.
getsentry/sentry-laravel:
branch: master
diff --git a/src/docs/saloon.md b/src/docs/saloon.md
index 3642f947a4..7844fef415 100644
--- a/src/docs/saloon.md
+++ b/src/docs/saloon.md
@@ -301,7 +301,7 @@ Your resource may access the connector through its protected, readonly `$connect
Saloon registers one named Hypervel [HTTP connection](/docs/{{version}}/http-client#connections), named `saloon` by default. Synchronous requests through this connection reuse the low-level transport, allowing cURL to retain keep-alive sockets, DNS information, and TLS sessions. Each operation still receives its own pending request, client, middleware stack, and cookie jar.
-The `saloon` connection uses a 10-second connection timeout and a 30-second request timeout. You may [publish the configuration file](#publishing-configuration-and-stubs) to change its options. A connector may also select another connection that your application registers during worker boot:
+The `saloon` connection uses a 10-second connection timeout and a 30-second request timeout. Like other HTTP client requests, Saloon requests require TLS 1.2 or later unless the connection sets another `crypto_method` option. You may [publish the configuration file](#publishing-configuration-and-stubs) to change its options. A connector may also select another connection that your application registers during worker boot:
```php
use Hypervel\Support\Facades\Http;
@@ -727,6 +727,28 @@ class GetPrivateReport extends Request
You may also add the trait to a connector to require authentication for every request in that integration. Saloon throws `MissingAuthenticatorException` before sending an unauthenticated request. You may override `getRequiresAuthMessage(PendingRequest $pendingRequest): string` when the integration needs a more specific message.
+Some APIs require you to request a token before calling other endpoints. A connector's `boot` method may send that request and authenticate the pending request with the result:
+
+```php
+use Hypervel\Saloon\Http\Auth\TokenAuthenticator;
+use Hypervel\Saloon\Http\PendingRequest;
+
+public function boot(PendingRequest $pendingRequest): void
+{
+ if ($pendingRequest->request() instanceof GetAccessToken) {
+ return;
+ }
+
+ $token = $this->send(new GetAccessToken($this->username, $this->password))
+ ->throw()
+ ->json('token');
+
+ $pendingRequest->authenticate(new TokenAuthenticator($token));
+}
+```
+
+The early return stops the token request from requesting a token itself. Don't combine this with `RequiresAuth`, which checks for an authenticator before `boot` runs. When the API's tokens last longer than one request, you may store the token in your application's [cache](/docs/{{version}}/cache) until it expires.
+
### Request Bodies
@@ -1154,7 +1176,7 @@ The connector hook runs before the request hook. Each hook runs once on the fina
### Plugins
-Plugins are traits with a boot method named after the trait. They allow connector and request behavior to be shared without another service layer:
+Plugins are traits with a public boot method named after the trait. They allow connector and request behavior to be shared without another service layer:
```php
use Hypervel\Saloon\Http\PendingRequest;
@@ -1169,7 +1191,7 @@ trait AddsRequestId
}
```
-Use the trait on any connector or request. Saloon discovers plugin boot methods once per concrete class and invokes them for each operation.
+Use the trait on any connector or request. Saloon discovers plugin boot methods once per concrete class and invokes them for each operation. Change the pending request in a plugin rather than the connector or request, since a connector may be shared by concurrent operations. A plugin used by both a connector and its request boots twice.
Connector plugins boot before request plugins, and the request is authenticated once every plugin has booted. This lets an authenticator use the URL and headers set by plugins, such as an [API version](#api-versions) in the host. A plugin may select the authenticator by calling `authenticate` on the pending request; Saloon applies it after the remaining plugins boot. The connector and request `boot` methods and request middleware run after authentication, so calling `authenticate` there applies the authenticator immediately.
@@ -1809,7 +1831,18 @@ A null store uses `saloon.cache.store`, which itself falls back to Hypervel's de
An integer cache duration is measured in seconds. You may also return a `DateInterval` or `DateTimeInterface` instance.
-GET, HEAD, OPTIONS, and QUERY requests are cacheable by default. A response is written unless it failed, including failures defined by a request or connector's [failure check](#error-handling). Mock responses and fixtures are cached like network responses, so a cached response is returned before the mock client is consulted. See [Fixtures](#fixtures) for keeping tests out of the cache.
+GET, HEAD, OPTIONS, and QUERY requests are cacheable by default. To change which methods are eligible, override `cacheableMethods` on the connector, or on a request using the [`HasCaching` trait](#request-cache-controls). A request's list takes precedence over its connector's:
+
+```php
+use Hypervel\Saloon\Enums\Method;
+
+protected function cacheableMethods(): array
+{
+ return [Method::GET, Method::POST];
+}
+```
+
+A response is written unless it failed, including failures defined by a request or connector's [failure check](#error-handling). Mock responses and fixtures are cached like network responses, so a cached response is returned before the mock client is consulted. See [Fixtures](#fixtures) for keeping tests out of the cache.
The default cache key includes the connector and request classes, method, final URI, headers, cookies, authentication and certificate state, prepared body, and response-affecting transport options. This means a QUERY request's body is part of its identity. Responses cached from streaming bodies are buffered because the cache must retain their bytes.
@@ -1876,8 +1909,6 @@ protected function cacheKey(PendingRequest $pendingRequest): ?string
Saloon hashes custom keys before passing them to the cache backend, so raw credentials and tenant identifiers are not exposed in backend key names. A custom key must include every value that can change the successful response. It is required when a non-seekable request body is cached or when lower-level PSR or HTTP middleware changes response identity after Saloon finalizes the operation.
-You may override `cacheableMethods` to change which methods are eligible. A request override takes precedence over the connector's list.
-
### Cache Scopes
@@ -1914,7 +1945,7 @@ Authentication state already separates tenant-owned credentials, and the final U
Saloon pagination iterates through pages returned by a remote API. It is separate from Hypervel's [application pagination](/docs/{{version}}/pagination), which prepares local data for views and JSON responses.
-A paginated request must implement the `Paginatable` marker contract. Create a paginator class for the remote API's pagination format.
+A paginated request must implement the `Paginatable` marker contract. Create a paginator class for the remote API's pagination format. Saloon includes page, offset, cursor, link, and link header paginators. For another format, extend `Paginator` and implement `applyPagination`, `isLastPage`, and `getPageItems`, using the protected `$pageNumber` and `$perPageLimit` properties to build each page's request.
### Page Pagination
@@ -1988,9 +2019,9 @@ $users = $paginator->collect();
The `HasPagination` contract provides the conventional connector entry point. A request that needs its own paginator may implement `HasRequestPagination` and define `paginate(Connector $connector): Paginator`; the connector can delegate to it as shown above. Declare the request's item type with `@implements HasRequestPagination` and `@return Paginator` on its `paginate` method.
-The `collect(false)` method returns a lazy collection of page responses instead of items. Declare the paginator's item type with `@extends PagedPaginator` (or the matching base class) to preserve it through `items` and `collect`. You may also inspect `totalResults`, `request`, and the zero-based iterator position returned by `currentPage`. Use `startPage` to configure the first remote page number.
+Iterating the paginator itself yields each page's response, and only the current page is kept in memory. A page response that would [throw](#error-handling) stops iteration with its request exception. The `collect(false)` method returns a lazy collection of page responses instead of items. To return data objects, map them in `getPageItems` and declare the paginator's item type with `@extends PagedPaginator` (or the matching base class) to preserve it through `items` and `collect`. You may also inspect `totalResults`, `request`, and the zero-based iterator position returned by `currentPage`. Use `startPage` to configure the first remote page number.
-Calling `count($paginator)` counts remote pages by requesting each page. It is not a metadata-only operation.
+Calling `count($paginator)` counts remote pages by requesting each page. It is not a metadata-only operation. Do not use `iterator_count`, which never loads a page and so cannot find the last one.
Override the protected query-name properties when an API uses different names:
@@ -2000,7 +2031,7 @@ protected string $pageName = 'currentPage';
protected string $perPageName = 'pageSize';
```
-`PagedPaginator` defaults to `page` and `per_page`. `OffsetPaginator` provides `$limitName` and `$offsetName`, defaulting to `limit` and `offset`; `CursorPaginator` provides `$cursorName` and `$perPageName`, defaulting to `cursor` and `per_page`. Override `applyPagination(Request $request): Request` for a protocol that needs a different request structure.
+`PagedPaginator` defaults to `page` and `per_page`, and sends a page size only when a per-page limit is set. To send one by default, declare `protected ?int $perPageLimit = 100;` on your paginator. `OffsetPaginator` provides `$limitName` and `$offsetName`, defaulting to `limit` and `offset`; `CursorPaginator` provides `$cursorName` and `$perPageName`, defaulting to `cursor` and `per_page`. Override `applyPagination(Request $request): Request` for a protocol that needs a different request structure.
During sequential pagination, Saloon throws a `PaginationException` if five consecutive pages return the same response body. Check that your paginator correctly identifies the last page. Retrying the current page does not count as another page. If your API legitimately returns identical pages, you may disable this check by declaring `protected bool $detectInfiniteLoop = false;` on your paginator.
@@ -2018,7 +2049,7 @@ If a request implements `MapPaginatedResponseItems`, its `mapPaginatedResponseIt
### Offset and Cursor Pagination
-Extend `OffsetPaginator` for APIs that use `limit` and `offset`. A per-page limit must be configured before iteration. Extend `CursorPaginator` for APIs where each response supplies the next cursor, and implement `getNextCursor`.
+Extend `OffsetPaginator` for APIs that use `limit` and `offset`. A per-page limit must be configured before iteration, and the protected `getOffset` method returns the current page's offset, such as for comparison with a total in `isLastPage`. Extend `CursorPaginator` for APIs where each response supplies the next cursor, and implement `getNextCursor`.
Cursors may be strings, numbers, booleans, or null. The default query encoding omits null and sends booleans as `1` or `0`. Override `applyPagination` when your API requires another encoding, and use `isLastPage` to determine when pagination ends.
@@ -2136,7 +2167,9 @@ class GitHubConnector extends Connector
}
```
-By default, a denied policy throws `RateLimitReachedException` before reaching the network. Override `waitForRateLimits` to sleep until capacity is available instead. It receives the denied policy and its decision, so you may wait out a short burst limit while still throwing for a daily quota:
+A policy may be a [fixed, calendar or sliding window, or a leaky bucket](/docs/{{version}}/rate-limiting#choosing-a-rate-limit). For example, a quota that resets at the end of each minute or day suits a calendar window, while an API that refills capacity continuously suits a leaky bucket. Give each user or API key its own limit with a distinct `by` key.
+
+By default, a denied policy throws `RateLimitReachedException` before reaching the network. The exception's `policy` and `result` methods return the denied policy and its decision, so `$exception->result()->retryAfter()` gives the number of seconds to wait. Override `waitForRateLimits` to sleep until capacity is available instead. It receives the denied policy and its decision, so you may wait out a short burst limit while still throwing for a daily quota:
```php
use Hypervel\RateLimiter\AdmissionPolicy;
@@ -2149,7 +2182,7 @@ protected function waitForRateLimits(AdmissionPolicy|Cooldown $policy, Decision
}
```
-You may select another configured rate-limiter store by overriding `resolveRateLimitStore`. Fakes and cache hits do not consume capacity.
+Limits are stored in the rate-limiter store named by the `saloon.rate_limiter.store` configuration value, or the rate limiter's default store when it is `null`. A connector or request may return another configured [store](/docs/{{version}}/rate-limiting#available-stores) name from `resolveRateLimitStore`. Fakes and cache hits do not consume capacity.
Saloon [consumes each resource's policies together](/docs/{{version}}/rate-limiting#consuming-multiple-limits), subject to the documented Redis Cluster limitation. Connector and request limits are separate: the connector is admitted first, so its charge remains if the request's limits deny the operation. After waiting for capacity, Saloon checks the resource's cooldown again before retrying its policies.
@@ -2208,7 +2241,7 @@ protected function resolveRateLimitCooldownKey(PendingRequest $pendingRequest):
Do not infer this key from a hostname or assume every provider limits by token. Use the boundary documented by the provider.
-You may override `resolveRateLimitCooldown` to support a provider-specific response or clamp a provider-defined maximum:
+You may override `resolveRateLimitCooldown` to support a provider-specific response or clamp a provider-defined maximum. Returning `null` records no cooldown:
```php
use Hypervel\RateLimiter\AdmissionPolicy;
diff --git a/src/saloon/README.md b/src/saloon/README.md
index 5322137e8f..f36f51d8f9 100644
--- a/src/saloon/README.md
+++ b/src/saloon/README.md
@@ -2,7 +2,7 @@
Documentation: https://hypervel.org/docs/saloon
-## Differences From Laravel
+## Differences From Saloon
Requests and pending requests use fluent methods in the style of Hypervel's HTTP client, such as `withHeaders`, `withoutHeader`, `withQueryParameters`, `withOptions` and `delay`, and their getters return plain values. Upstream's `ArrayStore` and `IntegerStore` objects (`headers()->add()`, `query()->remove()`, `delay()->set()`) are not available: `headers()` returns an array, `queryParameters()` and `delayMilliseconds()` replace the `query()` and `delay()` getters, and upstream's `config()` and `defaultConfig()` are `options()` and `defaultOptions()`. Getters drop upstream's `get` prefix, so requests have `method()` and `mockClient()`, and pending requests have `connector()`, `request()`, `method()` and `fakeResponse()`; compare `fakeResponse()` with `null` in place of `hasFakeResponse()`. Pending requests change the method and URL with `withMethod` and `withUrl` instead of `setMethod` and `setUrl`, `uri()` replaces `getUrl()`, including the query string, and `resolveResponseClass($response)` returns the custom response class, or `null` for the default, in place of `getResponseClass()`.
@@ -44,4 +44,10 @@ The upstream NTLM authenticator is omitted. Integrations requiring NTLM must sup
OAuth 2 configuration is an immutable `Data\OAuthConfig` built from constructor arguments and read through public properties, replacing upstream's `Helpers\OAuth2\OAuthConfig` setters and getters, so connectors define `defaultOAuthConfig()` and per-call changes use the grant methods' `requestModifier`. `invokeRequestModifier()` is `modify()`. `authorizationUrl()` returns an `AuthorizationUrl` holding the URL and its state, instead of `getAuthorizationUrl()` storing the state on the shared connector for `getState()`. Additional authorization parameters cannot replace that state, and if `getAccessToken()` receives either state, both must be non-empty and equal. `getUser()` applies the configuration's request modifier before the per-call one, as the token methods do, and its request sends no form `Content-Type`. See [OAuth 2](https://hypervel.org/docs/saloon#oauth2).
-Ported from: https://github.com/saloonphp/saloon
+Ported from:
+
+- https://github.com/saloonphp/saloon
+- https://github.com/saloonphp/laravel-plugin
+- https://github.com/saloonphp/cache-plugin
+- https://github.com/saloonphp/pagination-plugin
+- https://github.com/saloonphp/rate-limit-plugin
From d899a52163d48ac6feb4fbb244ab7dfbbe3e3abf Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Wed, 7 Oct 2026 05:44:03 +0000
Subject: [PATCH 21/26] Replace deprecated exception message expectations in
Saloon tests
PHPUnit 13.3 deprecates expectExceptionMessage(). The Saloon and
calendar-window tests changed on this branch now use
expectExceptionMessageIs() for complete messages, which is stricter,
and expectExceptionMessageIsOrContains() where a test checks part of a
message: delay validation, the base-URL replacement message's first
sentence, and a missing fixture's environment-dependent path. The
fixture-name and duplicate-pipe expectations now include the messages'
final period.
---
tests/RateLimiter/CalendarWindowTest.php | 2 +-
tests/Saloon/Cache/Feature/CacheTest.php | 2 +-
tests/Saloon/Feature/Body/HasJsonBodyTest.php | 2 +-
tests/Saloon/Feature/DelayRequestTest.php | 4 ++--
tests/Saloon/Feature/MockRequestTest.php | 4 ++--
.../Feature/Oauth2/AuthCodeFlowConnectorTest.php | 14 +++++++-------
.../Oauth2/ClientCredentialsFlowConnectorTest.php | 4 ++--
tests/Saloon/Feature/RetryConnectorTest.php | 4 ++--
tests/Saloon/Feature/RetryRequestTest.php | 6 +++---
.../Hypervel/Unit/MockClientAssertionsTest.php | 4 ++--
.../Pagination/Feature/AsyncPaginationTest.php | 2 +-
tests/Saloon/Pagination/Feature/PaginationTest.php | 2 +-
tests/Saloon/Unit/AuthenticatorTest.php | 2 +-
tests/Saloon/Unit/Body/ArrayBodyRepositoryTest.php | 2 +-
.../Unit/Body/MultipartBodyRepositoryTest.php | 6 +++---
tests/Saloon/Unit/ConfigTest.php | 2 +-
tests/Saloon/Unit/MiddlewarePipelineTest.php | 8 ++++----
tests/Saloon/Unit/MockClientTest.php | 6 +++---
tests/Saloon/Unit/MockConfigTest.php | 2 +-
tests/Saloon/Unit/MultipartValueTest.php | 4 ++--
.../Unit/Oauth2/AuthCodeFlowConnectorTest.php | 6 +++---
tests/Saloon/Unit/Oauth2/OAuthConfigTest.php | 6 +++---
tests/Saloon/Unit/PendingRequestTest.php | 4 ++--
tests/Saloon/Unit/RequestTest.php | 6 +++---
tests/Saloon/Unit/URLHelperTest.php | 8 ++++----
25 files changed, 56 insertions(+), 56 deletions(-)
diff --git a/tests/RateLimiter/CalendarWindowTest.php b/tests/RateLimiter/CalendarWindowTest.php
index 276b6aa1c6..60fee66d31 100644
--- a/tests/RateLimiter/CalendarWindowTest.php
+++ b/tests/RateLimiter/CalendarWindowTest.php
@@ -197,7 +197,7 @@ public static function windowProvider(): array
public function testWindowsEndingBeyondTheSupportedRangeAreRejected(): void
{
$this->expectException(InvalidRateLimitException::class);
- $this->expectExceptionMessage('The rate limiter timestamp exceeds the supported integer range.');
+ $this->expectExceptionMessageIs('The rate limiter timestamp exceeds the supported integer range.');
CalendarWindow::perMonth(1)->timezone('UTC')->window(AdmissionPolicy::MAX_INTEGER - 1);
}
diff --git a/tests/Saloon/Cache/Feature/CacheTest.php b/tests/Saloon/Cache/Feature/CacheTest.php
index 71e532286f..cc3a84f9c3 100644
--- a/tests/Saloon/Cache/Feature/CacheTest.php
+++ b/tests/Saloon/Cache/Feature/CacheTest.php
@@ -441,7 +441,7 @@ public function testItThrowsAnExceptionIfYouUseTheHasCachingTraitWithoutTheCache
$request = new CachedUserRequestWithoutCacheable;
$this->expectException(CachingException::class);
- $this->expectExceptionMessage('The request or connector must implement [Hypervel\Saloon\Cache\Contracts\Cacheable] when using request cache controls.');
+ $this->expectExceptionMessageIs('The request or connector must implement [Hypervel\Saloon\Cache\Contracts\Cacheable] when using request cache controls.');
$connector->send($request, $mockClient);
}
diff --git a/tests/Saloon/Feature/Body/HasJsonBodyTest.php b/tests/Saloon/Feature/Body/HasJsonBodyTest.php
index 3718359e21..5af4e80d3d 100644
--- a/tests/Saloon/Feature/Body/HasJsonBodyTest.php
+++ b/tests/Saloon/Feature/Body/HasJsonBodyTest.php
@@ -104,7 +104,7 @@ public function testWhenBothTheConnectorAndTheRequestHaveTheSameRequestBodiesThe
public function testIfTheConnectorAndRequestImplementDifferentBodyRepositoriesThenAnExceptionIsThrown(): void
{
$this->expectException(PendingRequestException::class);
- $this->expectExceptionMessage('Connector and request body types must be the same.');
+ $this->expectExceptionMessageIs('Connector and request body types must be the same.');
$this->pendingRequest(new HasJsonBodyConnector, new HasMultipartBodyRequest);
}
diff --git a/tests/Saloon/Feature/DelayRequestTest.php b/tests/Saloon/Feature/DelayRequestTest.php
index 8d91998017..6b2f12804c 100644
--- a/tests/Saloon/Feature/DelayRequestTest.php
+++ b/tests/Saloon/Feature/DelayRequestTest.php
@@ -175,7 +175,7 @@ public function testAnExplicitZeroDelayOverridesTheConnectorDelay(): void
public function testItRejectsNegativeDelays(): void
{
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('representable non-negative');
+ $this->expectExceptionMessageIsOrContains('representable non-negative');
$this->request()->delay(-1);
}
@@ -183,7 +183,7 @@ public function testItRejectsNegativeDelays(): void
public function testItRejectsDelaysThatOverflowMicroseconds(): void
{
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('representable non-negative');
+ $this->expectExceptionMessageIsOrContains('representable non-negative');
$this->request()->delay(intdiv(PHP_INT_MAX, 1000) + 1);
}
diff --git a/tests/Saloon/Feature/MockRequestTest.php b/tests/Saloon/Feature/MockRequestTest.php
index 57a74182a2..44a1a420da 100644
--- a/tests/Saloon/Feature/MockRequestTest.php
+++ b/tests/Saloon/Feature/MockRequestTest.php
@@ -148,7 +148,7 @@ public function testARequestCanBeMockedWithASequence(): void
$this->assertInstanceOf(MockResponse::class, $responseC->fakeResponse());
$this->expectException(NoMockResponseFoundException::class);
- $this->expectExceptionMessage('Saloon was unable to guess a mock response for your request [https://tests.saloon.dev/api/user], consider using a wildcard url mock or a connector mock.');
+ $this->expectExceptionMessageIs('Saloon was unable to guess a mock response for your request [https://tests.saloon.dev/api/user], consider using a wildcard url mock or a connector mock.');
$connector->send(new UserRequest);
}
@@ -598,7 +598,7 @@ public function testItWillThrowAnExceptionIfTheCustomFixtureClassIsMissingAName(
]);
$this->expectException(FixtureException::class);
- $this->expectExceptionMessage('The fixture must have a name');
+ $this->expectExceptionMessageIs('The fixture must have a name.');
(new TestConnector)->send(new UserRequest, $mockClient);
}
diff --git a/tests/Saloon/Feature/Oauth2/AuthCodeFlowConnectorTest.php b/tests/Saloon/Feature/Oauth2/AuthCodeFlowConnectorTest.php
index cd73fe6a1e..7da2cfb3a8 100644
--- a/tests/Saloon/Feature/Oauth2/AuthCodeFlowConnectorTest.php
+++ b/tests/Saloon/Feature/Oauth2/AuthCodeFlowConnectorTest.php
@@ -342,7 +342,7 @@ public function testAnInvalidRefreshTokenIsRejected(): void
Saloon::fake([MockResponse::make(['access_token' => 'access', 'refresh_token' => []])]);
$this->expectException(UnexpectedValueException::class);
- $this->expectExceptionMessage('The OAuth token response contains an invalid refresh token.');
+ $this->expectExceptionMessageIs('The OAuth token response contains an invalid refresh token.');
(new OAuth2Connector)->getAccessToken('code');
}
@@ -355,7 +355,7 @@ public function testItWillThrowAnExceptionIfStateIsInvalid(): void
$connector->authorizationUrl(['scope-1', 'scope-2'], $state);
$this->expectException(InvalidStateException::class);
- $this->expectExceptionMessage('Invalid state.');
+ $this->expectExceptionMessageIs('Invalid state.');
$connector->getAccessToken('code', 'invalid', $state);
}
@@ -445,7 +445,7 @@ public function testTheRefreshAccessTokenMethodThrowsAnExceptionIfYouProvideItAn
$authenticator = new AccessTokenAuthenticator('access', null, Date::now()->addSeconds(3600)->toDateTimeImmutable());
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('The provided OAuthAuthenticator does not contain a refresh token.');
+ $this->expectExceptionMessageIs('The provided OAuthAuthenticator does not contain a refresh token.');
$connector->refreshAccessToken($authenticator);
}
@@ -523,7 +523,7 @@ public function testAbsoluteRefreshEndpointRequiresOverridePermission(): void
$connector = new OAuth2Connector(['refreshEndpoint' => 'https://oauth.example.net/refresh']);
$this->expectException(PendingRequestException::class);
- $this->expectExceptionMessage('The request endpoint cannot replace the connector base URL.');
+ $this->expectExceptionMessageIsOrContains('The request endpoint cannot replace the connector base URL.');
try {
$connector->refreshAccessToken('refresh');
@@ -665,7 +665,7 @@ public function testIfYouAttemptToUseTheAuthorizationCodeFlowWithoutAClientIdItW
Saloon::fake($mockClient);
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Client ID is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Client ID is empty or has not been provided.');
$connector->getAccessToken('code');
}
@@ -680,7 +680,7 @@ public function testIfYouAttemptToUseTheAuthorizationCodeFlowWithoutASecretItWil
Saloon::fake($mockClient);
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Client Secret is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Client Secret is empty or has not been provided.');
$connector->getAccessToken('code');
}
@@ -695,7 +695,7 @@ public function testIfYouAttemptToUseTheAuthorizationCodeFlowWithoutARedirectUri
Saloon::fake($mockClient);
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Redirect URI is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Redirect URI is empty or has not been provided.');
$connector->getAccessToken('code');
}
diff --git a/tests/Saloon/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php b/tests/Saloon/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php
index 8ebb695124..c2982f9625 100644
--- a/tests/Saloon/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php
+++ b/tests/Saloon/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php
@@ -229,7 +229,7 @@ public function testIfYouAttemptToUseTheClientCredentialsFlowWithoutAClientIdItW
Saloon::fake($mockClient);
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Client ID is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Client ID is empty or has not been provided.');
$connector->getAccessToken();
}
@@ -244,7 +244,7 @@ public function testIfYouAttemptToUseTheClientCredentialsFlowWithoutASecretItWil
Saloon::fake($mockClient);
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Client Secret is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Client Secret is empty or has not been provided.');
$connector->getAccessToken();
}
diff --git a/tests/Saloon/Feature/RetryConnectorTest.php b/tests/Saloon/Feature/RetryConnectorTest.php
index af879065e7..9ba2a99fcd 100644
--- a/tests/Saloon/Feature/RetryConnectorTest.php
+++ b/tests/Saloon/Feature/RetryConnectorTest.php
@@ -150,7 +150,7 @@ public function testYouCanCustomiseIfTheMethodShouldRetry(): void
});
$this->expectException(InternalServerErrorException::class);
- $this->expectExceptionMessage("HTTP request returned status code 500:\n{\"name\":\"Gareth\"}\n");
+ $this->expectExceptionMessageIs("HTTP request returned status code 500:\n{\"name\":\"Gareth\"}\n");
$connector->send(new UserRequest, $mockClient);
}
@@ -164,7 +164,7 @@ public function testIfTheHandleRetryReturnsFalseItWillThrowAnException(): void
]);
$this->expectException(InternalServerErrorException::class);
- $this->expectExceptionMessage("HTTP request returned status code 500:\n{\"name\":\"Sam\"}\n");
+ $this->expectExceptionMessageIs("HTTP request returned status code 500:\n{\"name\":\"Sam\"}\n");
(new RetryConnector(3, when: fn (): bool => false))->send(new UserRequest, $mockClient);
}
diff --git a/tests/Saloon/Feature/RetryRequestTest.php b/tests/Saloon/Feature/RetryRequestTest.php
index bb9dcd4f35..54e1cf78ce 100644
--- a/tests/Saloon/Feature/RetryRequestTest.php
+++ b/tests/Saloon/Feature/RetryRequestTest.php
@@ -205,7 +205,7 @@ public function testYouCanCustomiseIfTheMethodShouldRetry(): void
]);
$this->expectException(InternalServerErrorException::class);
- $this->expectExceptionMessage("HTTP request returned status code 500:\n{\"name\":\"Gareth\"}\n");
+ $this->expectExceptionMessageIs("HTTP request returned status code 500:\n{\"name\":\"Gareth\"}\n");
(new TestConnector)->send(new RetryUserRequest(3, when: function (RequestException $exception): bool {
return $exception->response()->json() !== ['name' => 'Gareth'];
@@ -221,7 +221,7 @@ public function testIfTheHandleRetryReturnsFalseItWillThrowAnException(): void
]);
$this->expectException(InternalServerErrorException::class);
- $this->expectExceptionMessage("HTTP request returned status code 500:\n{\"name\":\"Sam\"}\n");
+ $this->expectExceptionMessageIs("HTTP request returned status code 500:\n{\"name\":\"Sam\"}\n");
(new TestConnector)->send(new RetryUserRequest(3, when: fn (): bool => false), $mockClient);
}
@@ -344,7 +344,7 @@ public function testAnExplicitRetryReplacesTheRequestsDefaultRetryPolicy(): void
public function testInvalidAttemptsOrIntervalsAreRejected(int $times, int $sleepMilliseconds, string $message): void
{
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage($message);
+ $this->expectExceptionMessageIs($message);
(new UserRequest)->retry($times, $sleepMilliseconds);
}
diff --git a/tests/Saloon/Hypervel/Unit/MockClientAssertionsTest.php b/tests/Saloon/Hypervel/Unit/MockClientAssertionsTest.php
index 2fe82b2b87..fe6b8625d9 100644
--- a/tests/Saloon/Hypervel/Unit/MockClientAssertionsTest.php
+++ b/tests/Saloon/Hypervel/Unit/MockClientAssertionsTest.php
@@ -151,7 +151,7 @@ public function testYouCanMockExceptions(): void
$this->assertSame(['name' => 'Sam'], $okResponse->json());
$this->expectException(Exception::class);
- $this->expectExceptionMessage('Unable to connect!');
+ $this->expectExceptionMessageIs('Unable to connect!');
TestConnector::make()->send(new UserRequest);
}
@@ -163,7 +163,7 @@ public function testYouCanMockNormalExceptions(): void
]);
$this->expectException(Exception::class);
- $this->expectExceptionMessage('Custom Exception!');
+ $this->expectExceptionMessageIs('Custom Exception!');
TestConnector::make()->send(new UserRequest);
}
diff --git a/tests/Saloon/Pagination/Feature/AsyncPaginationTest.php b/tests/Saloon/Pagination/Feature/AsyncPaginationTest.php
index a5596a5322..33a7e69d2f 100644
--- a/tests/Saloon/Pagination/Feature/AsyncPaginationTest.php
+++ b/tests/Saloon/Pagination/Feature/AsyncPaginationTest.php
@@ -91,7 +91,7 @@ public function testIfYouDontImplementTheGetTotalPagesMethodOnAPaginatorItWillTh
$paginator = $connector->paginate($request);
$this->expectException(LogicException::class);
- $this->expectExceptionMessage('Implement [getTotalPages] to use pooled pagination.');
+ $this->expectExceptionMessageIs('Implement [getTotalPages] to use pooled pagination.');
$paginator->pool();
}
diff --git a/tests/Saloon/Pagination/Feature/PaginationTest.php b/tests/Saloon/Pagination/Feature/PaginationTest.php
index d776ad6555..8e2efa0286 100644
--- a/tests/Saloon/Pagination/Feature/PaginationTest.php
+++ b/tests/Saloon/Pagination/Feature/PaginationTest.php
@@ -160,7 +160,7 @@ public function testThePaginatorWillThrowAnExceptionIfYouUseARequestThatIsNotPag
$request = new UserRequest;
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('The request must implement [' . Paginatable::class . '] to be used with a paginator.');
+ $this->expectExceptionMessageIs('The request must implement [' . Paginatable::class . '] to be used with a paginator.');
$connector->paginate($request);
}
diff --git a/tests/Saloon/Unit/AuthenticatorTest.php b/tests/Saloon/Unit/AuthenticatorTest.php
index 9af914b61e..1903aad3cb 100644
--- a/tests/Saloon/Unit/AuthenticatorTest.php
+++ b/tests/Saloon/Unit/AuthenticatorTest.php
@@ -79,7 +79,7 @@ public function testTheRequiresAuthTraitWillThrowAnExceptionIfAnAuthenticatorIsN
]);
$this->expectException(MissingAuthenticatorException::class);
- $this->expectExceptionMessage('The "Hypervel\Tests\Saloon\Fixtures\Requests\RequiresAuthRequest" request requires authentication.');
+ $this->expectExceptionMessageIs('The "Hypervel\Tests\Saloon\Fixtures\Requests\RequiresAuthRequest" request requires authentication.');
$request = new RequiresAuthRequest;
diff --git a/tests/Saloon/Unit/Body/ArrayBodyRepositoryTest.php b/tests/Saloon/Unit/Body/ArrayBodyRepositoryTest.php
index 6f258d3730..97b1c37767 100644
--- a/tests/Saloon/Unit/Body/ArrayBodyRepositoryTest.php
+++ b/tests/Saloon/Unit/Body/ArrayBodyRepositoryTest.php
@@ -45,7 +45,7 @@ public function testYouCanSetIt(): void
public function testItWillThrowAnExceptionIfYouSetANonArray(): void
{
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('The body value must be an array.');
+ $this->expectExceptionMessageIs('The body value must be an array.');
$body = new FormBodyRepository;
$body->set('Sam');
diff --git a/tests/Saloon/Unit/Body/MultipartBodyRepositoryTest.php b/tests/Saloon/Unit/Body/MultipartBodyRepositoryTest.php
index 816d09bef6..02652de0d7 100644
--- a/tests/Saloon/Unit/Body/MultipartBodyRepositoryTest.php
+++ b/tests/Saloon/Unit/Body/MultipartBodyRepositoryTest.php
@@ -35,7 +35,7 @@ public function testTheStoreCanHaveAnArrayOfMultipartValuesProvided(): void
public function testTheStoreWillThrowAnExceptionIfSetValueIsNotAnArray(): void
{
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('The multipart body value must be an array.');
+ $this->expectExceptionMessageIs('The multipart body value must be an array.');
$body = new MultipartBodyRepository;
$body->set('123');
@@ -44,7 +44,7 @@ public function testTheStoreWillThrowAnExceptionIfSetValueIsNotAnArray(): void
public function testTheStoreWillThrowAnExceptionIfTheArrayDoesNotContainMultipartValues(): void
{
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('The value array must only contain Hypervel\Saloon\Data\MultipartValue objects.');
+ $this->expectExceptionMessageIs('The value array must only contain Hypervel\Saloon\Data\MultipartValue objects.');
new MultipartBodyRepository([
'name' => 'Sam',
@@ -173,7 +173,7 @@ public function testItWillThrowAnExceptionIfTheMergedItemsAreNotMultipartValueOb
$body = new MultipartBodyRepository;
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('The value array must only contain Hypervel\Saloon\Data\MultipartValue objects.');
+ $this->expectExceptionMessageIs('The value array must only contain Hypervel\Saloon\Data\MultipartValue objects.');
$body->merge([new MultipartValue('sidekick', 'Gareth')], ['superhero' => 'Black Widow']);
}
diff --git a/tests/Saloon/Unit/ConfigTest.php b/tests/Saloon/Unit/ConfigTest.php
index 81271e53da..2e5bb541d8 100644
--- a/tests/Saloon/Unit/ConfigTest.php
+++ b/tests/Saloon/Unit/ConfigTest.php
@@ -83,7 +83,7 @@ public function testYouCanPreventStrayApiRequests(): void
Http::preventStrayRequests();
$this->expectException(StrayRequestException::class);
- $this->expectExceptionMessage('Attempted request to [https://tests.saloon.dev/api/user] without a matching fake.');
+ $this->expectExceptionMessageIs('Attempted request to [https://tests.saloon.dev/api/user] without a matching fake.');
TestConnector::make()->send(new UserRequest);
}
diff --git a/tests/Saloon/Unit/MiddlewarePipelineTest.php b/tests/Saloon/Unit/MiddlewarePipelineTest.php
index 4a38b48d45..998ad40319 100644
--- a/tests/Saloon/Unit/MiddlewarePipelineTest.php
+++ b/tests/Saloon/Unit/MiddlewarePipelineTest.php
@@ -84,7 +84,7 @@ public function testRequestMiddlewareNamedPipeMustBeUnique(): void
);
$this->expectException(DuplicatePipeNameException::class);
- $this->expectExceptionMessage('The "YeeHawPipe" pipe already exists on the pipeline');
+ $this->expectExceptionMessageIs('The "YeeHawPipe" pipe already exists on the pipeline.');
$pipeline->onRequest(
callable: function (PendingRequest $request): void {
@@ -208,7 +208,7 @@ public function testResponseMiddlewareNamedPipeMustBeUnique(): void
}, 'ResponsePipe');
$this->expectException(DuplicatePipeNameException::class);
- $this->expectExceptionMessage('The "ResponsePipe" pipe already exists on the pipeline');
+ $this->expectExceptionMessageIs('The "ResponsePipe" pipe already exists on the pipeline.');
$pipeline->onResponse(function (): void {
}, 'ResponsePipe');
@@ -363,7 +363,7 @@ public function testFatalMiddlewareNamedPipeMustBeUnique(): void
);
$this->expectException(DuplicatePipeNameException::class);
- $this->expectExceptionMessage('The "YeeHawPipe" pipe already exists on the pipeline');
+ $this->expectExceptionMessageIs('The "YeeHawPipe" pipe already exists on the pipeline.');
$pipeline->onFatalException(
callable: function (): void {
@@ -476,7 +476,7 @@ public function testWhenMergingAMiddlewarePipelineTogetherIfTwoPipelinesExistWit
$pipelineB->onRequest(fn (): null => null, 'howdy');
$this->expectException(DuplicatePipeNameException::class);
- $this->expectExceptionMessage('The "howdy" pipe already exists on the pipeline');
+ $this->expectExceptionMessageIs('The "howdy" pipe already exists on the pipeline.');
$pipelineA->merge($pipelineB);
}
diff --git a/tests/Saloon/Unit/MockClientTest.php b/tests/Saloon/Unit/MockClientTest.php
index 720d88c965..d2964bd71a 100644
--- a/tests/Saloon/Unit/MockClientTest.php
+++ b/tests/Saloon/Unit/MockClientTest.php
@@ -161,7 +161,7 @@ public function testSaloonThrowsAnExceptionIfItCantWorkOutTheUrlResponse(): void
$this->assertSame($responseB, $mockClient->match($connectorA->createPendingRequest($requestB)));
$this->expectException(NoMockResponseFoundException::class);
- $this->expectExceptionMessage('Saloon was unable to guess a mock response for your request [https://google.com/user], consider using a wildcard url mock or a connector mock.');
+ $this->expectExceptionMessageIs('Saloon was unable to guess a mock response for your request [https://google.com/user], consider using a wildcard url mock or a connector mock.');
$mockClient->match($connectorB->createPendingRequest($requestC));
}
@@ -336,7 +336,7 @@ public function testYouCanMockExceptionsWithAClosure(): void
$this->assertSame(['name' => 'Sam'], $okResponse->json());
$this->expectException(TestResponseException::class);
- $this->expectExceptionMessage('Unable to connect!');
+ $this->expectExceptionMessageIs('Unable to connect!');
(new TestConnector)->send(new UserRequest, $mockClient);
}
@@ -348,7 +348,7 @@ public function testYouCanMockNormalExceptions(): void
]);
$this->expectException(Exception::class);
- $this->expectExceptionMessage('Custom Exception!');
+ $this->expectExceptionMessageIs('Custom Exception!');
(new TestConnector)->send(new UserRequest, $mockClient);
}
diff --git a/tests/Saloon/Unit/MockConfigTest.php b/tests/Saloon/Unit/MockConfigTest.php
index a9170bcef5..15f5c144b8 100644
--- a/tests/Saloon/Unit/MockConfigTest.php
+++ b/tests/Saloon/Unit/MockConfigTest.php
@@ -76,7 +76,7 @@ public function testYouCanThrowAnExceptionIfTheFixtureDoesNotExist(): void
]);
$this->expectException(FixtureMissingException::class);
- $this->expectExceptionMessage('example.json" could not be found in storage.');
+ $this->expectExceptionMessageIsOrContains('example.json" could not be found in storage.');
(new TestConnector)->send(new UserRequest, $mockClient);
}
diff --git a/tests/Saloon/Unit/MultipartValueTest.php b/tests/Saloon/Unit/MultipartValueTest.php
index 838de8cd91..d82247c4f8 100644
--- a/tests/Saloon/Unit/MultipartValueTest.php
+++ b/tests/Saloon/Unit/MultipartValueTest.php
@@ -51,7 +51,7 @@ public static function validValues(): iterable
public function testItWillThrowAnExceptionOnInvalidValues(mixed $value): void
{
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('The value property must be either a Psr\Http\Message\StreamInterface, resource, string, finite number, boolean, null, or array.');
+ $this->expectExceptionMessageIs('The value property must be either a Psr\Http\Message\StreamInterface, resource, string, finite number, boolean, null, or array.');
new MultipartValue('test', $value);
}
@@ -72,7 +72,7 @@ public static function invalidValues(): iterable
public function testAnArrayValueCannotHaveAFilenameOrHeaders(?string $filename, array $headers): void
{
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('An array value cannot have a filename or headers.');
+ $this->expectExceptionMessageIs('An array value cannot have a filename or headers.');
new MultipartValue('roles', ['admin'], $filename, $headers);
}
diff --git a/tests/Saloon/Unit/Oauth2/AuthCodeFlowConnectorTest.php b/tests/Saloon/Unit/Oauth2/AuthCodeFlowConnectorTest.php
index 3eb00d693f..1e210bfb82 100644
--- a/tests/Saloon/Unit/Oauth2/AuthCodeFlowConnectorTest.php
+++ b/tests/Saloon/Unit/Oauth2/AuthCodeFlowConnectorTest.php
@@ -45,7 +45,7 @@ public function testTheOauthConfigIsValidatedWhenGeneratingAnAuthorizationUrl():
$connector = new OAuth2Connector(['clientId' => '']);
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Client ID is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Client ID is empty or has not been provided.');
$connector->authorizationUrl();
}
@@ -55,7 +55,7 @@ public function testTheOauthConfigIsValidatedWhenCreatingAccessTokens(): void
$connector = new OAuth2Connector(['clientId' => '']);
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Client ID is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Client ID is empty or has not been provided.');
$connector->getAccessToken('code');
}
@@ -65,7 +65,7 @@ public function testTheOauthConfigIsValidatedWhenRefreshingAccessTokens(): void
$connector = new OAuth2Connector(['clientId' => '']);
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Client ID is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Client ID is empty or has not been provided.');
$connector->refreshAccessToken('');
}
diff --git a/tests/Saloon/Unit/Oauth2/OAuthConfigTest.php b/tests/Saloon/Unit/Oauth2/OAuthConfigTest.php
index 5399318474..6e7edfbffa 100644
--- a/tests/Saloon/Unit/Oauth2/OAuthConfigTest.php
+++ b/tests/Saloon/Unit/Oauth2/OAuthConfigTest.php
@@ -58,7 +58,7 @@ public function testItWillThrowAnExceptionIfYouDoNotSpecifyTheClientId(): void
$config = new OAuthConfig('', 'client-secret', 'https://my-app.saloon.dev/auth/callback');
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Client ID is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Client ID is empty or has not been provided.');
$config->validate();
}
@@ -68,7 +68,7 @@ public function testItWillThrowAnExceptionIfYouDoNotSpecifyTheClientSecret(): vo
$config = new OAuthConfig('client-id', '', 'https://my-app.saloon.dev/auth/callback');
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Client Secret is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Client Secret is empty or has not been provided.');
$config->validate();
}
@@ -78,7 +78,7 @@ public function testItWillThrowAnExceptionIfYouDoNotSpecifyTheRedirectUri(): voi
$config = new OAuthConfig('client-id', 'client-secret');
$this->expectException(OAuthConfigValidationException::class);
- $this->expectExceptionMessage('The Redirect URI is empty or has not been provided.');
+ $this->expectExceptionMessageIs('The Redirect URI is empty or has not been provided.');
$config->validate();
}
diff --git a/tests/Saloon/Unit/PendingRequestTest.php b/tests/Saloon/Unit/PendingRequestTest.php
index e8fcfe45c8..2ac2d16022 100644
--- a/tests/Saloon/Unit/PendingRequestTest.php
+++ b/tests/Saloon/Unit/PendingRequestTest.php
@@ -79,7 +79,7 @@ public function testThePendingRequestValidatesProperlyFormedHeaders(): void
]);
$this->expectException(InvalidHeaderException::class);
- $this->expectExceptionMessage('One or more of the headers are invalid. Make sure to use the header name as the key. For example: [\'Content-Type\' => \'application/json\'].');
+ $this->expectExceptionMessageIs('One or more of the headers are invalid. Make sure to use the header name as the key. For example: [\'Content-Type\' => \'application/json\'].');
(new TestConnector)->createPendingRequest($request);
}
@@ -123,7 +123,7 @@ public function testHeaderValuesMustBeScalarNullOrStringable(): void
);
$this->expectException(InvalidHeaderException::class);
- $this->expectExceptionMessage('HTTP header values must be scalar, null, Hypervel Stringable, or arrays of those values.');
+ $this->expectExceptionMessageIs('HTTP header values must be scalar, null, Hypervel Stringable, or arrays of those values.');
$pendingRequest->toPsrRequest();
}
diff --git a/tests/Saloon/Unit/RequestTest.php b/tests/Saloon/Unit/RequestTest.php
index 727883a969..8e2ea35f06 100644
--- a/tests/Saloon/Unit/RequestTest.php
+++ b/tests/Saloon/Unit/RequestTest.php
@@ -172,7 +172,7 @@ public function testARelativeEndpointCannotBeJoinedToAnEmptyBaseUrl(): void
$pendingRequest = (new CustomBaseUrlConnector)->createPendingRequest($request);
$this->expectException(PendingRequestException::class);
- $this->expectExceptionMessage('A request without a connector base URL must use an absolute HTTP or HTTPS endpoint.');
+ $this->expectExceptionMessageIs('A request without a connector base URL must use an absolute HTTP or HTTPS endpoint.');
$pendingRequest->uri();
}
@@ -183,7 +183,7 @@ public function testItThrowsAnExceptionIfYouForgetToAddAMethod(): void
$request = new MissingMethodRequest;
$this->expectException(LogicException::class);
- $this->expectExceptionMessage('Your request is missing an HTTP method. Add a method property such as [protected Method $method = Method::GET].');
+ $this->expectExceptionMessageIs('Your request is missing an HTTP method. Add a method property such as [protected Method $method = Method::GET].');
$connector->send($request);
}
@@ -208,7 +208,7 @@ public function testContainerResolutionPassesRequestParameters(): void
public function testWithCookieRejectsInvalidCookies(array $cookie, string $message): void
{
$this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage($message);
+ $this->expectExceptionMessageIs($message);
(new UserRequest)->withCookie(new SetCookie($cookie));
}
diff --git a/tests/Saloon/Unit/URLHelperTest.php b/tests/Saloon/Unit/URLHelperTest.php
index 2438e29a1b..7b99a6bc48 100644
--- a/tests/Saloon/Unit/URLHelperTest.php
+++ b/tests/Saloon/Unit/URLHelperTest.php
@@ -58,7 +58,7 @@ public function testJoinThrowsWhenEndpointIsAnAbsoluteUrlToPreventSsrfAndCredent
$attackerUrl = 'https://attacker.example.com/steal';
$this->expectException(PendingRequestException::class);
- $this->expectExceptionMessage('The request endpoint cannot replace the connector base URL.');
+ $this->expectExceptionMessageIsOrContains('The request endpoint cannot replace the connector base URL.');
UrlResolver::resolve($trustedBaseUrl, $attackerUrl, false);
}
@@ -85,7 +85,7 @@ public function testCreatingAPendingRequestWithARequestThatReturnsAbsoluteUrlFro
$request = new AbsoluteEndpointRequest('https://attacker.example.com/callback');
$this->expectException(PendingRequestException::class);
- $this->expectExceptionMessage('The request endpoint cannot replace the connector base URL.');
+ $this->expectExceptionMessageIsOrContains('The request endpoint cannot replace the connector base URL.');
// The URL is resolved when it is first read rather than when the pending request is created.
$connector->createPendingRequest($request)->uri();
@@ -204,7 +204,7 @@ public function testBaseAndEndpointQueriesAreRetainedBeforeRepositoryOverrides()
public function testEmptyBaseUrlRequiresAnAbsoluteHttpEndpoint(): void
{
$this->expectException(PendingRequestException::class);
- $this->expectExceptionMessage('A request without a connector base URL must use an absolute HTTP or HTTPS endpoint.');
+ $this->expectExceptionMessageIs('A request without a connector base URL must use an absolute HTTP or HTTPS endpoint.');
UrlResolver::resolve('', 'google.com/search', true);
}
@@ -213,7 +213,7 @@ public function testEmptyBaseUrlRequiresAnAbsoluteHttpEndpoint(): void
public function testAlternateSchemesAreRejected(string $baseUrl): void
{
$this->expectException(PendingRequestException::class);
- $this->expectExceptionMessage('The request endpoint must be an absolute HTTP or HTTPS URI.');
+ $this->expectExceptionMessageIs('The request endpoint must be an absolute HTTP or HTTPS URI.');
UrlResolver::resolve($baseUrl, 'file:///etc/passwd', true);
}
From 77f6ec42115bcba1d467f4b4529ac1717a7a5ad2 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Wed, 7 Oct 2026 06:20:15 +0000
Subject: [PATCH 22/26] Record that Laravel Idea metadata is not shipped
Upstream Saloon's Laravel plugin, laravel-data and laravel-permission each
ship a root ide.json with code-generation templates for the Laravel Idea
PhpStorm plugin. Hypervel does not ship this metadata for any of them.
The Saloon README lists it with the other plugin features that are not
included and points to the saloon:* generator commands instead. The Data
and Permission sync notes record it, since neither README covers it.
---
docs/upstream-sync/sync.yaml | 4 ++--
src/saloon/README.md | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/upstream-sync/sync.yaml b/docs/upstream-sync/sync.yaml
index 749c225473..e82628b512 100644
--- a/docs/upstream-sync/sync.yaml
+++ b/docs/upstream-sync/sync.yaml
@@ -156,14 +156,14 @@ spatie/laravel-data:
checked_through: ce296f22861dc1237ce468754cc7f46d3ac34ad5
last_reviewed_pr: null
sync_date: '2026-10-03'
- notes: Hypervel replaces upstream's data pipes and resolvers with a fixed engine. The pipes and DataFromSomethingResolver map to Support/Creation/DataCreator and its per-operation ConstructionState; the validation resolvers and built-in rule inferrers map to Support/Validation/DataValidationCompiler and DataValidator; TransformedDataResolver and VisibleDataFieldsResolver map to Support/Transformation/DataTransformer and PartialTree. DataCreator's direct construction from DataClass creation recipes and DataTransformer's bulk copy are deliberate fast paths, so apply upstream behavior changes to them as well as to the general paths, and compare tests/Benchmarks/Data/benchmark.php results before and after. Upstream tests for those replaced classes live in the matching upstream feature tests or in the owning engine's tests under tests/Data/Support.
+ notes: Hypervel replaces upstream's data pipes and resolvers with a fixed engine. The pipes and DataFromSomethingResolver map to Support/Creation/DataCreator and its per-operation ConstructionState; the validation resolvers and built-in rule inferrers map to Support/Validation/DataValidationCompiler and DataValidator; TransformedDataResolver and VisibleDataFieldsResolver map to Support/Transformation/DataTransformer and PartialTree. DataCreator's direct construction from DataClass creation recipes and DataTransformer's bulk copy are deliberate fast paths, so apply upstream behavior changes to them as well as to the general paths, and compare tests/Benchmarks/Data/benchmark.php results before and after. Upstream tests for those replaced classes live in the matching upstream feature tests or in the owning engine's tests under tests/Data/Support. Upstream's ide.json code-generation metadata for the Laravel Idea PhpStorm plugin is not ported.
spatie/laravel-permission:
branch: main
checked_through: 6615eefac655efcd652fe394a20cbdf4f72c609f
last_reviewed_pr: null
sync_date: '2026-10-05'
- notes: Upstream Pest files map to PHPUnit classes at the same paths under tests/Permission, with each it()/test() description as the method name. Upstream's permission.testing migration flag, which adds the roles team column while teams are off so cases can enable teams mid-test, is not ported; those cases enable teams before migrating through the DefineEnvironment attribute's usesTeams method. The CACHE_DRIVER cache-driver test runs map to CACHE_STORE. Passport::actingAsClient() maps to TestCase::actingAsClient() with the PassportGuard fixture because Hypervel has no Passport package. Upstream's single cached permission collection maps to PermissionRegistrar's catalog payload (getSerializedPermissionsForCache() stores role keys per permission; permissionCatalog() and modelClassCatalog() hydrate it) plus the per-model assignment caches (rememberModel*()), which are filled through Cache\ModelCacheCoordinator and invalidated after commit; apply upstream cache or loading changes to both. Upstream relation definitions map to the Role and Permission relation methods built through BuildsPermissionRelations, whose Partitioned* relations add partition and team constraints and loaded-relation tracking. Upstream's detach-then-attach syncs map to HasRoles::syncRoles() and HasPermissions::synchronizePermissionAssignments(), which read the current pivots and write only the differences, keeping each permission's is_denied effect. Upstream docs map to sections of src/docs/permission.md; the example app, PhpStorm, UI options, schema diagram, upgrade and project pages are not ported.
+ notes: Upstream Pest files map to PHPUnit classes at the same paths under tests/Permission, with each it()/test() description as the method name. Upstream's permission.testing migration flag, which adds the roles team column while teams are off so cases can enable teams mid-test, is not ported; those cases enable teams before migrating through the DefineEnvironment attribute's usesTeams method. The CACHE_DRIVER cache-driver test runs map to CACHE_STORE. Passport::actingAsClient() maps to TestCase::actingAsClient() with the PassportGuard fixture because Hypervel has no Passport package. Upstream's single cached permission collection maps to PermissionRegistrar's catalog payload (getSerializedPermissionsForCache() stores role keys per permission; permissionCatalog() and modelClassCatalog() hydrate it) plus the per-model assignment caches (rememberModel*()), which are filled through Cache\ModelCacheCoordinator and invalidated after commit; apply upstream cache or loading changes to both. Upstream relation definitions map to the Role and Permission relation methods built through BuildsPermissionRelations, whose Partitioned* relations add partition and team constraints and loaded-relation tracking. Upstream's detach-then-attach syncs map to HasRoles::syncRoles() and HasPermissions::synchronizePermissionAssignments(), which read the current pivots and write only the differences, keeping each permission's is_denied effect. Upstream docs map to sections of src/docs/permission.md; the example app, PhpStorm, UI options, schema diagram, upgrade and project pages are not ported. Upstream's ide.json code-generation metadata for the Laravel Idea PhpStorm plugin is not ported either.
aimeos/laravel-nestedset:
branch: master
diff --git a/src/saloon/README.md b/src/saloon/README.md
index f36f51d8f9..678328265b 100644
--- a/src/saloon/README.md
+++ b/src/saloon/README.md
@@ -8,7 +8,7 @@ Requests and pending requests use fluent methods in the style of Hypervel's HTTP
Connectors are read-only. Their headers, query parameters, options, body, authenticator and delay come from their `default*` methods and constructor values, because a connector may be shared by concurrent requests. Apply per-operation values to the request, or change connector defaults on the pending request in a hook or middleware. Connectors have no `middleware()` or debugging methods; register middleware and debuggers on the pending request from `boot()` or a plugin. For the same reason, requests and connectors allow absolute endpoints by overriding `allowsBaseUrlOverride()`; upstream's public `$allowBaseUrlOverride` property has no effect. `HasApiVersion` has no `setApiVersion()`: assign `$apiVersion` in the constructor or override `getApiVersion()`.
-There is no process-global `Config` class and no pluggable sender. Global middleware is `Saloon::middleware()`. Requests are sent through Hypervel's HTTP client on a named connection, `saloon.connection.name` or the connector's `resolveHttpConnection()`, so `sender()`, `defaultSender()`, sender resolvers, handler stacks and the sender's factory collection are not available; use the connection's options, `Http::globalMiddleware()`, or Saloon's PSR request hooks and middleware. Body repositories' `toStream()` and fake responses' `createPsrResponse()` take no PSR factories. Telescope's HTTP client watcher records Saloon requests with the `saloon` tag in place of the plugin's Telescope middleware, so fakes and cache hits are not recorded. The plugin's Pulse and Nightwatch middleware are not included, since Hypervel has neither package; OpenTelemetry's HTTP client instrumentation traces Saloon requests like other HTTP client requests. Prevent stray requests with `Http::preventStrayRequests()`, which throws the HTTP client's `StrayRequestException`, including for a request that would record a missing fixture, so allow the API's URLs with `Http::allowStrayRequests()` while recording. Fake sleeping with `Sleep::fake()`, and control the clock through the framework `Date` clock.
+There is no process-global `Config` class and no pluggable sender. Global middleware is `Saloon::middleware()`. Requests are sent through Hypervel's HTTP client on a named connection, `saloon.connection.name` or the connector's `resolveHttpConnection()`, so `sender()`, `defaultSender()`, sender resolvers, handler stacks and the sender's factory collection are not available; use the connection's options, `Http::globalMiddleware()`, or Saloon's PSR request hooks and middleware. Body repositories' `toStream()` and fake responses' `createPsrResponse()` take no PSR factories. Telescope's HTTP client watcher records Saloon requests with the `saloon` tag in place of the plugin's Telescope middleware, so fakes and cache hits are not recorded. The plugin's Pulse and Nightwatch middleware are not included, since Hypervel has neither package; OpenTelemetry's HTTP client instrumentation traces Saloon requests like other HTTP client requests. The plugin's `ide.json` code-generation metadata for the Laravel Idea PhpStorm plugin is not included; generate classes with the `saloon:*` commands (see [Generating Integrations](https://hypervel.org/docs/saloon#generating-integrations)). Prevent stray requests with `Http::preventStrayRequests()`, which throws the HTTP client's `StrayRequestException`, including for a request that would record a missing fixture, so allow the API's URLs with `Http::allowStrayRequests()` while recording. Fake sleeping with `Sleep::fake()`, and control the clock through the framework `Date` clock.
`createPendingRequest()` takes no mock client. Mock clients are chosen and matched when the request is sent, after request middleware has run and the URL is final, so middleware does not see a mock response and pending requests have no `hasMockClient()` or `getMockClient()`.
From 0f7eff50f2725df0df2fb90b82bf78efc34fa24d Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Wed, 7 Oct 2026 06:20:52 +0000
Subject: [PATCH 23/26] Record the Saloon sync checkpoints
Set the checkpoints for Saloon and its four plugins (Laravel, cache,
pagination and rate limiting), plus the shared Saloon docs:
- saloonphp/saloon v4 through 2f45e526f9d1 (#564)
- saloonphp/laravel-plugin v4 through 47d06ef8621a (#89)
- saloonphp/cache-plugin v3 through 5a036bae401d (#17)
- saloonphp/pagination-plugin v2 through a61822ca93c1 (#17)
- saloonphp/rate-limit-plugin v2 through aed5ff488e4d (#31)
- Sammyjo20/saloon-docs v3 through 8ea96847141f (#92)
---
docs/upstream-sync/sync.yaml | 36 ++++++++++++++++++------------------
1 file changed, 18 insertions(+), 18 deletions(-)
diff --git a/docs/upstream-sync/sync.yaml b/docs/upstream-sync/sync.yaml
index e82628b512..60fd2ca3ba 100644
--- a/docs/upstream-sync/sync.yaml
+++ b/docs/upstream-sync/sync.yaml
@@ -179,44 +179,44 @@ PHP-Open-Source-Saver/jwt-auth:
saloonphp/saloon:
branch: v4
- checked_through: null
- last_reviewed_pr: null
- sync_date: null
+ checked_through: 2f45e526f9d1d10a138f864492b074b046d2e52e
+ last_reviewed_pr: 564
+ sync_date: '2026-10-07'
notes: Core of the unified hypervel/saloon package, together with the four plugin entries and shared documentation below. Upstream's connector send path and senders map to SaloonManager and Http/Sender, which use Hypervel's HTTP client; pools use coroutines. The PendingRequest constructor lifecycle maps to SaloonManager::createPendingRequest (properties merge in the PendingRequest constructor and plugins boot after it), mock clients are selected and matched in SaloonManager::send after request middleware rather than stored on the pending request, and Helpers/URLHelper maps to Http/UrlResolver. Upstream's Config maps to the manager's global middleware, the saloon.connection settings and the framework Date, Sleep and Http stray-request APIs; Helpers/RequestExceptionHelper maps to Response::newRequestException. Upstream's retry loop and DelayMiddleware map to SaloonManager::send, and its retry properties and handleRetry() methods map to Data/RetryPolicy and the defaultRetryPolicy() hooks. Helpers/OAuth2/OAuthConfig maps to the immutable Data/OAuthConfig, and token-response parsing shared by the OAuth grant traits lives in Traits/OAuth2/ParsesOAuthTokenResponses. Assess upstream changes against these framework integrations and preserve supported SDK-generator extension points. Upstream tests and fixtures map to the same paths under tests/Saloon/{Unit,Feature,Fixtures}; cases that call upstream's live test API use the engine test server under tests/Integration/Saloon instead. src/saloon/README.md lists the deliberate public differences across all five entries, with their reasons and Hypervel equivalents; check them against current source before applying an upstream change they affect, and keep the README current.
saloonphp/laravel-plugin:
branch: v4
- checked_through: null
- last_reviewed_pr: null
- sync_date: null
+ checked_through: 47d06ef8621a5a25a2041e4a9004d96539db3f34
+ last_reviewed_pr: 89
+ sync_date: '2026-10-07'
notes: Part of the unified src/saloon package; reconcile alongside the core entry rather than creating a separate package. Provider, config, console, facade and event changes map to SaloonServiceProvider, config/saloon.php, Console, Facades and Events. Upstream's Http directory holds a MockClient subclass and observability middleware rather than a sender. Fakes and fixture recording map to SaloonManager and Http/Faking, SaloonManager dispatches the request events, and Telescope support comes from the framework HTTP client watcher through Http/Sender's Telescope tags. Tests map to tests/Saloon/Hypervel and use the core fixtures, which the plugin's fixtures copy. The plugin's Feature/PoolTest and Feature/RequestTest repeat core cases, so merge their new or changed cases into tests/Saloon/Feature/PoolTest and tests/Integration/Saloon/Feature/{PoolTest,RequestTest}, keeping plugin-specific setup such as Saloon::fake(), rather than adding separate copies.
saloonphp/cache-plugin:
branch: v3
- checked_through: null
- last_reviewed_pr: null
- sync_date: null
+ checked_through: 5a036bae401dab95b41c514dcd87b25bc4600b24
+ last_reviewed_pr: 17
+ sync_date: '2026-10-07'
notes: Part of the unified src/saloon package. Upstream's CacheMiddleware and CacheRecorderMiddleware map to SaloonManager::send(), which reads the cache before matching the mock client and writes after the response, and clearCache() maps to SaloonManager::clearCache(); keys come from Cache/CacheKey. Drivers map to framework cache stores selected by Cacheable::cacheStore(); assess driver changes against that integration instead of duplicating them. Connectors implement Cacheable and override cacheKey() and cacheableMethods() rather than using HasCaching. SaloonServiceProvider allows CachedResponse through the cache's serializable-class policy. Tests map to tests/Saloon/Cache/{Feature,Fixtures}, with the real-request case in tests/Integration/Saloon/Cache.
saloonphp/pagination-plugin:
branch: v2
- checked_through: null
- last_reviewed_pr: null
- sync_date: null
+ checked_through: a61822ca93c1207008941822b00df1d8740a4096
+ last_reviewed_pr: 17
+ sync_date: '2026-10-07'
notes: Part of the unified src/saloon package, under Pagination. Request-owned pagination, link paginators and the protected paginator state ($pageNumber, $startPage, $perPageLimit, $currentResponse, $currentPageLoaded, $pooling) are used by SDK generators; check affected consumers when adapting upstream changes. Upstream's async iteration maps to Paginator::pool(), so async test cases traverse through pool(). The infinite-loop check runs in Paginator::current(), not request middleware, because a middleware closure would keep the paginator alive through its own request. Upstream tests map to tests/Saloon/Pagination/Feature, with the public superhero API faked by Fixtures/SuperheroApi; Hypervel-only cases are in tests/Saloon/Pagination/PaginatorTest.
saloonphp/rate-limit-plugin:
branch: v2
- checked_through: null
- last_reviewed_pr: null
- sync_date: null
+ checked_through: aed5ff488e4dc2b7c1fc19ba40e16f139d658126
+ last_reviewed_pr: 31
+ sync_date: '2026-10-07'
notes: Part of the unified src/saloon package. Upstream rate-limit behavior maps to RateLimit and SaloonManager using Hypervel's rate-limiter policies and stores; assess changes against those framework services. Upstream's limiter middleware, too-many-attempts limit and store records become admission before transport, a cooldown recorded from the transport response, and Saloon::inspectRateLimit(). Feature/HasRateLimitsTest, Unit/{Destruct,Helper}Test and Laravel/Feature/JobMiddlewareTest map to tests/Saloon/RateLimit/{Feature,Unit,Hypervel/Feature}; ported cases fake the transport with Http::fake(), because Saloon fakes consume no capacity, and assert through inspectRateLimit() instead of store records. Unit/{Limit,Bucket,LimitStore}Test, Feature/Stores and Laravel/Feature/LaravelStoreTest test classes replaced by the rate limiter's Limit, CalendarWindow and LeakyBucket policies and its stores, so compare their changes with tests/RateLimiter (including its shared store contract) and tests/Integration/RateLimiter instead of porting them. RateLimitTest keeps the fake, cache and policy-group cases.
Sammyjo20/saloon-docs:
branch: v3
- checked_through: null
- last_reviewed_pr: null
- sync_date: null
+ checked_through: 8ea96847141fe60e24eb9dda2eb0e27a59c6bebd
+ last_reviewed_pr: 92
+ sync_date: '2026-10-07'
notes: Shared documentation for the unified src/saloon package and all four plugin entries above. Reconcile applicable core and plugin pages into the existing sections of the single src/docs/saloon.md rather than separate plugin guides, keeping Hypervel's additions and checking examples against current source, in Laravel-style prose matching the guide. The v3 branch includes v4 guidance. Installation commands, supported versions, upgrade guides, release notes, showcase, tutorials, the book and the third-party Lawman and SDK generator pages have no Hypervel equivalent; check them only for behavior the guide must still describe.
getsentry/sentry-laravel:
From 88d238adf4d3268016dabf97bbafc06dcf1a5fd6 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Wed, 7 Oct 2026 07:05:54 +0000
Subject: [PATCH 24/26] Fix the cluster calendar test and cover retried request
bodies
The Redis store test for calendar windows read the server clock with
time() without a node. PhpRedis's RedisCluster::time() needs a key or
address, so the test failed on the Redis Cluster job. It now reads the
clock of the node that holds the window's key. The store itself reads
TIME inside its Lua script and was not affected.
Retrying a request rewinds its body to where the first attempt started,
but nothing tested it. New retry tests send a resource body that starts
part way through, attach a resource file, and use a non-seekable body.
The first two fail if the rewind is removed. The third checks that a
non-seekable body throws BodyException with the failed response's
exception as its previous one, instead of resending an empty body.
Verified on a three-node Redis Cluster and a standalone Redis 8 server.
---
.../RateLimiter/Redis/RedisStoreTest.php | 8 ++-
tests/Saloon/Feature/RetryRequestTest.php | 69 +++++++++++++++++++
2 files changed, 75 insertions(+), 2 deletions(-)
diff --git a/tests/Integration/RateLimiter/Redis/RedisStoreTest.php b/tests/Integration/RateLimiter/Redis/RedisStoreTest.php
index d6e9e0eda8..32e8e29691 100644
--- a/tests/Integration/RateLimiter/Redis/RedisStoreTest.php
+++ b/tests/Integration/RateLimiter/Redis/RedisStoreTest.php
@@ -177,13 +177,17 @@ public function testCalendarWindowsFollowRedisTimeWhenThePhpClockIsInAnotherPeri
$first = $limiter->consume($policy);
$second = $limiter->consume($policy);
- $redisSeconds = (int) $this->redisClient()->time()[0];
+ $redis = $this->redisClient();
+
+ // RedisCluster::time() needs a node, so read the clock of the node that holds the window's key.
+ $redisTime = $this->usingRedisCluster() ? $redis->time($this->physicalKey($policy)) : $redis->time();
+ $redisSeconds = (int) $redisTime[0];
$this->assertTrue($first->allowed());
$this->assertSame(4, $first->remaining());
$this->assertSame(3, $second->remaining());
$this->assertEqualsWithDelta(3_600 - $redisSeconds % 3_600, $second->resetAfter(), 1);
- $this->assertLessThanOrEqual(3_600_000, $this->redisClient()->pttl($this->physicalKey($policy)));
+ $this->assertLessThanOrEqual(3_600_000, $redis->pttl($this->physicalKey($policy)));
}
/**
diff --git a/tests/Saloon/Feature/RetryRequestTest.php b/tests/Saloon/Feature/RetryRequestTest.php
index 54e1cf78ce..284a93a3b3 100644
--- a/tests/Saloon/Feature/RetryRequestTest.php
+++ b/tests/Saloon/Feature/RetryRequestTest.php
@@ -4,8 +4,14 @@
namespace Hypervel\Tests\Saloon\Feature;
+use ArrayObject;
use Exception;
+use GuzzleHttp\Promise\PromiseInterface;
+use GuzzleHttp\Psr7\NoSeekStream;
+use GuzzleHttp\Psr7\Utils;
use Hypervel\Contracts\Foundation\Application as ApplicationContract;
+use Hypervel\Http\Client\Request as HttpRequest;
+use Hypervel\Saloon\Exceptions\BodyException;
use Hypervel\Saloon\Exceptions\Request\FatalRequestException;
use Hypervel\Saloon\Exceptions\Request\RequestException;
use Hypervel\Saloon\Exceptions\Request\Statuses\InternalServerErrorException;
@@ -14,6 +20,7 @@
use Hypervel\Saloon\Http\Faking\MockResponse;
use Hypervel\Saloon\Http\PendingRequest;
use Hypervel\Saloon\SaloonServiceProvider;
+use Hypervel\Support\Facades\Http;
use Hypervel\Support\Sleep;
use Hypervel\Testbench\TestCase;
use Hypervel\Tests\Saloon\Fixtures\Connectors\TestConnector;
@@ -338,6 +345,50 @@ public function testAnExplicitRetryReplacesTheRequestsDefaultRetryPolicy(): void
$mockClient->assertSentCount(1);
}
+ public function testARetrySendsAResourceBodyAgainFromWhereTheFirstAttemptStarted(): void
+ {
+ $resource = fopen('php://memory', 'rw+');
+ fwrite($resource, 'skipped:payload');
+ fseek($resource, 8);
+ $sent = $this->fakeOneFailedUpload();
+
+ $response = (new TestConnector)->send((new UserRequest)->withBody($resource, 'text/plain')->retry(2));
+
+ $this->assertSame(200, $response->status());
+ $this->assertSame(['payload', 'payload'], $sent->getArrayCopy());
+ }
+
+ public function testARetrySendsAttachedResourcesAgain(): void
+ {
+ $resource = fopen('php://memory', 'rw+');
+ fwrite($resource, 'payload');
+ rewind($resource);
+ $sent = $this->fakeOneFailedUpload();
+
+ $response = (new TestConnector)->send((new UserRequest)->attach('file', $resource, 'file.txt')->retry(2));
+
+ $this->assertSame(200, $response->status());
+ $this->assertCount(2, $sent);
+ $this->assertStringContainsString('name="file"; filename="file.txt"', $sent[0]);
+ $this->assertStringContainsString("\r\n\r\npayload\r\n", $sent[0]);
+ $this->assertSame($sent[0], $sent[1]);
+ }
+
+ public function testANonSeekableBodyIsNotRetried(): void
+ {
+ $sent = $this->fakeOneFailedUpload();
+ $request = (new UserRequest)->withBody(new NoSeekStream(Utils::streamFor('payload')), 'text/plain')->retry(2);
+
+ try {
+ (new TestConnector)->send($request);
+ $this->fail('A non-seekable body was retried.');
+ } catch (BodyException $exception) {
+ $this->assertSame('The request body is not seekable and cannot be retried safely.', $exception->getMessage());
+ $this->assertInstanceOf(InternalServerErrorException::class, $exception->getPrevious());
+ $this->assertSame(['payload'], $sent->getArrayCopy());
+ }
+ }
+
// Upstream raises negative attempts and intervals to their minimum. Hypervel rejects them; a zero interval is
// valid and is the default.
#[DataProvider('invalidRetryPolicies')]
@@ -362,4 +413,22 @@ public static function invalidRetryPolicies(): array
'negative interval' => [2, -1, 'The retry delay must be a non-negative integer.'],
];
}
+
+ /**
+ * Fake a transport that reads each request body from its current position and fails the first attempt.
+ *
+ * @return ArrayObject
+ */
+ protected function fakeOneFailedUpload(): ArrayObject
+ {
+ $sent = new ArrayObject;
+
+ Http::fake(function (HttpRequest $request) use ($sent): PromiseInterface {
+ $sent[] = $request->toPsrRequest()->getBody()->getContents();
+
+ return Http::response(status: count($sent) === 1 ? 500 : 200);
+ });
+
+ return $sent;
+ }
}
From 9f088f9ef61646dd550add8be9a3d04a0eb806e0 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Wed, 7 Oct 2026 07:06:01 +0000
Subject: [PATCH 25/26] Resolve dot segments in Saloon's integrations path
Without a configured integrations namespace, the generator commands map
the integrations path beneath the app directory to a namespace. They
compared the raw configured path, so app_path('Http/../Integrations')
produced a namespace containing "..", and app_path('../src/Integrations')
passed the inside-the-app check and generated an invalid namespace
instead of asking for one.
The commands now canonicalize the configured path with Symfony's
Path::canonicalize() and use it for the namespace, the destination file
and the integration suggestions. The app path is canonicalized the same
way before the comparison. Saloon now requires symfony/filesystem
directly; the root package already did.
The generator tests cover an in-app path with dot segments and one that
leaves the app directory.
---
src/saloon/composer.json | 1 +
.../src/Console/Commands/MakeCommand.php | 26 ++++++++++++-------
.../Saloon/Console/GeneratorCommandsTest.php | 20 +++++++++++---
3 files changed, 35 insertions(+), 12 deletions(-)
diff --git a/src/saloon/composer.json b/src/saloon/composer.json
index f7cd319ba3..a54bc99f6c 100644
--- a/src/saloon/composer.json
+++ b/src/saloon/composer.json
@@ -58,6 +58,7 @@
"psr/http-message": "^2.0",
"symfony/console": "^8.1.2",
"symfony/dom-crawler": "^8.1",
+ "symfony/filesystem": "^8.1",
"symfony/finder": "^8.1",
"symfony/var-dumper": "^8.1"
},
diff --git a/src/saloon/src/Console/Commands/MakeCommand.php b/src/saloon/src/Console/Commands/MakeCommand.php
index 25e0833785..04371a4725 100644
--- a/src/saloon/src/Console/Commands/MakeCommand.php
+++ b/src/saloon/src/Console/Commands/MakeCommand.php
@@ -11,6 +11,7 @@
use Hypervel\Support\Str;
use LogicException;
use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Filesystem\Path;
use function Hypervel\Prompts\suggest;
@@ -95,6 +96,16 @@ protected function qualifyClass(string $name): string
: $namespace . '\\' . $name;
}
+ /**
+ * Get the configured integrations path.
+ *
+ * Dot segments are removed so the path can be compared with the application directory and mapped to a namespace.
+ */
+ protected function integrationsPath(): string
+ {
+ return Path::canonicalize($this->config->string('saloon.integrations_path'));
+ }
+
/**
* Get the configured integrations namespace.
*
@@ -107,18 +118,18 @@ protected function integrationNamespace(): string
if ($namespace === null) {
$rootNamespace = rtrim($this->rootNamespace(), '\\');
- $appPath = rtrim($this->hypervel->path(), '/\\');
- $integrationsPath = rtrim($this->config->string('saloon.integrations_path'), '/\\');
+ $appPath = Path::canonicalize($this->hypervel->path());
+ $integrationsPath = $this->integrationsPath();
if ($integrationsPath === $appPath) {
return $rootNamespace;
}
- if (! str_starts_with($integrationsPath, $appPath . DIRECTORY_SEPARATOR)) {
+ if (! str_starts_with($integrationsPath, $appPath . '/')) {
throw new LogicException('The [saloon.integrations_namespace] configuration value is required when the integrations path is outside the application directory.');
}
- return $rootNamespace . '\\' . str_replace(DIRECTORY_SEPARATOR, '\\', substr($integrationsPath, strlen($appPath) + 1));
+ return $rootNamespace . '\\' . str_replace('/', '\\', substr($integrationsPath, strlen($appPath) + 1));
}
if (! is_string($namespace) || $namespace === '') {
@@ -179,7 +190,7 @@ protected function promptForMissingArgumentsUsing(): array
*/
protected function getExistingIntegrations(string $search = ''): array
{
- $integrationsPath = $this->config->string('saloon.integrations_path');
+ $integrationsPath = $this->integrationsPath();
if (! $this->files->isDirectory($integrationsPath)) {
return [];
@@ -216,9 +227,6 @@ protected function getPath(string $name): string
$relativeName = Str::after($name, $this->integrationNamespace() . '\\');
}
- return rtrim($this->config->string('saloon.integrations_path'), '/\\')
- . DIRECTORY_SEPARATOR
- . str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $relativeName)
- . '.php';
+ return $this->integrationsPath() . '/' . str_replace('\\', '/', $relativeName) . '.php';
}
}
diff --git a/tests/Saloon/Console/GeneratorCommandsTest.php b/tests/Saloon/Console/GeneratorCommandsTest.php
index 573e4281ad..3862413766 100644
--- a/tests/Saloon/Console/GeneratorCommandsTest.php
+++ b/tests/Saloon/Console/GeneratorCommandsTest.php
@@ -211,13 +211,14 @@ public static function integrationsPathsInsideTheAppDirectory(): array
return [
'application directory' => ['', 'App\Stripe'],
'subdirectory' => ['Integrations', 'App\Integrations\Stripe'],
+ 'path with dot segments' => ['Http/../Integrations', 'App\Integrations\Stripe'],
];
}
- public function testAnIntegrationsPathOutsideTheAppDirectoryRequiresANamespace(): void
+ #[DataProvider('integrationsPathsOutsideTheAppDirectory')]
+ public function testAnIntegrationsPathOutsideTheAppDirectoryRequiresANamespace(string $relativePath): void
{
- // A sibling whose name starts with the app directory's name is still outside it.
- config()->set('saloon.integrations_path', base_path('app-other/Integrations'));
+ config()->set('saloon.integrations_path', base_path($relativePath));
$this->generatedDirectories[] = base_path('app-other');
try {
@@ -237,6 +238,19 @@ public function testAnIntegrationsPathOutsideTheAppDirectoryRequiresANamespace()
$this->assertDirectoryDoesNotExist(base_path('app-other'));
}
+ /**
+ * Get integrations paths, relative to the base path, that are outside the app directory.
+ *
+ * @return array
+ */
+ public static function integrationsPathsOutsideTheAppDirectory(): array
+ {
+ return [
+ 'sibling whose name starts with the app directory name' => ['app-other/Integrations'],
+ 'dot segments leaving the app directory' => ['app/../app-other/Integrations'],
+ ];
+ }
+
public function testCommandOptionsOverrideConfiguredPathAndNamespace(): void
{
config()->set('saloon.integrations_path', base_path('ignored/integrations'));
From 380709f5a296cbfdcf8ead29c2cd3d5bf24b3063 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Wed, 7 Oct 2026 07:06:01 +0000
Subject: [PATCH 26/26] Import request and connector classes in Saloon guide
examples
The SDK connector, resource and HasConnector examples used GetUser,
GetRepository and GitHubConnector without importing them. Copied as
shown, the classes resolve in the wrong namespace: the connector method
fails with a missing class, and GitHubConnector::class silently names a
class that does not exist until the request sends.
---
src/docs/saloon.md | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/src/docs/saloon.md b/src/docs/saloon.md
index 7844fef415..3e15a64411 100644
--- a/src/docs/saloon.md
+++ b/src/docs/saloon.md
@@ -255,6 +255,7 @@ public function boot(PendingRequest $pendingRequest): void
A connector may serve as an SDK's entry point by offering methods that send its requests:
```php
+use App\Http\Integrations\GitHub\Requests\GetUser;
use Hypervel\Saloon\Http\Response;
public function user(string $username): Response
@@ -266,6 +267,8 @@ public function user(string $username): Response
When an integration contains many endpoints, you may group related requests into resource classes. Extend `BaseResource` and use the `@extends` annotation to specify your connector type:
```php
+use App\Http\Integrations\GitHub\GitHubConnector;
+use App\Http\Integrations\GitHub\Requests\GetRepository;
use Hypervel\Saloon\Http\BaseResource;
use Hypervel\Saloon\Http\Response;
@@ -440,6 +443,7 @@ Standalone requests define their headers, query parameters, options, authenticat
A request that always uses the same connector may send itself with the `HasConnector` trait. Define the connector class in a `$connector` property:
```php
+use App\Http\Integrations\GitHub\GitHubConnector;
use Hypervel\Saloon\Traits\Request\HasConnector;
class GetUser extends Request