Add support for custom headers in OData requests

[Copilot]

Implements optional custom header support for OData requests, addressing issue #23. This feature allows consumers to add authentication tokens, tracking headers, or other custom headers to their OData requests without requiring any changes to existing code.

Progress

• Implement custom headers support in IODataClient interface
• Add header management methods to ODataClient class
• Add fluent header methods to Query Builder
• Create comprehensive unit tests
• Add documentation and usage examples to README
• Create detailed example file (examples/custom_headers_example.php)
• Add reference to example file in README

Features

Client-Level Headers (Global)

Set headers that apply to all requests made by the client:

$client = new ODataClient($serviceUrl, null, $httpProvider);

// Set multiple headers at once
$client->setHeaders([
    'Authorization' => 'Bearer your-token-here',
    'X-API-Key' => 'your-api-key',
    'X-Client-Version' => '1.0.0'
]);

// Add a single header
$client->addHeader('X-Request-ID', uniqid());

// All subsequent requests will include these headers
$people = $client->from('People')->get();

Query-Level Headers (Per-Request)

Add headers to specific queries using the fluent interface:

// Headers for a specific query only
$people = $client->from('People')
    ->withHeader('X-Query-Context', 'get-all-people')
    ->withHeaders([
        'X-Debug' => 'true',
        'X-Performance-Track' => 'enabled'
    ])
    ->get();

// Different headers for different queries
$airlines = $client->from('Airlines')
    ->withHeader('X-Data-Source', 'airlines-api')
    ->get();

Key Benefits

• Fully Optional: Existing code continues to work without any changes
• Flexible: Set headers globally on the client or per-query
• Fluent: All header methods support method chaining with existing query methods
• Preserved: Default OData headers (Content-Type, OData-Version, etc.) are automatically maintained
• Isolated: Query-specific headers don't affect the client's global headers

Implementation Details

• Added setHeaders(), getHeaders(), and addHeader() methods to IODataClient interface
• Implemented header storage and management in ODataClient class
• Added withHeader() and withHeaders() methods to Query\Builder for fluent per-query headers
• Integrated with existing ODataRequest->addHeaders() method for HTTP transmission
• All header methods return the client/builder instance for method chaining

Backward Compatibility

This is a non-breaking change. All existing code will continue to work exactly as before. The custom headers feature is completely optional and only activated when explicitly used.

Testing

Includes comprehensive unit tests covering:

• Header management methods
• Fluent interface functionality
• Integration with HTTP providers
• Backward compatibility verification
• Query builder header isolation

Documentation and usage examples have been added to the README, including a reference to a complete working example at examples/custom_headers_example.php.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[anderly]

@copilot update the readme to mention the sample usage.

[Copilot]

@copilot update the readme to mention the sample usage.

I've added a reference to the custom headers example file in the README. The Custom Headers section now includes a link to examples/custom_headers_example.php for a complete working example. Changes included in commit f69cc9b.