Dynamic Access-Control-Expose-Headers Support

[yinheli]

Add Dynamic Support for Access-Control-Expose-Headers

This PR implements dynamic support for the Access-Control-Expose-Headers header in php-cors, addressing the need for more flexible CORS header management in complex applications.

Proposal issue: #29

Changes

• Update CorsService to merge existing exposed headers with configured
• Add deduplication for exposed headers

Benefits

• Allows developers to set exposed headers dynamically at the controller or middleware level.
• Provides greater flexibility for applications with diverse API endpoints requiring different header exposures.
• Maintains backwards compatibility with existing global configuration.

Testing

I've added new unit tests to cover.

Feedback and suggestions are welcome. Thank you!

[barryvdh]

What would be the use-case of adding these headers in the controller or middleware?

[yinheli]

Here are some common use cases for dynamically adding Access-Control-Expose-Headers in controllers or middleware:

1. Custom Pagination Headers

• When specific API endpoints need to expose pagination headers like X-Total-Count, X-Page-Count
• These headers may only be relevant for paginated list endpoints, not needed globally

2. API Version Headers

• Exposing version headers (X-API-Version) only for versioned API routes
• Keeping header exposure scoped to relevant endpoints

3. Resource-Specific Headers

• Custom headers like X-Resource-ID, X-Last-Modified for specific resources
• No need to expose these headers on all routes

4. Authentication/Authorization Headers

• Selectively exposing auth-related headers (X-Token-Expiry, X-Refresh-Token)
• Only needed on auth-related endpoints

5. Rate Limiting Headers

• Headers like X-RateLimit-Remaining for rate-limited endpoints
• Not applicable to all routes

This dynamic approach allows applications to:

• Keep CORS header exposure minimal and relevant
• Avoid exposing unnecessary headers globally
• Have fine-grained control per route/controller
• Improve security by limiting header exposure

The proposed implementation provides this flexibility while maintaining backwards compatibility with global configuration.

Imagine that if you are maintaining a large monolithic application, you wouldn't want the CORS middleware configuration to affect many routes.