weijiajia / saloonphp-http-proxy-plugin
A robust HTTP proxy management plugin for Saloon PHP, allowing easy proxy rotation and failover.
Requires
- php: ^8.0
- saloonphp/saloon: ^3.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.17
- pestphp/pest: ^3.7
- phpstan/phpstan: ^1.10
This package is auto-updated.
Last update: 2025-03-23 05:12:34 UTC
README
A robust HTTP proxy management plugin for Saloon PHP, allowing you to easily use and rotate proxies in your API requests.
Table of Contents
Features
- π Stateless proxy management aligned with Saloon design principles
- π Automatic proxy fallback on connection failures
- π Customizable proxy rotation strategies (FIFO queue with round-robin support)
- π Support for authenticated proxies (username/password)
- 𧩠Simple integration with Saloon requests and connectors
- π¦ Dynamic proxy availability management
- π Smart handling of proxy failures with custom exceptions
Requirements
- PHP 8.0 or higher
- Saloon PHP v2.0 or higher
Installation
You can install the package via composer:
composer require weijiajia/saloonphp-http-proxy-plugin
Usage
Basic Setup
- Implement the
ProxyManagerInterface
in your connector or request class - Add the
HasProxy
trait to your Saloon connector or request class:
use Saloon\Http\Connector; use Weijiajia\SaloonphpHttpProxyPlugin\HasProxy; use Weijiajia\SaloonphpHttpProxyPlugin\Contracts\ProxyManagerInterface; class MyApiConnector extends Connector implements ProxyManagerInterface { use HasProxy; public function resolveBaseUrl(): string { return 'https://api.example.com'; } }
Adding Proxies
Add proxies to your connector or request object:
// Create a connector $connector = new MyApiConnector(); // Add proxies from URLs $connector->getProxyQueue()->enqueue('http://proxy1.example.com:8080'); $connector->getProxyQueue()->enqueue('http://user:pass@proxy2.example.com:8080'); // Or use Proxy objects use Weijiajia\SaloonphpHttpProxyPlugin\Proxy; $proxy = new Proxy( host: 'proxy3.example.com', port: 8080, url: 'http://proxy3.example.com:8080', type: 'http', username: 'user', password: 'pass' ); $connector->getProxyQueue()->enqueue($proxy); // Set a custom proxy queue use Weijiajia\SaloonphpHttpProxyPlugin\ProxySplQueue; $proxyQueue = new ProxySplQueue(roundRobinEnabled: true, proxies: ['http://proxy1.example.com:8080']); $connector->withProxyQueue($proxyQueue); // Use new method name
Proxy Rotation
Enable round-robin proxy rotation to cycle through available proxies:
// Enable round-robin mode directly on the proxy queue $connector->getProxyQueue()->setRoundRobinEnabled(true); // Or use the convenience method $connector->roundRobin(true);
Force Using Proxies
You can force your requests to only proceed if a proxy is available:
$connector->withForceProxy(true); // Default is true
Temporarily Disable Proxies
$connector->withProxyEnabled(false);
Proxy Availability Management
You can mark proxies as available or unavailable:
// Get all proxies in the queue $proxies = $connector->getProxyQueue()->getAllProxies(); // Mark a proxy as unavailable $proxies[0]->setAvailable(false); // Check if a proxy is available $isAvailable = $proxies[0]->isAvailable(); // returns false
Advanced Usage
Custom Proxy Queue
You can implement your own proxy queue by extending the ProxySplQueue
class:
use Weijiajia\SaloonphpHttpProxyPlugin\ProxySplQueue; use Weijiajia\SaloonphpHttpProxyPlugin\Contracts\ProxyInterface; class PrioritizedProxyQueue extends ProxySplQueue { // Your custom implementation with prioritization public function dequeue(): mixed { // Custom dequeue logic that considers priority // ... } // You can also implement additional methods public function addWithPriority(ProxyInterface $proxy, int $priority): void { // Custom logic to add proxy with priority } } $connector->withProxyQueue(new PrioritizedProxyQueue());
Request-Specific Proxies
The HasProxy
trait can be used on individual requests as well:
use Saloon\Http\Request; use Weijiajia\SaloonphpHttpProxyPlugin\HasProxy; use Weijiajia\SaloonphpHttpProxyPlugin\Contracts\ProxyManagerInterface; class MyApiRequest extends Request implements ProxyManagerInterface { use HasProxy; protected ?string $method = 'GET'; public function resolveEndpoint(): string { return '/api/endpoint'; } public function __construct() { // Add request-specific proxies $this->getProxyQueue()->enqueue('http://request-specific-proxy.example.com:8080'); } }
Error Handling
use Weijiajia\SaloonphpHttpProxyPlugin\Exceptions\NoAvailableProxyException; use Weijiajia\SaloonphpHttpProxyPlugin\Exceptions\HasProxyException; try { $connector->withForceProxy(true); $response = $connector->send(new MyRequest()); } catch (NoAvailableProxyException $e) { // Handle the case when no proxies are available echo "No proxies available: " . $e->getMessage(); } catch (HasProxyException $e) { // Handle interface implementation issues echo "Proxy configuration error: " . $e->getMessage(); } catch (\Exception $e) { // Handle other exceptions echo "Request error: " . $e->getMessage(); }
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This package is open-sourced software licensed under the MIT license.