PHPackages                             weijiajia/saloonphp-http-proxy-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. weijiajia/saloonphp-http-proxy-plugin

ActiveLibrary[HTTP & Networking](/categories/http)

weijiajia/saloonphp-http-proxy-plugin
=====================================

A robust HTTP proxy management plugin for Saloon PHP, allowing easy proxy rotation and failover.

1106PHP

Since Jun 26Pushed 10mo ago1 watchersCompare

[ Source](https://github.com/jackchang1025/saloonphp-http-proxy-plugin)[ Packagist](https://packagist.org/packages/weijiajia/saloonphp-http-proxy-plugin)[ RSS](/packages/weijiajia-saloonphp-http-proxy-plugin/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Saloon PHP HTTP Proxy Plugin
============================

[](#saloon-php-http-proxy-plugin)

[![Latest Version on Packagist](https://camo.githubusercontent.com/8c9745bd90b1ec7e0059b568b788985e12a403a71e2eb0f854149cbe223a9725/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7765696a69616a69612f73616c6f6f6e7068702d687474702d70726f78792d706c7567696e2e737667)](https://packagist.org/packages/weijiajia/saloonphp-http-proxy-plugin)[![Total Downloads](https://camo.githubusercontent.com/7b271fbc01b9a839eb9b6ac65e12ef3bf739b44e0894bc2d703a7ae951344625/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7765696a69616a69612f73616c6f6f6e7068702d687474702d70726f78792d706c7567696e2e737667)](https://packagist.org/packages/weijiajia/saloonphp-http-proxy-plugin)

A robust HTTP proxy management plugin for [Saloon PHP](https://github.com/saloonphp/saloon), allowing you to easily use and rotate proxies in your API requests.

[中文文档](README.zh-CN.md) | [English](README.md)

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
    - [Basic Setup](#basic-setup)
    - [Adding Proxies](#adding-proxies)
    - [Proxy Rotation](#proxy-rotation)
    - [Custom Proxy Switching](#custom-proxy-switching)
    - [Force Using Proxies](#force-using-proxies)
    - [Temporarily Disable Proxies](#temporarily-disable-proxies)
    - [Proxy Availability Management](#proxy-availability-management)
- [Advanced Usage](#advanced-usage)
    - [Custom Proxy Queue](#custom-proxy-queue)
    - [Request-Specific Proxies](#request-specific-proxies)
    - [Concurrent Requests](#concurrent-requests)
    - [Error Handling](#error-handling)
- [Contributing](#contributing)
- [License](#license)
- [Credits](#credits)

Features
--------

[](#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
------------

[](#requirements)

- PHP 8.0 or higher
- Saloon PHP v2.0 or higher

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require weijiajia/saloonphp-http-proxy-plugin
```

Usage
-----

[](#usage)

### Basic Setup

[](#basic-setup)

1. Implement the `ProxyManagerInterface` in your connector or request class
2. 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

[](#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

[](#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

[](#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

[](#temporarily-disable-proxies)

```
$connector->withProxyEnabled(false);
```

### Proxy Availability Management

[](#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
--------------

[](#advanced-usage)

### Custom Proxy Queue

[](#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

[](#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

[](#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
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

License
-------

[](#license)

This package is open-sourced software licensed under the MIT license.

Credits
-------

[](#credits)

- [weijiajia](https://github.com/weijiajia)
- [All Contributors](../../contributors)

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance39

Infrequent updates — may be unmaintained

Popularity11

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity14

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/636557533fde1107bb301eca908de1c17c9ea7073d5c9c0fbad725ccd0800bde?d=identicon)[jackchang1025](/maintainers/jackchang1025)

---

Top Contributors

[![422066139](https://avatars.githubusercontent.com/u/1780162?v=4)](https://github.com/422066139 "422066139 (7 commits)")

### Embed Badge

![Health badge](/badges/weijiajia-saloonphp-http-proxy-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/weijiajia-saloonphp-http-proxy-plugin/health.svg)](https://phpackages.com/packages/weijiajia-saloonphp-http-proxy-plugin)
```

###  Alternatives

[friendsofsymfony/rest-bundle

This Bundle provides various tools to rapidly develop RESTful API's with Symfony

2.8k73.3M319](/packages/friendsofsymfony-rest-bundle)[php-http/discovery

Finds and installs PSR-7, PSR-17, PSR-18 and HTTPlug implementations

1.3k309.5M1.2k](/packages/php-http-discovery)[nyholm/psr7

A fast PHP7 implementation of PSR-7

1.3k235.4M2.4k](/packages/nyholm-psr7)[pusher/pusher-php-server

Library for interacting with the Pusher REST API

1.5k94.8M293](/packages/pusher-pusher-php-server)[spatie/crawler

Crawl all internal links found on a website

2.8k16.3M52](/packages/spatie-crawler)[react/http

Event-driven, streaming HTTP client and server implementation for ReactPHP

78126.4M414](/packages/react-http)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)