Client Login

PHP Integration

6 min read

Use this guide to integrate InstantProxies into PHP applications, services, workers, and request-driven automation workflows.

PHP is often used in web applications, backend services, internal tools, and automation scripts where request behavior needs to remain explicit and predictable. Proxy integration should be handled as reusable client infrastructure, not embedded into request code or business logic.

Use PHP when

PHP is a good fit when your workload depends on:

  • web applications and backend services
  • internal tools and automation scripts
  • request-driven workflows that need predictable configuration
  • systems where timeout behavior and environment handling should remain explicit
  • codebases that benefit from separating transport logic from application logic

If your workflow is fully browser-driven, use a browser automation guide instead. If you need fast baseline validation before application integration, start with First Request with cURL.

Integration requirements

A production-ready PHP integration should be:

  • predictable across development, staging, and production environments
  • built around reusable client configuration
  • easy to validate before larger workflow complexity is introduced
  • compatible with timeout, retry, and logging strategies
  • structured so transport behavior stays separate from application logic
  • maintainable for long-lived services and team-owned systems

Choose the client model first

The most common PHP paths are:

  • cURL for lower-level control and lightweight request execution
  • Guzzle for reusable client configuration, middleware-friendly design, and structured application integration

Choose one client model early. Keep the proxy path, timeout behavior, and logging model consistent around that client.

Treat proxy configuration as client design

Do not scatter proxy settings across request code or utility methods.

Separate:

  • client construction
  • proxy configuration
  • timeout behavior
  • environment-specific values
  • logging and validation hooks
  • request execution logic

This keeps transport behavior consistent and easier to debug.

Start with a minimal validation path

Validate the proxy path with the smallest possible example before embedding it into a larger application flow.

The first validation path should prove that:

  • the client uses the intended proxy path
  • timeout behavior is visible
  • the runtime behaves the way the code assumes it does
  • one simple request completes successfully

If you have not yet proven the proxy path outside PHP, pair this page with Verify Your Connection.

cURL example

Use cURL when you want a direct and lightweight request path with explicit transport options.

<?php

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://httpbin.org/ip',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROXY => 'http://YOUR_PROXY_HOST:PORT',
    CURLOPT_TIMEOUT => 20,
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($response === false) {
    throw new Exception(curl_error($ch));
}

curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Use this first to verify that:

  • the client uses the intended proxy route
  • timeout behavior is explicit
  • one simple request completes successfully

Guzzle example

Use Guzzle when your application needs a reusable client abstraction with more structured configuration.

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'proxy' => 'http://YOUR_PROXY_HOST:PORT',
    'timeout' => 20,
]);

$response = $client->request('GET', 'https://httpbin.org/ip');

echo $response->getStatusCode() . PHP_EOL;
echo $response->getBody() . PHP_EOL;

Use Guzzle when the codebase benefits from shared configuration, reusable clients, and cleaner request-layer structure.

Configure authentication correctly

InstantProxies supports:

  • IP whitelisting or authorization
  • username and password authentication

If IP whitelisting is active, authorize the public IP of the real runtime environment.

If username and password authentication is active, keep credentials in environment-aware configuration and build the proxy configuration intentionally.

cURL credential example

<?php

$username = getenv('INSTANTPROXIES_USERNAME');
$password = getenv('INSTANTPROXIES_PASSWORD');
host = getenv('INSTANTPROXIES_HOST');
$port = getenv('INSTANTPROXIES_PORT');

$proxy = "http://{$username}:{$password}@{$host}:{$port}";

Guzzle credential example

<?php

$proxy = sprintf(
    'http://%s:%s@%s:%s',
    getenv('INSTANTPROXIES_USERNAME'),
    getenv('INSTANTPROXIES_PASSWORD'),
    getenv('INSTANTPROXIES_HOST'),
    getenv('INSTANTPROXIES_PORT')
);

Do not hardcode credentials.

If authentication fails, see Authentication and Allowlist Errors.

Keep client setup separate from request logic

Request handlers and service logic should use a configured client. They should not rebuild proxy settings or timeouts inline.

Centralize:

  • client creation
  • proxy settings
  • timeout values
  • environment-specific configuration
  • validation helpers
  • logging hooks

This improves maintainability and keeps runtime behavior consistent across the codebase.

Validate in stages

Validate in this order:

  1. one clean proxied request
  2. repeated execution of the same request
  3. timeout behavior
  4. reusable client construction
  5. structured logging
  6. retries
  7. higher request volume or broader workflow behavior

Do not start with full application flow or retry-heavy logic.

Make timeouts explicit

Timeout behavior should be configured deliberately.

Timeouts affect:

  • how quickly failures surface
  • whether degraded conditions are visible or hidden
  • how retries behave later
  • how easy it is to classify failures accurately

Set timeout behavior explicitly in cURL or the client configuration. Do not rely on vague defaults for production workloads.

If timeout design needs deeper review, see Timeout Strategy.

Reuse clients intentionally

A PHP proxy integration is usually stronger when the client is reused rather than rebuilt at each call site.

Reusable client design improves:

  • consistency across requests
  • readability of the codebase
  • shared timeout and logging behavior
  • environment-specific configuration handling
  • long-term maintainability of proxy-backed workflows

Client construction should normally be centralized.

Add retries only after validating the base client path

Retries can help, but only after the base request path is understood.

Premature retries often:

  • hide client or authentication problems
  • multiply slow request paths
  • make logs harder to interpret
  • increase activity without improving useful throughput

Validate the client first. Then add retries only where recovery assumptions are realistic and observable.

If retry behavior needs deeper review, see Retry Strategy and Failure Recovery.

Log client-level signals

Log enough information to answer:

  • which client configuration was used
  • what timeout assumptions applied
  • whether the request followed the intended proxy path
  • whether the visible issue looks local, proxy-related, or target-side
  • whether the environment changed the behavior

Use structured logging where possible.

For deeper guidance, see Logging and Diagnostic Signals.

Environment consistency matters

PHP integrations often move across:

  • local development
  • staging
  • production servers
  • containers
  • scheduled tasks and workers

Keep proxy-backed behavior environment-aware. A one-time success in one runtime is not enough evidence for broader confidence.

Common failure patterns

Typical issues include:

  • embedding proxy settings directly into request logic
  • leaving timeout behavior vague or inconsistent
  • validating one request and assuming the broader workflow is ready
  • adding retries before the base request path is understood
  • weak separation between environment-specific values and application code
  • rebuilding client configuration too often instead of reusing it cleanly

Use this sequence:

  1. define proxy and authentication settings in environment-aware configuration
  2. build one reusable client
  3. validate one request path
  4. repeat the same path from the same environment
  5. make timeouts explicit
  6. add structured logging
  7. add retries and broader workflow complexity only after repeated execution is stable

Key points

  • model proxy behavior through reusable client configuration
  • keep client setup separate from request and application logic
  • validate repeated runs, not just one successful request
  • make timeouts, logging, and authentication explicit
  • reuse clients intentionally
  • add retries only after the base path is understood

Next step

If the integration works but behaves inconsistently across environments or repeated execution, continue to Debugging Integration Issues.

If the next concern is broader workload stability, continue to Reliability.