☰
Trongate MX Docs
Introduction
Core HTTP Operations
Swapping Content
Events & Responses
Dynamic Form Handing
UI Enhancements
Data Management
Form Handling
Advanced Features
Trongate MX Security
Reference

Custom Headers

The mx-headers attribute allows you to add custom HTTP headers to your Trongate MX requests. This feature is particularly useful when you need to send additional information to your server endpoints, such as authentication tokens, API keys, or custom metadata.

Critical Header Naming Requirements:

  • Use hyphens (-), NEVER underscores (_) - Header names containing underscores are often dropped by web servers and proxies for security reasons. This is the most common cause of headers not being received.
  • Prefix custom headers with "X-" - This is the standard convention for custom application headers (e.g., X-Request-ID, X-API-Key, X-Current-URL).
  • Use Title-Case for readability - While HTTP headers are case-insensitive by specification, X-Current-URL is more readable and conventional than x-current-url.

Header Naming Examples

Correct header names (will work):

Incorrect header names (will likely fail):

Quick Rule: If you're creating a custom header name, always use the format X-Your-Header-Name with hyphens separating words. This ensures maximum compatibility across all web servers and HTTP infrastructure.

Basic Usage

The mx-headers attribute accepts a JSON object containing key-value pairs that represent your custom headers. Each key-value pair will be sent as an HTTP header with your request.

Here's a basic example using Trongate's helper function:

And here's the equivalent using pure HTML:

The example above is for illustration purposes only. Never hardcode security tokens or API keys directly into HTML source code. These credentials would be visible in the page source and could pose significant security risks.

Cleaner Syntax for Advanced Use

To avoid syntax errors and improve maintainability when working with multiple headers, you can combine Trongate's function with PHP's json_encode():

This approach uses PHP's json_encode() function to ensure properly formatted JSON for the mx-headers attribute while keeping the code maintainable.

For those who prefer to work primarily with HTML, here's an alternative syntax:

Important Technical Considerations

  • The mx-headers value must be valid JSON - malformed JSON will cause the request to fail
  • When using HTML attributes directly, use single quotes around the attribute value since JSON requires double quotes for properties
  • Header names are case-insensitive according to the HTTP specification, but conventionally written in Title-Case
  • Some headers (like Content-Length) are automatically managed by browsers and cannot be set via JavaScript

Common Use Cases

1. Authentication Headers

Authentication is a primary use case for custom headers. Here's a secure implementation using the function:

Authentication Best Practices:

  • Use Bearer authentication for JWTs and OAuth 2.0 access tokens
  • Implement CSRF protection for POST requests
  • Store tokens securely (e.g., in HTTP-only cookies for session tokens)
  • Use short-lived tokens and implement proper token rotation

2. API Version Headers

Version headers help manage API compatibility:

3. Request Tracking Headers

Custom headers can help with request tracking and debugging:

Security Considerations

Critical Security Guidelines:

  • Always use HTTPS for requests containing sensitive headers
  • Validate and sanitize all header values on both client and server sides
  • Store sensitive tokens securely
  • Implement rate limiting on endpoints that accept custom headers

Reading Custom Headers on the Server

Custom headers sent via mx-headers are accessible in PHP through the $_SERVER superglobal. Header names are automatically transformed to uppercase with HTTP_ prefix, and hyphens become underscores.

For example, if you send X-Current-URL, access it as $_SERVER['HTTP_X_CURRENT_URL'].

Fetching a Specific Header Value

Fetching All Custom Headers as an Array

Quick Tip: Use the null coalescing operator (??) with an empty string to safely handle missing headers.

Conclusion

The mx-headers attribute provides a flexible way to include custom HTTP headers in your Trongate MX requests. When implemented with proper security considerations, it enables robust authentication, versioning, and request tracking capabilities in your applications.