Http Laravel Package

Getting Started

The illuminate/http package is Laravel’s core HTTP abstraction layer—used daily via Request and Response classes, but rarely instantiated directly. Start by:

• Opening a controller in a Laravel app and observing method-injected Request usage (e.g., store(Request $request)).
• Reading the Laravel HTTP Requests and HTTP Responses docs—these are the illuminate/http docs.
• First practical step: Inject Request into a controller method and use $request->input(), $request->validate(), or $request->user().

Implementation Patterns

• Input Handling: Use Request type-hints for automatic population of user input, query strings, cookies, headers, and uploaded files:

  public function update(Request $request, User $user)
  {
      $user->fill($request->validate([
          'name' => 'sometimes|string|max:255',
          'email' => 'sometimes|email|unique:users,email,' . $user->id,
      ]));
      $user->save();
  }
  

• Structured Responses: Prefer response()->json() or response()->view() over manually constructing Response. Chain headers, cookies, and status codes:

  return response()
      ->json(['error' => 'Not found'], 404)
      ->withHeaders(['X-Request-Id' => Str::uuid()]);
  

• Custom Requests: Leverage FormRequest for validation/authorization separation—store() and update() share logic via Request inheritance but enforce different rules:

  // app/Http/Requests/StoreUserRequest.php
  public function rules(): array
  {
      return ['email' => 'required|email|unique:users'];
  }
  

• Testing Patterns: Use TestResponse assertions on responses from get(), postJson(), etc.:

  $response = $this->getJson('/api/users');
  $response->assertStatus(200)->assertJsonCount(10, 'data');
  

• HTTP Client Integration: While illuminate/http provides Response/Request, use Http::retry() (built on Guzzle) for outbound calls—this uses illuminate/http for parsing responses:

  $response = Http::retry(3, 100)->post('https://api.example.com/users', $payload);
  $userId = $response->json('id');
  

Gotchas and Tips

• Manual Instantiation Risk: Avoid new Request($_GET, $_POST, ..., $_COOKIE)—this bypasses Laravel’s Request::capture() and request lifecycle setup. Use Request::createFromBase() if absolutely necessary (e.g., console commands triggering HTTP context).
• Validation Gotcha: validate() throws ValidationException—not 422 directly—handled globally by Laravel’s exception renderer. In API tests, assert for 422 only after Laravel’s ValidationException handler runs.
• File Uploads: $request->file('avatar') returns UploadedFile—always verify with $file->isValid() before operations. Skipping this risks security or errors.
• Header Case: ->header('Content-Type') won’t work—use lowercase or let Laravel normalize: ->header('content-type', 'application/json').
• Macroable Limits: While Request/Response are macroable,macros added via Request::macro() break PHPStan/Psalm unless cast to mixed. Prefer helpers like request()->safe() for clarity.
• Trusted Proxies: If behind Nginx/AWS ELB, misconfigured trustedproxies causes $request->ip() to return the proxy’s IP—not the client’s. Set TRUSTED_PROXIES='*' (dev) or explicit IPs in production.
• Test Tip: In Pest, use withHeaders(['X-API-Key' => 'secret'])— Laravel translates this into Request headers before route/controller binding, crucial for auth middleware tests.