php-fig/fig-standards — pull request #353 by weierophinney (2014-10-14 16:48:29+00:00)
Title: [PSR-7] Clarify MessageInterface header methods

This edit contains a number of changes around the various header methods of the `MessageInterface` as proposed on the mailing list.

Per [this thread](https://groups.google.com/d/msgid/php-fig/248eaec5-bf0b-4a8c-bdd1-66adb0992477%40googlegroups.com):

- Updating `addHeaders()` and `setHeaders()` to indicate that they expect the same argument: an associative array with values that can be either a string, an object that can be cast to a string, or an array of such values.
- Updating `addHeader()` to indicate it should have the same arguments as `setHeader()`: string, object that can be cast to a string, or an array of such values.

Per [this thread](https://groups.google.com/d/msgid/php-fig/05dd990a-459e-4fa4-8617-04b820da51eb%40googlegroups.com?utm_medium=email&utm_source=footer):

- Added `clearHeaders()`, which is intended for emptying the existing header stack.
- Modified `setHeaders()` to indicate it should not remove existing headers, only overwrite those passed to it; `clearHeaders()` MUST be called first if you wish to reset with only those you are passing to `setHeaders()`.

Per [this thread](https://groups.google.com/d/msg/php-fig/H_NR7qctw-8/EaBO5amhCSYJ):

- Added language to each of the `(add|set)Headers?()` docblocks to indicate that header values passed as objects MUST be cast to string _immediately_ to ensure consistent runtime behavior.