Behind A Proxy Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cnerta/behind-a-proxy-bundle:1.0.*
   

   Add to AppKernel.php:

   new Cnerta\BehindAProxyBundle\CnertaBehindAProxyBundle(),
   

2. Basic Configuration (config/packages/cnerta_behind_a_proxy.yaml):

   cnerta_behind_a_proxy:
       enabled: true
       proxy_host: "your-proxy-host"
       proxy_port: 8080
       proxy_username: "optional-user"
       proxy_password: "optional-pass"
   

3. First Use Case: Enable the bundle and configure proxy settings. Test with a curl request in a controller:

   use Symfony\Component\HttpFoundation\Request;
   
   public function testProxy(Request $request) {
       $response = $request->getClient()->request('GET', 'http://example.com');
       return new Response($response->getContent());
   }
   

Implementation Patterns

Core Workflows

1. Global Proxy Configuration:

   • Centralize proxy settings in config/packages/cnerta_behind_a_proxy.yaml.
   • Toggle enabled to activate/deactivate globally.

2. Context-Specific Overrides: Use the bundle’s ProxyContext service to override settings per request:

   $context = $this->get('cnerta_behind_a_proxy.context');
   $context->setProxyHost('custom-proxy.example.com');
   

3. Integration with HTTP Clients:

   • Symfony HTTP Client: Automatically respects proxy settings.
   • Guzzle: Extend the bundle’s ProxyClient or inject the ProxyContext:

     $client = new Client([
         'handler' => HandlerStack::create($this->get('cnerta_behind_a_proxy.handler')),
     ]);
     

4. SoapClient Integration: Pass the bundle’s ProxyContext to SoapClient:

   $context = $this->get('cnerta_behind_a_proxy.context');
   $soapClient = new SoapClient($wsdl, [
       'stream_context' => $context->getStreamContext(),
   ]);
   

5. Stream Context for Raw PHP: Use the ProxyContext to generate stream contexts for file_get_contents or stream_context_create:

   $context = $this->get('cnerta_behind_a_proxy.context');
   file_get_contents('http://example.com', false, $context->getStreamContext());
   

Advanced Patterns

1. Dynamic Proxy Routing: Use dependency injection to conditionally enable proxies:

   services:
       App\Service\DynamicProxyService:
           arguments:
               $proxyContext: '@cnerta_behind_a_proxy.context'
   

2. Proxy-Aware Middleware: Create middleware to log or modify proxy behavior:

   public function handle(Request $request, Closure $next) {
       $this->get('cnerta_behind_a_proxy.context')->logProxyUsage();
       return $next($request);
   }
   

3. Environment-Specific Configs: Override proxy settings per environment (e.g., config/packages/dev/cnerta_behind_a_proxy.yaml).

Gotchas and Tips

Pitfalls

1. Deprecation Warnings:

   • host_ssl is removed in v2.0.0 (use proxy_host + proxy_port with https://).
   • PHP 5.4+ required for v2.0.0; use 1.0.* for older versions.

2. Configuration Overrides:

   • YAML config must match the bundle’s expected keys (e.g., proxy_host, not http_proxy).
   • Case-sensitive: enabled: true (not Enabled: true).

3. Stream Context Conflicts:

   • If using file_get_contents with custom stream options, merge contexts manually:

     $proxyContext = $this->get('cnerta_behind_a_proxy.context')->getStreamContext();
     $customOptions = ['http' => ['header' => "User-Agent: MyApp\r\n"]];
     $mergedContext = stream_context_create($proxyContext, $customOptions);
     

4. SoapClient Quirks:

   • Some SoapClient versions ignore stream contexts. Use SoapClient::setUseCurl():

     $soapClient = new SoapClient($wsdl, [
         'stream_context' => $context->getStreamContext(),
         'use_curl' => true,
     ]);
     

5. Debugging:

   • Enable debug mode in config/packages/dev/monolog.yaml to log proxy requests:

     handlers:
         proxy_log:
             type: stream
             path: "%kernel.logs_dir%/proxy.log"
             level: debug
     

Tips

1. Testing:

   • Mock the ProxyContext in PHPUnit:

     $this->get('cnerta_behind_a_proxy.context')->setProxyHost('test-proxy');
     

2. Performance:

   • Disable the bundle in production if unused (enabled: false) to avoid overhead.

3. Extending:

   • Override the ProxyContext service to add custom logic:

     services:
         cnerta_behind_a_proxy.context:
             class: App\Service\CustomProxyContext
             parent: cnerta_behind_a_proxy.context
     

4. Fallbacks:

   • Implement a fallback proxy resolver:

     $context = $this->get('cnerta_behind_a_proxy.context');
     if (!$context->isProxyConfigured()) {
         $context->setProxyHost(config('app.fallback_proxy'));
     }
     

5. Security:

   • Avoid hardcoding credentials. Use environment variables or Symfony’s parameter_bag:

     parameters:
         proxy_password: '%env(APP_PROXY_PASSWORD)%'