I'd like to point out some problems with the formal interfaces provided by several packages belonging to the PSR standards.
Starting with this example: [image: screenshot.png] This inspection failure (in PHP Storm) of course is bunk - and static analysis can easily *prove* that it's bunk: since $abs_path is statically type-hinted as string, it's a string. The issue here is the interface declaration: [image: screenshot.png] Interfaces (obviously) do not throw exceptions - their implementations do that. The underlying issue I'm trying to highlight here, is that, as a consumer of *implementations* of these interfaces, what I'm seeing in the doc-blocks of most PSR interfaces and methods isn't documentation for me as a consumer - it's documentation for the developers who implemented them. Here's another worse example from PSR-7's ServerRequestInterface: [image: screenshot.png] Reading this, as a consumer, I'm completely side-tracked by confusing and misleading details, such as "This method MUST NOT update the related Cookie header of the request instance, nor related values in the server params" - explicit directions for implementors, of no relevance at them time when you're consuming them. Interfaces shouldn't have language like this - for example, "*MUST return* an instance that has the updated cookie values" ought to be "*Returns* an instance that has the updated cookie values", and so on. So I'm highlighting two problems here: frequent misleading or incorrect use of doc-blocks, and confusing explanations/specifications as opposed to consumer-facing explanations/expectations. But it sort of comes down to the same thing - we've been treating the interfaces as though they *are* the specification, with documentation and doc-blocks written for implementors as opposed to consumers. You don't normally do that in your own interfaces, do you? Why do we do that in PSRs? -- You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group. To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscr...@googlegroups.com. To post to this group, send email to php-fig@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/cbf43fce-19e9-4dc3-906c-d53d1972b81a%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
