Http Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require austral/http-bundle

Register the bundle in config/bundles.php:

Austral\HttpBundle\HttpBundle::class => ['all' => true],

2. First Use Case: Inject the HttpRequest service into a controller or service:

   use Austral\HttpBundle\Service\HttpRequest;
   
   class MyController extends AbstractController
   {
       public function __construct(private HttpRequest $httpRequest) {}
   
       public function index()
       {
           $requestData = $this->httpRequest->all();
           $domain = $this->httpRequest->getDomain();
           // Use $requestData or $domain as needed
       }
   }
   

3. Key Classes to Explore:

   • HttpRequest service (for request handling)
   • DomainManagement service (for domain logic)
   • HttpListener (for event-based HTTP handling)

Implementation Patterns

Core Workflows

1. Request Handling: Use HttpRequest to access/modify request data:

   $this->httpRequest->get('param_name'); // Get a single parameter
   $this->httpRequest->query();           // Get query parameters
   $this->httpRequest->request();         // Get request body
   $this->httpRequest->server();          // Get server variables
   

2. Domain Management: Leverage DomainManagement for virtual/master domain logic:

   $domain = $this->domainManagement->getDomain();
   $isRedirectDomain = $this->domainManagement->isRedirectDomain();
   

3. Event-Driven HTTP Logic: Extend HttpListener to handle kernel events:

   use Austral\HttpBundle\Event\HttpListener;
   
   class CustomHttpListener extends HttpListener
   {
       public function onKernelRequest(GetResponseEvent $event)
       {
           // Modify request/response logic here
       }
   }
   

   Register in services.yaml:

   services:
       Austral\HttpBundle\Event\HttpListener:
           tags: [kernel.event_listener]
   

4. Integration with Austral Ecosystem: Combine with Austral\EntityBundle for domain-aware entities:

   use Austral\EntityBundle\Entity\Domain;
   
   $domainEntity = $this->domainManagement->getDomainEntity();
   

Common Use Cases

• Multi-Tenant Request Handling: Use DomainManagement to route requests based on subdomains.
• Request Sanitization: Override HttpRequest methods to enforce custom validation.
• CORS/CSRF Middleware: Extend HttpListener to add security headers.

Gotchas and Tips

Pitfalls

1. Domain Resolution Quirks:

   • Virtual domains must be configured in config/packages/austral_http.yaml:

     austral_http:
         domains:
             virtual: ['app1', 'app2']
             master: 'example.com'
     

   • Forgetting to configure master domain may cause isRedirectDomain() to fail.

2. Request Overrides:

   • Modifying $this->httpRequest->server() directly may break Laravel’s internal request handling. Use HttpListener for kernel-level changes.

3. Event Dispatching:

   • HttpListener events are dispatched before Laravel’s middleware. Place logic carefully to avoid conflicts.

4. PHP Version Compatibility:

   • Ensure symfony/http-kernel version matches your Laravel version (e.g., Laravel 10 → Symfony 6.4).

Debugging Tips

1. Check Domain Logic:

   dd($this->domainManagement->getDomain(), $this->domainManagement->isRedirectDomain());
   

2. Inspect Request Data:

   dd($this->httpRequest->toArray()); // Dump all request data
   

3. Event Debugging:
   • Temporarily log events in HttpListener:

     public function onKernelRequest(GetResponseEvent $event)
     {
         \Log::debug('Request event triggered', ['request' => $event->getRequest()]);
     }
     

Extension Points

1. Custom Request Services: Extend HttpRequest to add project-specific methods:

   class CustomHttpRequest extends HttpRequest
   {
       public function getUserAgent()
       {
           return $this->server('HTTP_USER_AGENT', '');
       }
   }
   

   Bind in services.yaml:

   services:
       Austral\HttpBundle\Service\HttpRequest:
           class: App\Service\CustomHttpRequest
   

2. Domain Strategies: Override DomainManagement to implement custom domain resolution:

   class CustomDomainManagement extends DomainManagement
   {
       protected function resolveDomain(): string
       {
           // Custom logic (e.g., database lookup)
           return 'custom-domain.com';
       }
   }
   

3. Event Subscribers: Create subscribers for HttpListener events:

   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class HttpEventSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               HttpListener::ON_KERNEL_REQUEST => 'onKernelRequest',
           ];
       }
   
       public function onKernelRequest(GetResponseEvent $event)
       {
           // Subscriber logic
       }
   }
   

Configuration Quirks

• Default Config Path: config/packages/austral_http.yaml (auto-generated if missing).
• Environment Overrides: Use config('austral_http.domains') to access runtime config.
• Caching: Domain resolution is not cached by default. Implement caching in DomainManagement if needed:

  $domain = Cache::remember("domain_{$request->getHost()}", 3600, fn() => $this->resolveDomain());