PSR-18

PSR-18
Name	PSR-18
Subject	HTTP Client Messaging
Status	accepted
Published	2016
Organization	PHP-FIG
Language	PHP

PSR-18

PSR-18 provides a standardized HTTP client interface for PHP libraries and applications, enabling interoperability between HTTP client implementations and higher-level components. It complements other PHP Framework Interop Group proposals by defining method signatures and error handling behaviors so that libraries like Guzzle, Symfony HttpClient, and Zend HTTP can interoperate with frameworks such as Laravel, Symfony, and Drupal. The standard focuses on request and response objects and exceptions to ensure predictable integration across diverse ecosystems including Composer, Packagist, and PEAR.

Overview

PSR-18 specifies an interface for sending HTTP requests and receiving responses that is implementation-agnostic, allowing projects like Laravel (web framework), Symfony (software), Drupal, WordPress plugins, and libraries such as Guzzle and Zend Framework components to rely on a common client contract. It interacts closely with the message definitions from PSR-7 and the HTTP message factories from PSR-17, enabling projects including Composer (software), Packagist, Monolog, and Twig (template engine) to substitute client implementations without code changes. Integrations with dependency managers like Composer (software) and hosting platforms like Heroku or Platform.sh benefit from predictable wiring in containerized environments such as Docker and orchestration via Kubernetes.

History and Development

PSR-18 emerged within the PHP Framework Interop Group, where contributors from projects like Zend Framework, Symfony (software), Laravel (web framework), Guzzle, and Slim (framework) collaborated to address fragmentation around HTTP clients. Key discussions occurred during conferences such as PHPCon and meetings associated with organizations like OWASP and developer collectives around GitHub repositories and GitLab mirrors. The evolution was influenced by prior standards including PSR-7 and PSR-17, and by client libraries like Guzzle, Buzz (library), cURL wrappers, and Requests for PHP. Community feedback from projects such as Composer (software), Drupal, TYPO3, and Magento (software) shaped acceptance criteria and edge-case handling.

Specification and Requirements

The specification defines a single client interface with a sendRequest method that accepts a PSR-7 request object and returns a PSR-7 response object, aligning with factories introduced by PSR-17 and error semantics modeled after exceptions used in Symfony (software) and Zend Framework. Requirements include clear exception types for networking failures versus protocol errors so projects like Monolog, Sentry (company), New Relic, and Datadog can instrument and log issues consistently. The spec mandates synchronous behavior for the core API, which influenced integrations with asynchronous libraries such as ReactPHP, Amp (framework), and adapters used by Ratchet (websocket) and Workerman. The document prescribes behavior for redirects, streaming, and header normalization so adapters for cURL, fopen wrappers, and socket-based clients behave predictably in ecosystems like PaaS vendors including AWS Elastic Beanstalk and Google App Engine.

Implementations and Libraries

Several prominent implementations and adapters target the PSR-18 contract, including adapters for Guzzle, bridges in Symfony (software) components, libraries from Zend Framework, and lightweight clients within Diactoros (PHP)-adjacent projects. Other ecosystem tools such as HTTPlug, Buzz (library), Requests for PHP, and providers in WordPress plugins implemented wrappers to expose PSR-18 interfaces. Community projects on GitHub created bridge packages to map between clients like Guzzle, cURL, pecl_http, and platform services from Microsoft Azure SDKs or Google Cloud Platform client libraries. Integration libraries in ecosystems like Drupal, TYPO3, Magento (software), and Laravel (web framework) provide service container bindings and configuration profiles to swap implementations.

Adoption and Compatibility

Adoption of the PSR-18 interface was driven by major PHP ecosystems such as Symfony (software), Laravel (web framework), Drupal, and Zend Framework-derived projects, with package discoverability via Packagist and dependency resolution through Composer (software). Compatibility layers and bridge packages ensure older projects using Guzzle 5 or custom cURL wrappers can migrate incrementally while maintaining integrations with observability tools like Sentry (company), New Relic, and Datadog. Hosting vendors and platform services including Heroku, Platform.sh, AWS Elastic Beanstalk, and Google App Engine run PSR-18–compatible applications in production, while CI/CD pipelines using Jenkins, GitHub Actions, and GitLab CI test interoperability across client implementations.

Criticism and Limitations

Critiques of PSR-18 cite its synchronous-only core API as limiting for projects relying on event-driven stacks such as ReactPHP and Amp (framework), and for high-concurrency platforms like Swoole where asynchronous patterns are preferred. Some vendors and teams working on microservices frameworks and tooling such as RoadRunner (PHP) or Laravel Octane found the spec insufficient for streaming or advanced connection pooling needs, prompting community work on adapters and companion proposals. Others pointed to the dependency on PSR-7 and PSR-17 as adding boilerplate for simple scripts or legacy systems like older WordPress plugins, leading to adoption hesitancy in some ecosystems including bespoke CMS platforms and legacy e-commerce systems such as Magento (software).