Laravel 5 / Lumen Request Header?

Laravel 5 / Lumen Request Header?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Accessing Custom HTTP Headers in Laravel and Lumen

When working with APIs or custom integrations, you often encounter headers that aren't part of the standard set like Content-Type or Authorization. A common scenario involves passing a proprietary token or identifier via a header, such as pubapi, to authenticate your application with a third-party service. If you are using Laravel or Lumen, retrieving this value inside your controller requires understanding how the framework exposes HTTP metadata to your code.

The most frequent mistake developers make is assuming that standard collection methods like Request::all() will capture headers. In reality, Request::all() (and its alias $request->all()) exclusively returns data from the request body and query parameters. It does not inspect the header line of the HTTP transaction. Consequently, attempting to echo a custom header using this method will return an empty array or result in unexpected behavior, failing to retrieve the value you need.

To access a specific header like pubapi, you must utilize the dedicated accessor provided by the Illuminate\Http\Request class. The standard method for this is header(). You can call this statically via the helper or instance-based on your request object.

use Illuminate\Http\Request;

public function show(Request $request)
{
    // Accessing the header value
    $pubApiToken = $request->header('pubapi');

    // Or using the static method if preferred in older versions
    // $pubApiToken = Request::header('pubapi');
}

It is important to note the case-sensitivity of headers in this context. While HTTP standards technically define header names as case-insensitive, many server implementations and proxy configurations normalize them to lowercase before they reach your application. In Laravel and Lumen, the header() method handles this normalization automatically, so calling $request->header('PubAPI') will successfully retrieve a value sent as pubapi.

However, there is a critical nuance regarding how these headers are passed from Postman or other tools. If you are sending your header through the "Headers" tab in Postman, ensure that the header name matches what your backend expects. If your backend documentation specifies case-sensitive matching and your server is not normalizing headers, you might need to send it exactly as specified.

If header('pubapi') returns null, double-check the spelling and ensure the header is actually being sent with the request payload. Another common pitfall involves Content-Type mismatches. While less likely to cause a null result for a simple string value, if your application logic expects JSON but receives form data (or vice versa), the framework might behave differently depending on how you parse the input later.

For more complex scenarios where you need to inspect multiple headers at once or validate them against a schema, consider using the headers method which returns an associative array of all header values. This allows for batch processing but requires careful handling of case normalization if you are iterating over keys manually.

$headers = $request->headers;
$pubApiToken = $headers['pubapi']; // Accessing via lowercase key is safest

Understanding the distinction between body parameters and HTTP headers is fundamental to building robust API integrations. By leveraging the header() method correctly, you can seamlessly extract custom metadata from incoming requests without falling into the trap of using generic collection methods meant for form data.

Our network