A proposal for a HTTP Client

[Benjamin Eberlei]

See https://github.com/php-fig/fig-standards/pull/24

From the introduction:

Many libraries and applications require an HTTP client to talk to other servers. In general all these libraries either ship their own HTTP client library, or use low-level PHP functionality such as file_get_contents, ext/curl or the ext/socket. Depending on the use-cases there are very tricky implementation details to be handled such as proxies, SSL, authentication protocols and many more. Not every small library can afford to implement all the different details. However there are only a few http client libraries that are widely used between different projects, because of NIH or fears of vendor lock-in.

Motivation:

Doctrine has about 4 projects that need an HTTP client. Currently every projects implements them itself, which is annoying. We could abstract this into our "Common" library, however that would mean we would start being a "http client" vendor. Now personally, i don't care about http clients and would rather let others do this, however i also don't want to face vendor lock-in by deciding for any of the many http clients. In a perfect world (with this standard) Doctrine could ship one very simple http client using sockets, and if anyone needs something more awesome, he could just use any other provider of a PSR http client.

Questions:

1. Do the voting members think this is something to standardize?
2. API: I didn't include a Request object as i think its not really necessary. The proposal is expclicitly very simple.
3. How to proceed?
4. Feedback?

greetings,
Benjamin

[Benjamin Eberlei]

Ah more questions of course:

* Did i forget something on the request?
* Did i forget something on the response?
* Should the http client be bound to a host? so that $url is not containing a host? Or should the client wiggle this itself?

[Hari K T]

Hi Benjamin Eberlei, 

ie really a great proposal looking from my point of view . I would have loved if php itself had one in core :-) .

Hope all will support this in a single voice :-)

Thank you

Hari K T
M: +91-9388758821 | W: http://harikt.com/blog

--
You received this message because you are subscribed to the Google Groups "PHP Standards Working Group" group.
To post to this group, send email to php-st...@googlegroups.com.
To unsubscribe from this group, send email to php-standard...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/php-standards?hl=en.

[Kris Wallsmith]

Thanks for proposing this, Benjamin. I think this is an excellent area for standardization. We are all in the business of HTTP, after all.

However, I think we should take a step back and start with interfaces for an HTTP request and an HTTP response. Once those are done, then we can move on to an HTTP client.

Kris (author of Buzz)

--

[Jordi Boggiano]

On 24.03.2012 17:19, Kris Wallsmith wrote:
> However, I think we should take a step back and start with interfaces
> for an HTTP request and an HTTP response. Once those are done, then we
> can move on to an HTTP client.

I realize this is a long shot, but in my dream world the Symfony
HttpFoundation classes for request/response would be made standard.
Their use in the framework & then adoption by Drupal, PPI (?) and
perhaps others make them a great candidate.

For those that don't know it:

https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpFoundation/Request.php
https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpFoundation/Response.php

The use of public properties for some things make them hard to be turned
into interfaces, but anyone can rely on that component and just use
those classes. I guess Composer adoption isn't broad enough for people
to agree with me that this is ok though.

Cheers

--
Jordi Boggiano
@seldaek - http://nelm.io/jordi

[Evert Pot]

On Mar 24, 2012, at 5:06 PM, Benjamin Eberlei wrote:

> See https://github.com/php-fig/fig-standards/pull/24
>
> From the introduction:
>
> Many libraries and applications require an HTTP client to talk to other servers. In general all these libraries either ship their own HTTP client library, or use low-level PHP functionality such as file_get_contents, ext/curl or the ext/socket. Depending on the use-cases there are very tricky implementation details to be handled such as proxies, SSL, authentication protocols and many more. Not every small library can afford to implement all the different details. However there are only a few http client libraries that are widely used between different projects, because of NIH or fears of vendor lock-in.
>
> Motivation:
>
> Doctrine has about 4 projects that need an HTTP client. Currently every projects implements them itself, which is annoying. We could abstract this into our "Common" library, however that would mean we would start being a "http client" vendor. Now personally, i don't care about http clients and would rather let others do this, however i also don't want to face vendor lock-in by deciding for any of the many http clients. In a perfect world (with this standard) Doctrine could ship one very simple http client using sockets, and if anyone needs something more awesome, he could just use any other provider of a PSR http client.
>
> Questions:
>
> 1. Do the voting members think this is something to standardize?

I personally feel that this group should focus on interface, not implementation.
There is definitely something amiss in the PHP world, where a lot of project have trouble depending on external components.

But introducing a new one, doesn't really solve that I feel. What we need is more people on board with composer.phar,
and have solid, minimal components that projects like doctrine feel comfortable with to add as a dependency.

I _do_ think there is a lot of value in a common request and response interface though. Not just for HTTP client, but
also to wrap $_SERVER, php://output, header(), etc..

If these 2 interfaces exist, it would also not be terribly hard to define a very simple interface for making requests.
After all, at that point all that's really required is a method that takes a Request object, and returns a Response object.

At that point all doctrine would have to do is to provide a way for users to inject the 'Client' interface.

I feel the end-result of your proposal is a nobel and useful one, but I have serious doubts this should be done through PSR.

Evert

[Lukas Kahwe Smith]

On Mar 24, 2012, at 12:35 , Evert Pot wrote:

> I personally feel that this group should focus on interface, not implementation.
> There is definitely something amiss in the PHP world, where a lot of project have trouble depending on external components.

agreed .. we might elect one implementation as a reference implementation, but more important is that we propose interfaces, a guideline for how to interpret these interfaces and a test suite to check for compliance.

regards,
Lukas Kahwe Smith
m...@pooteeweet.org

[Benjamin Eberlei]

Just realized i forgot cookies.

I am not sure if we need interfaces for request+response. These are value objects, and if simple and clean don't need interfaces IMHO.

The client needs.

[thom...@gmail.com]

Expand

Sent from my BlackBerry® wireless device

---

From: Benjamin Eberlei <kon...@beberlei.de>

Sender: php-st...@googlegroups.com

Date: Sat, 24 Mar 2012 18:26:17 +0100

To: <php-st...@googlegroups.com>

ReplyTo: php-st...@googlegroups.com

Subject: Re: A proposal for a HTTP Client

[Evert Pot]

On Mar 24, 2012, at 6:26 PM, Benjamin Eberlei wrote:

> Just realized i forgot cookies.

If you're taking this approach, you will find that you probably forgot a lot of HTTP features :)

If you want to keep things simple, I'd strongly suggest focusing on the following:

1. Request message
- http method
- url
- http version
- headers
- stream for body

2. Response message:
- http status code
- human-readable status
- http version
- headers
- stream for body

Keep in mind that multiple headers can be set with the same name, so a key-value list for
headers may not cover all the use cases.

Using these basic components, you can represent (as far as i know?) any http message.
Anything can be implemented with these components. Cookies would not be an issue, for instance.

Utility objects and classes could be used to aid constructing these headers and deliver them.

These guidelines as a basis, this would allow me:

1. To also wrap the request and response object in my current PHP process.
2. Create a custom client that's capable of asynchronous requests through libevent
3. Create a client that gives me multiple Response objects for every hop in a case of redirects, or a situation where HTTP/1.1 100 Continue is returned.

Your simple client may well be good enough for your use-cases, but in order for something like
this to be successful, it'd be important to create something that doesn't require people to
use other tools as soon as they need anything more complex.

Evert

[Lukas Kahwe Smith]

On Mar 24, 2012, at 13:59 , Evert Pot wrote:

> Your simple client may well be good enough for your use-cases, but in order for something like
> this to be successful, it'd be important to create something that doesn't require people to
> use other tools as soon as they need anything more complex.

why?

how is not covering the more complex cases going to be a reason to not adopt this for the simple cases?

[Evert Pot]

As a user needing a simple HTTP client, I agree.. no reason to use something more complex if you don't need to.
If you are a provider of an HTTP client (such as Symfony), I'm sure you would agree that you wouldn't want to provide an incomplete client.

Evert

[Benjamin Eberlei]

hm, maybe it makes more sense to focus on pecl_http getting a sane OOP api before it goes into PHP core and until then live with the HTTP client dilemma we have in userland?

[Lukas Kahwe Smith]

incomplete client? implementing in interface does not preclude you from adding other methods. so i dont see you issue at all.
and there can be other higher level standards that build on this simple interface.

[Evert Pot]

I'm referring to the proposal on github. My point was that it's too simple, and best to first focus on just the Request and Response messages before attempting to define the client.
The current proposal does not have a Request interface, but just a simple set of arguments for making requests.

Was there a miscommunication?

Evert

[Lukas Kahwe Smith]

Apparently so, since i understood you are saying that people wouldnt implement this interface, because its too simple.
Now as for Request/Response, I agree it would be great to also standardize these, but its going to be much harder and the discussion can run in parallel.

As for Benjamin's comment about pecl http: I totally agree that its a good idea to bring Michael into this discussion (actually one of the first things I did after the PR was opened was to ping him on IRC). That being said, we are discussing interfaces here and only implementations in so far as to ensure that the interfaces make sense once they are implemented. Furthermore if possible it is of course also nice to ensure compatibility with existing libs, but as there are already so many, the risk is high that it will just alienate the authors of the given libs if we pick a "favorite".

[Michael Dowling]

As the creator of Guzzle (https://github.com/guzzle/guzzle), I'm very interested in this proposal.  I've added several comments to the PR, which I'd be happy to discuss here or on github.  Quick rundown of my comments:

• Why return an array for headers that have only one value?  Why not return an array only when there are multiple headers of the same name (this is basically what Guzzle does)?
  
• HttpException should probably be an interface so that it's easier to plug into existing projects.
• I'd like to see $headers move before $content in the arguments of HttpClient::request()
• Should $content in HttpClient::request() accept an array or string?  An array would allow you to easily send form style POST requests.  I'm fine with just expecting a string to be passed to this method, but I want to see what others think.
  
• I think that the $options array needs to have a standardized array of options or should be removed from HttpClient::request().  Allowing HTTP client vendors to specify their own custom options would still cause vendor lock-in or abstraction code to be present in consumers of these clients.
  
• As I think most clients will offer adapters instead of changing their interfaces, would it make sense to add a method to the HttpClient that would allow access to the more advanced adapted HTTP client (e.g. getAdaptedClient())?  I don't think it's a good idea to change the interfaces of Guzzle to support a much simpler HTTP client, so I'm probably going to offer an adapter.

The impetus for this proposal stems from the fact that several Doctrine projects need an HTTP client.  With the currently proposed interfaces and lack of a Request interface, you will not be able to send HTTP requests in parallel, which is something I'm thinking Doctrine would benefit from greatly.  For example, when working with unit of work pattern, you often need to do several actions when flush is called (delete things, update things, add things).  Without the use of parallel requests, you'll need to do all of these requests serially.  The way that this is handled in Guzzle is by using a client object as a sort of builder that returns requests.  These requests can then be sent one at a time or in parallel by calling the ``send`` method of the client and passing an array of requests (http://guzzlephp.org/tour/http.html#send-http-requests-in-parallel).

hm, maybe it makes more sense to focus on pecl_http getting a sane OOP api before it goes into PHP core and until then live with the HTTP client dilemma we have in userland?

While that would be awesome, I don't think it's feasible to wait on pecl_http to be updated or put into PHP's core for you or others to release new libraries.  It didn't make it into PHP 5.4, so you'd require your users to install the pecl extension or wait on PHP next.

I think this proposal could work as long as we're realistic-- provide only an interface and not an implementation, limit the scope as much as possible, and expect existing libraries to provide adapters if the proposed PSR interface differs from the original client's interface.

Thanks,
Michael

On Saturday, March 24, 2012 1:11:32 PM UTC-5, Benjamin Eberlei wrote:

hm, maybe it makes more sense to focus on pecl_http getting a sane OOP api before it goes into PHP core and until then live with the HTTP client dilemma we have in userland?

On Sat, Mar 24, 2012 at 7:01 PM, Lukas Kahwe Smith <m...@pooteeweet.org> wrote:

On Mar 24, 2012, at 13:59 , Evert Pot wrote:

> Your simple client may well be good enough for your use-cases, but in order for something like
> this to be successful, it'd be important to create something that doesn't require people to
> use other tools as soon as they need anything more complex.

why?

how is not covering the more complex cases going to be a reason to not adopt this for the simple cases?

regards,
Lukas Kahwe Smith
m...@pooteeweet.org

--
You received this message because you are subscribed to the Google Groups "PHP Standards Working Group" group.
To post to this group, send email to php-st...@googlegroups.com​.

To unsubscribe from this group, send email to php-standards+unsubscribe@​googlegroups.com.

[Benjamin Eberlei]

i disagree on pecl/http. If it ships with a sane API that does not require wrapping, then developing a PHP clone of this NOW is much better task for all our limited time than trying to find a standard to wrap pecl/http into.

I agree on your points though, the API was a long shot and i already want to remove request in its own object, that way we dont have to argue about order in the request() method.

To view this discussion on the web visit https://groups.google.com/d/msg/php-standards/-/uTPxNJwxz0QJ.

To post to this group, send email to php-st...@googlegroups.com.

To unsubscribe from this group, send email to php-standard...@googlegroups.com.

[Michael Dowling]

I think it would be great for pecl/http to be updated, and I'd consider using it in Guzzle instead of curl (as long as it has the same callback support that curl provides).  However, providing a new interface for pecl/http and implementing a PHP only version is just reinventing the wheel on top of many existing wheels (Guzzle, Buzz, Zend HTTP client, PEAR, etc).

I like the concept of introducing a simple set of interfaces for libraries that need a simple HTTP client.  I don't think the PSR group getting into the business of providing implementations is a good idea though (maybe I misunderstood though).

-Michael

[Paul M Jones]

Hi all,

To suggest a course of action that appears to have been fruitful with PSR-1: Compile a list of known HTTP request/response/client libraries, examine them for commonalities, publish the results, and go from there.

Guzzle, Buzz, ZF, Solar (and soon Aura), Symfony, Lithium, Cake, PECL HTTP, etc. all have HTTP request/response classes. They'd be the likely targets for research.

That way at least we have an idea of what people are *actually* doing, and not be limited to our own ideas of what we *think* people *ought* to be doing.

--

Paul M. Jones
http://paul-m-jones.com/

[Evert Pot]

If we feel it helps, I can ask someone from the httpbis group to provide input too.
We should be a bit further ourselves though :)

Evert

[Alexandre Gaigalas]

We should also look how the PHP native HTTP stream wrapper works. After researching a lot of clients I've settled on stream_get_contents() for the body + stream_get_metadata() for the response headers and stream_context_create() for the request declaration, even though they don't have an OOP interface.

ref: http://www.php.net/manual/en/context.http.php

A thin OOP layer based on these functions would make more sense to me than any other. A reference implementation would also be very easy to set up without relying on any specific vendors.

If we keep up this proposal, I believe we should also add to the compiled list of clients how they handle HTTP-specific workflows. Not all clients nowadays are able to handle transfer encodings, protocol upgrades, cookie persistence, file uploads, keep alives and many other core HTTP features.

Maybe the clean request() method should even be clear about *not* treat all those workflows, to keep things uniform without having to implement a large subset of the spec. If we consider another RFCs besides 2616 there is a *lot* of things to specify. Subsequent revisions of this possible PSR should address more complex workflows as clients adopt the basic interface.

From the spec point of view, there is no valid Request without a Response and vice-versa. Browser-to-server implementations tend to separate these concepts mainly because of their "phisical" separation, but as an HTTP client self-contained this seems to be unecessary. The Request/Response pair is defined by the spec as an HTTP Message, and makes a lot of sense to me that a client could need only a Message interface to be clean and consistent.

--
You received this message because you are subscribed to the Google Groups "PHP Standards Working Group" group.

To post to this group, send email to php-st...@googlegroups.com.

To unsubscribe from this group, send email to php-standard...@googlegroups.com.

[Alexandre Gaigalas]

Oops. Small correction: The spec defines an HTTP Message as an abstract format for Request and Response formats. They differ mainly on the request/status line and the related workflows.

[Suissa]

I agree.

2012/3/25 Alexandre Gaigalas <alex...@gaigalas.net>

--
Jean C. Nascimento aka Suissa
WebDeveloper Sênior - SP

http://about.me/suissa

      

[Beau Simensen]

2. API: I didn't include a Request object as i think its not really necessary. The proposal is expclicitly very simple.

Could we define standard HTTP Request and Response interfaces (and an HTTP Client that is just a pass-thru for Request -> Response) in one PSR and define a Simple Client that leverages the HTTP Response from the other PSR?

/* PSR-HTTP-Client */

use Whizbang\Client as PsrClient; // implements PsrClientInterface

use Whizbang\Request as PsrRequest; // implements PsrRequestInterface

$psrClient = new PsrClient;

$psrRequest = new PsrRequest();

(PsrResponseInterface) $psrResponse = $psrClient->makeRequest($psrRequest);

/* PSR-HTTP-SimpleClient */

use Whizbang\SimpleClient as PsrSimpleClient; // implements PsrSimpleClientInterface

$psrSimpleClient = new PsrSimpleClient;

(PsrResponseInterface) $psrReponse = $psrSimpleClient->makeSimpleRequest(/* specialized set of simple arguments */);

If so, vendors would be able to opt supporting either PSR-HTTP-Client or PSR-HTTP-SimpleClient (or both). Users would be able to decide which route they would need to go down for their particular application.

[Beau Simensen]

Should the http client be bound to a host? so that $url is not containing a host? Or should the client wiggle this itself?

I think this would only be useful under very specific circumstances. In general I don't want to have to worry about the URL I am accessing being the same host as the last URL I accessed.

Being able to support this might be a good case for having a Request interface, though? It would provide flexibility to handle this kind of thing in the application's logic as opposed to offloading it to the HTTP Client magic.

    $apiRequestFactory = new MyApiRequestFactory('http://example.com/api/baseUrl');

    $psrResponse = $psrClient->makeRequest($apiRequestFactory->createPost('category/programming/tag/php'));

    $psrResponse = $psrClient->makeRequest($apiRequestFactory->createGet('products'));

    $psrResponse = $psrClient->makeRequest(new Request('GET', $product->getFavoritesUrl()));

It would be pretty trivial to provide a set of custom Request types and Request factories (GetRequest($url,...) , PostRequest($url,...), RestResourceRequestFactory($baseUrl)) as references. I'm not sure if they should be a part of the PSR, but it might not be a terrible idea.

[Beau Simensen]

Does anyone else think this might be a good approach? If so I'd like to try and get the ball moving on this one again.

[Alexandre Gaigalas]

I like it. Let me know if I get things right:

The final product of this recommendation would be a set of interfaces that compliant HTTP clients written in PHP must conform to. Some of them are optional based on the features that the client provides, so we can also use these interfaces to check if a specific client is compliant to something.

Right so far? Where do we go from here?

--

You received this message because you are subscribed to the Google Groups "PHP Standards Working Group" group.

To view this discussion on the web visit https://groups.google.com/d/msg/php-standards/-/CWSymx3hW2wJ.

[Norv N.]

I think it's a good approach. Request and Response interfaces are expected and necessary. FWIW, I rather see a good standard proposal as one that covers first the essential interfaces of the domain.

The HTTP client interface can be defined in parallel or after these are established.

[Dowling, Michael]

Assuming this proposal comes to fruition, what's the expectation on existing HTTP clients?  Are users expecting breaking changes, adapters, or something else?

-Michael

From: "Norv N." <no...@simplemachines.org>
Reply-To: <php-st...@googlegroups.com>
Date: Thu, 7 Jun 2012 07:08:08 -0700 (PDT)
To: <php-st...@googlegroups.com>
Subject: Re: A proposal for a HTTP Client

--

You received this message because you are subscribed to the Google Groups "PHP Standards Working Group" group.

To view this discussion on the web visit https://groups.google.com/d/msg/php-standards/-/W4twfs1ovXIJ.

[Beau Simensen]

On Thursday, June 7, 2012 12:10:39 PM UTC-5, Michael Dowling wrote:

Assuming this proposal comes to fruition, what's the expectation on existing HTTP clients?  Are users expecting breaking changes, adapters, or something else?

I think that my expectation is that existing HTTP clients would not need to be changed. That is my expectation for the Cache proposals as well. New implementations would be welcome to implement the proposals directly but existing vendors can provide support for the interfaces by whatever means necessary. If that means BC breaks for their users, that is up to them.

People create different implementations for different reasons and people choose those implementations based on the differences. Cache and HTTP clients can be very specialized and a user can choose one that meets their specialized needs if they have specialized needs. I think it is important to not get in the way of the vendors in this case.

On the other hand, applications or libraries that just needs "a cache" or "an HTTP client" may not care about the details or specifics and can be written instead to accept a PSR cache or HTTP client implementation. A framework can be configured to use Buzz or Guzzle or XYZ as its "PSR HTTP client" and generic libraries and objects can consume it by way of dependency injection. Specialized domain objects can instead accept the actual implementation by way of dependency injection where access to functionality that isn't available by the PSR HTTP client is required.

[Kris Wallsmith]

I do not agree with the Client/SimpleClient distinction. I've designed Buzz so the only thing a client needs to worry about is executing an HTTP request and populating the response. Since you pass the response object to the client, it isn't even expected to create that object.

interface ClientInterface

{

    function send(RequestInterface $request, MessageInterface $response);

}

If you want an easier interface you can wrap one around a client. In Buzz this is called a browser and has nice methods like…

public function get($url, $headers = array())

public function post($url, $headers = array(), $content = '')

public function call($url, $method, $headers = array(), $content = '')

public function submit($url, array $fields, $method = RequestInterface::METHOD_POST, $headers = array())

public function send(RequestInterface $request, MessageInterface $response = null)

It is important that these are two separate concepts.

However, I still think we should focus our current efforts on defining request and response interfaces. I've included Buzz's here for discussion…

interface MessageInterface

{

    function getHeader($name, $glue = "\r\n");

    function getHeaders();

    function setHeaders(array $headers);

    function addHeader($header);

    function getContent();

    function setContent($content);

}

interface RequestInterface extends MessageInterface

{

    const METHOD_OPTIONS = 'OPTIONS';

    const METHOD_GET     = 'GET';

    const METHOD_HEAD    = 'HEAD';

    const METHOD_POST    = 'POST';

    const METHOD_PUT     = 'PUT';

    const METHOD_DELETE  = 'DELETE';

    const METHOD_PATCH   = 'PATCH';

    function getMethod();

    function setMethod($method);

    function getResource();

    function setResource($resource);

    function getProtocolVersion();

    function getHost();

    function setHost($host);

    function isSecure();

}

Thanks,

Kris

[Beau Simensen]

On Thursday, June 7, 2012 12:54:47 PM UTC-5, Kris Wallsmith wrote:

interface ClientInterface
{
    function send(RequestInterface $request, MessageInterface $response);
}

What are the benefits to passing in a $response vs having the object create it?

I do not agree with the Client/SimpleClient distinction.

What part do you disagree with? That there would be a SimpleClient at all?

Here is what I currently have in mind. I think that Client would be similar to Buzz Client interface and SimpleClient would be similar to Buzz Browser. Maybe it is the naming that is a bit off?

PSR-HTTP-Client:

namespace Fig\Psr\HttpClient;

interface RequestInterface
{
    /* TBD */
}

interface ResponseInterface
{
    /* TBD */
}

interface ClientInterface
{
    /**
     * @return ResponseInterface
     */
    public function send(RequestInterface $request);
}

PSR-HTTP-SimpleClient (which would attempt to address Benjamin's "very simple HTTP client" use case leveraging the ResponseInterface from PSR-HTTP-Client):

namespace Fig\Psr\SimpleHttpClient;

interface SimpleClientInterface
{
    /**
     * @return \Fig\Psr\HttpClient\ResponseInterface
     */
    public function request($method, $url, array $headers = array(), $content = null, array $options = array());
}

Lots of options here (should they actually be in separate PSR from each other? do they need to be in separate classes or can send and request live together? should we have request at all?), but I see these as the building blocks to try and flesh out.

[Dowling, Michael]

I think we should work to create fairly generic interfaces that make no assumptions about the implementation details of an HTTP client vendor.  I think we should strive to ensure that a PSR HTTP client consumer knows that when it is dealing with a client, request, or response object that the object's dependencies are already associated with the object.  The long and short: a request represents a request, a response a response, and a client sends the requests and creates a response.  A consumer shouldn't have to care how any of this is done.

I don't see the need for a distinction between browsers and clients when we're talking about a PSR HTTP client.  I agree with what Beau said earlier: these HTTP client interfaces should be used to support dependency injection so that other libraries can utilize them in a generic way.  I don't think that a PSR should concern itself with the way in which a client is built or instantiated, a request is instantiated, what request or response factories it uses, or the specific way in which a client transfers data over the wire. I would rather not separate the transport layer from the client (aka browser in Kris's example).

If a client interface contained a createRequest() method or something similar, then the way in which a request is created could be irrelevant to a PSR consumer.  The underlying implementation is free to implement the the "createRequest()" method however deemed necessary -- implement factories, builders, or whatever.  However, these implementation details should not creep into a PSR.

Some parts of the interfaces Kris posted are pretty similar to Guzzle, so I think we've got a good spring board here for discussion.  (note: Guzzle's interfaces are a bit larger, but most of the differences are library requirement details specific to Guzzle).  Speaking purely in the context of a PSR proposal, here's some feedback that I think would would mold these interfaces into a more generic PSR:

1. I would not want to include "setMethod($method)" in a PSR request interface.  This makes implementation assumptions and is something that could be handled in a createRequest() method of a client.  Guzzle uses a RequestInterface for GET, HEAD, DELETE, etc; and an EntityEnclosingRequestInterface for PUT, POST, PATCH, etc.
2. Just brainstorming, but could the "isSecure()" method be replaced by a more generic "getScheme()" method that returned "http", "https", etc?
3. I think a PSR client should deal with headers using keys and values rather than passing the full HTTP header line.  So getHeader($header), setHeader($header, $value), addHeader($header, $value), getHeaders(), setHeaders($headers),  etc.
4. I think we should be clear that headers should be specific to HTTP headers and not affect the start line of an HTTP message (examples of start lines are "GET / HTTP/1.1" for requests and "HTTP/1.1 200 OK" for responses).  Allowing headers to change things like the request method is an implementation assumption that a HTTP vendor uses the same request classes for each type of method.
5. Guzzle uses "addHeader($header, $value)" to add a header to a message.  If a header already exists, then the new value is appended to the existing header. If the header does not exist, then the value is added.  "setHeader($key, $value)" is used to add a header to a message and replace any existing headers by that name. Everything is handled case-insensitively.
6. I think there should be a proper response interface that has methods like getStatusCode() and getReasonPhrase().  Both Guzzle and Buzz use these same method names.
7. Can/should a PSR interface account for the ability to send HTTP requests in parallel?

-Michael

From: Beau Simensen <sime...@gmail.com>
Reply-To: <php-st...@googlegroups.com>
Date: Thu, 7 Jun 2012 12:43:29 -0700 (PDT)
To: <php-st...@googlegroups.com>
Subject: Re: A proposal for a HTTP Client

--

You received this message because you are subscribed to the Google Groups "PHP Standards Working Group" group.

To view this discussion on the web visit https://groups.google.com/d/msg/php-standards/-/1y22NG25EVgJ.

[Paul M. Jones]

On Jun 7, 2012, at 2:43 PM, Beau Simensen wrote:

> On Thursday, June 7, 2012 12:54:47 PM UTC-5, Kris Wallsmith wrote:
>> interface ClientInterface
>> {
>> function send(RequestInterface $request, MessageInterface $response);
>> }
>>
> What are the benefits to passing in a $response vs having the object create it?

The benefits are subtle, sophisticated, and not immediately obvious. For one, you can pass in a mock response object at testing time. (While this is not strictly "dependency injection," it is similar.)



-- pmj

[Dowling, Michael]

We would be providing an interface. Couldn't someone just implement a
mock client that returns a mock response?

This seems like an implementation detail to me. I think our PSR's should
be a black box.

-Michael

>--
>You received this message because you are subscribed to the Google Groups
>"PHP Standards Working Group" group.

[Devon H. O'Dell]

Has anybody taken a look at the Go HTTP client interface[1]? I've used
it with much success and it has been a pleasure to work with. I think
modeling an interface after net/http would work well; I think it's at
least worth considering adopting ideas from an existing, successful
interface instead of trying to invent something entirely from the
ground up.

--dho

[1]: http://golang.org/pkg/net/http/#Client

2012/6/7 Dowling, Michael <mtdo...@gmail.com>:

[Kris Wallsmith]

Hi Michael,

Thank you for your response. I look forward to discussing this with you.

On Thursday, June 7, 2012 12:44:19 PM UTC-7, Michael Dowling wrote:

I think we should work to create fairly generic interfaces that make no assumptions about the implementation details of an HTTP client vendor.  I think we should strive to ensure that a PSR HTTP client consumer knows that when it is dealing with a client, request, or response object that the object's dependencies are already associated with the object.  The long and short: a request represents a request, a response a response, and a client sends the requests and creates a response.  A consumer shouldn't have to care how any of this is done.

I agree with you 99% here except for the "client […] creates a response" bit.

I don't see the need for a distinction between browsers and clients when we're talking about a PSR HTTP client.  I agree with what Beau said earlier: these HTTP client interfaces should be used to support dependency injection so that other libraries can utilize them in a generic way.  I don't think that a PSR should concern itself with the way in which a client is built or instantiated, a request is instantiated, what request or response factories it uses, or the specific way in which a client transfers data over the wire. I would rather not separate the transport layer from the client (aka browser in Kris's example).

Why would you "rather not separate the transport layer from the client"? Buzz's client classes have a very specific responsibility: executing a request and populating a response. The client gets involved just-in-time and finishes as-soon-as-possible. The methods in Buzz's browser class are just sugar on top of an injected client.

If a client interface contained a createRequest() method or something similar, then the way in which a request is created could be irrelevant to a PSR consumer.  The underlying implementation is free to implement the the "createRequest()" method however deemed necessary -- implement factories, builders, or whatever.  However, these implementation details should not creep into a PSR.

I do not think the PSR should concern itself with how message objects are created.

Some parts of the interfaces Kris posted are pretty similar to Guzzle, so I think we've got a good spring board here for discussion.  (note: Guzzle's interfaces are a bit larger, but most of the differences are library requirement details specific to Guzzle).  Speaking purely in the context of a PSR proposal, here's some feedback that I think would would mold these interfaces into a more generic PSR:

1. I would not want to include "setMethod($method)" in a PSR request interface.  This makes implementation assumptions and is something that could be handled in a createRequest() method of a client.  Guzzle uses a RequestInterface for GET, HEAD, DELETE, etc; and an EntityEnclosingRequestInterface for PUT, POST, PATCH, etc.

If setMethod() is not included, how do you set the method?

1. Just brainstorming, but could the "isSecure()" method be replaced by a more generic "getScheme()" method that returned "http", "https", etc?

I've included this method in the Buzz interface so a cookie jar can determine whether to apply secure cookies to a particular request. 

1. I think a PSR client should deal with headers using keys and values rather than passing the full HTTP header line.  So getHeader($header), setHeader($header, $value), addHeader($header, $value), getHeaders(), setHeaders($headers),  etc.

This is the main issue to be resolved before proposing request and response interfaces. I've designed Buzz to store header lines in a list in order to maintain the true order of headers. Maybe this is not important?

1. I think we should be clear that headers should be specific to HTTP headers and not affect the start line of an HTTP message (examples of start lines are "GET / HTTP/1.1" for requests and "HTTP/1.1 200 OK" for responses).  Allowing headers to change things like the request method is an implementation assumption that a HTTP vendor uses the same request classes for each type of method.

That's a good point. I see now that the HTTP spec distinguishes between the request line and headers.

Thanks! 

Kris

To unsubscribe from this group, send email to php-standards+unsubscribe@googlegroups.com.

[Kris Wallsmith]

Hi Beau,

Responses inline…

On Thursday, June 7, 2012 12:43:29 PM UTC-7, Beau Simensen wrote:

On Thursday, June 7, 2012 12:54:47 PM UTC-5, Kris Wallsmith wrote:

interface ClientInterface
{
    function send(RequestInterface $request, MessageInterface $response);
}

What are the benefits to passing in a $response vs having the object create it?

 

If you have many clients (i.e. cURL, stream, xyz…) you would be duplicating code to create a new response object in each one. You could abstract this out into a factory, but then you would be injecting the factory into each client. It's simpler to just expect the response object to be created upstream somewhere and only expect the client to populate it.

I do not agree with the Client/SimpleClient distinction.

What part do you disagree with? That there would be a SimpleClient at all?

Here is what I currently have in mind. I think that Client would be similar to Buzz Client interface and SimpleClient would be similar to Buzz Browser. Maybe it is the naming that is a bit off?

PSR-HTTP-Client:

namespace Fig\Psr\HttpClient;

interface RequestInterface
{
    /* TBD */
}

interface ResponseInterface
{
    /* TBD */
}

interface ClientInterface
{
    /**
     * @return ResponseInterface
     */
    public function send(RequestInterface $request);
}

PSR-HTTP-SimpleClient (which would attempt to address Benjamin's "very simple HTTP client" use case leveraging the ResponseInterface from PSR-HTTP-Client):

namespace Fig\Psr\SimpleHttpClient;

interface SimpleClientInterface
{
    /**
     * @return \Fig\Psr\HttpClient\ResponseInterface
     */
    public function request($method, $url, array $headers = array(), $content = null, array $options = array());
}

Lots of options here (should they actually be in separate PSR from each other? do they need to be in separate classes or can send and request live together? should we have request at all?), but I see these as the building blocks to try and flesh out.

Having two client interfaces means a vendor needs to implement them both to be compatible? Providing two interfaces that accomplish the same functionality is unnecessarily confusing.

Thanks,

Kris

[Dowling, Michael]

Hi Kris,

> I agree with you 99% here except for the "client […] creates a response" bit.

The reason I say this is because I think a PSR client consumer should not be concerned with how a request or response is created. So, how can we achieve that?  We could go nuts and write up interfaces for request factories, but I think that's overkill.  We can't and should not specify the constructors of the request or response objects either.  An alternative would be to have a method on a client used to create and return a request.  Further, the client could execute the request and return a response interface object when a request is sent.

To address your concerns of single responsibility, when implementing the PSR interface, your client object could  internally delegate to a factory used for creating requests and responses.  All of these implementation details would be internal to your implementation and should not concern the consumer of the PSR client.

> Why would you "rather not separate the transport layer from the client"? Buzz's client classes have a very specific responsibility: executing a request and populating a response. The client gets involved just-in-time and finishes as-soon-as-possible. The methods in Buzz's browser class are just sugar on top of an injected client.

I think that works great for Buzz, but the transport of a client is an implementation detail of the client.  Why should we put implementation details into a PSR interface?  A PSR client consumer should not have to care at all how a request is being transferred over the wire, much like they shouldn't have to care if they're using Guzzle, Buzz, ZF, etc.  I think that's the whole point of this PSR.

So, to clarify and use Buzz as an example:

Someone makes a library that requires a PSR client and expects a client to be injected somewhere in their library.  Developer X wants to use Buzz, and Buzz supports different transports.  They would build the Buzz client using whatever transport they want, inject the client into the browser, then pass the browser or some other object implementing the PSR interface into the library that requires the client.  The client doesn't need to know anything other than the capabilities of the client, request, and responses.

> I do not think the PSR should concern itself with how message objects are created.

Agreed.

> If setMethod() is not included, how do you set the method?

In the constructor of a request object.  If we add something like a ``createRequest($method, …blah)`` method, then a PSR client consumer can create requests as needed.  Providing a way to create new request objects in this manner also allows for PSR specifications on sending requests in parallel (i.e. you grab 10 requests objects the send them at the same time using the client).

> I've included this method in the Buzz interface so a cookie jar can determine whether to apply secure cookies to a particular request.

Gotcha.  In the context of a PSR, could someone just say ``if ($request->getScheme() == 'https')``?  I'm fine with isSecure(), but a ``getScheme()`` method is still a good idea I think.  Simply sending request to port 443 does not automatically mean you'll use SSL encryption, whereas the scheme can tell you if the request should be sent using SSL.  It also helps creating URLs from a request object.

> I've designed Buzz to store header lines in a list in order to maintain the true order of headers. Maybe this is not important?

I have not seen a case where the order of HTTP headers is important, but there might be edge cases.  If this was truly a requirement, I think it could be implemented in other ways, so I think it's an implementation detail.

The only requirement I've seen is preserving the exact casing of headers.  That sucks because HTTP says headers should be case insensitive, but unfortunately, some servers require headers in a specific case.  I was able to handle this in Guzzle correctly, and it looks like what you've done would work for that as well.

Thanks,

Michael

To view this discussion on the web visit https://groups.google.com/d/msg/php-standards/-/Vhl2ZqaqNJIJ.

To post to this group, send email to php-st...@googlegroups.com.

To unsubscribe from this group, send email to php-standard...@googlegroups.com.

[Beau Simensen]

Hi Kris,

Having two client interfaces means a vendor needs to implement them both to be compatible? Providing two interfaces that accomplish the same functionality is unnecessarily confusing.

That is why I first suggested the idea that there be two PSR's. By having both, a vendor could choose to be compatibile either with PSR-HTTP-Client, PSR-HTTP-SimpleClient, or both. Similar to PSR-1 and PSR-2...

The interfaces do accomplish the same functionality but in very different ways. I think that the focus should be on PSR-HTTP-Client and once that is squared away we can decide on trying to push something like Benjamin's initial proposal based on PSR-HTTP-Client's Response (what I refer to as PSR-HTTP-SimpleClient). It is possible that proposal will never get approval but I want to make sure it isn't ruled out at this point.

If it makes things easier to discuss I can stop talking about that as an option for the time being. :)

[Kris Wallsmith]

Hi Michael!

On Thursday, June 7, 2012 2:53:49 PM UTC-7, Michael Dowling wrote:

Hi Kris,

> I agree with you 99% here except for the "client […] creates a response" bit.

The reason I say this is because I think a PSR client consumer should not be concerned with how a request or response is created.

Ah, so we disagree here. I think we should encourage consumers to create and work with request objects. The client convenience methods are nice, but they conceal too much.

 

So, how can we achieve that?  We could go nuts and write up interfaces for request factories, but I think that's overkill.  We can't and should not specify the constructors of the request or response objects either.  An alternative would be to have a method on a client used to create and return a request.  Further, the client could execute the request and return a response interface object when a request is sent.

To address your concerns of single responsibility, when implementing the PSR interface, your client object could  internally delegate to a factory used for creating requests and responses.  All of these implementation details would be internal to your implementation and should not concern the consumer of the PSR client.

I'm willing to go either way on this point. Does anyone else have an opinion?

> Why would you "rather not separate the transport layer from the client"? Buzz's client classes have a very specific responsibility: executing a request and populating a response. The client gets involved just-in-time and finishes as-soon-as-possible. The methods in Buzz's browser class are just sugar on top of an injected client.

I think that works great for Buzz, but the transport of a client is an implementation detail of the client.  Why should we put implementation details into a PSR interface?  A PSR client consumer should not have to care at all how a request is being transferred over the wire, much like they shouldn't have to care if they're using Guzzle, Buzz, ZF, etc.  I think that's the whole point of this PSR.

So, to clarify and use Buzz as an example:

Someone makes a library that requires a PSR client and expects a client to be injected somewhere in their library.  Developer X wants to use Buzz, and Buzz supports different transports.  They would build the Buzz client using whatever transport they want, inject the client into the browser, then pass the browser or some other object implementing the PSR interface into the library that requires the client.  The client doesn't need to know anything other than the capabilities of the client, request, and responses.

> I do not think the PSR should concern itself with how message objects are created.

Agreed.

> If setMethod() is not included, how do you set the method?

In the constructor of a request object.  If we add something like a ``createRequest($method, …blah)`` method, then a PSR client consumer can create requests as needed.  Providing a way to create new request objects in this manner also allows for PSR specifications on sending requests in parallel (i.e. you grab 10 requests objects the send them at the same time using the client).

> I've included this method in the Buzz interface so a cookie jar can determine whether to apply secure cookies to a particular request.

Gotcha.  In the context of a PSR, could someone just say ``if ($request->getScheme() == 'https')``?  I'm fine with isSecure(), but a ``getScheme()`` method is still a good idea I think.  Simply sending request to port 443 does not automatically mean you'll use SSL encryption, whereas the scheme can tell you if the request should be sent using SSL.  It also helps creating URLs from a request object.

The cookie specification does not mention a specific scheme, only that the client "secure means to contact the origin server."

> I've designed Buzz to store header lines in a list in order to maintain the true order of headers. Maybe this is not important?

I have not seen a case where the order of HTTP headers is important, but there might be edge cases.  If this was truly a requirement, I think it could be implemented in other ways, so I think it's an implementation detail.

I agree that this is an implementation detail. The question for this discussion is what method should be included in the message interface for working with headers. This is probably a topic that deserves its own thread.

Thanks,

Kris

The only requirement I've seen is preserving the exact casing of headers.  That sucks because HTTP says headers should be case insensitive, but unfortunately, some servers require headers in a specific case.  I was able to handle this in Guzzle correctly, and it looks like what you've done would work for that as well.

Thanks,

Michael

Reply-To: <php-standards@googlegroups.com>

Date: Thu, 7 Jun 2012 14:08:33 -0700 (PDT)

To: <php-standards@googlegroups.com>
Subject: Re: A proposal for a HTTP Client

Hi Michael,

Thank you for your response. I look forward to discussing this with you.

On Thursday, June 7, 2012 12:44:19 PM UTC-7, Michael Dowling wrote:

I think we should work to create fairly generic interfaces that make no assumptions about the implementation details of an HTTP client vendor.  I think we should strive to ensure that a PSR HTTP client consumer knows that when it is dealing with a client, request, or response object that the object's dependencies are already associated with the object.  The long and short: a request represents a request, a response a response, and a client sends the requests and creates a response.  A consumer shouldn't have to care how any of this is done.

I agree with you 99% here except for the "client […] creates a response" bit.

I don't see the need for a distinction between browsers and clients when we're talking about a PSR HTTP client.  I agree with what Beau said earlier: these HTTP client interfaces should be used to support dependency injection so that other libraries can utilize them in a generic way.  I don't think that a PSR should concern itself with the way in which a client is built or instantiated, a request is instantiated, what request or response factories it uses, or the specific way in which a client transfers data over the wire. I would rather not separate the transport layer from the client (aka browser in Kris's example).

Why would you "rather not separate the transport layer from the client"? Buzz's client classes have a very specific responsibility: executing a request and populating a response. The client gets involved just-in-time and finishes as-soon-as-possible. The methods in Buzz's browser class are just sugar on top of an injected client.

If a client interface contained a createRequest() method or something similar, then the way in which a request is created could be irrelevant to a PSR consumer.  The underlying implementation is free to implement the the "createRequest()" method however deemed necessary -- implement factories, builders, or whatever.  However, these implementation details should not creep into a PSR.

I do not think the PSR should concern itself with how message objects are created.

Some parts of the interfaces Kris posted are pretty similar to Guzzle, so I think we've got a good spring board here for discussion.  (note: Guzzle's interfaces are a bit larger, but most of the differences are library requirement details specific to Guzzle).  Speaking purely in the context of a PSR proposal, here's some feedback that I think would would mold these interfaces into a more generic PSR:

1. I would not want to include "setMethod($method)" in a PSR request interface.  This makes implementation assumptions and is something that could be handled in a createRequest() method of a client.  Guzzle uses a RequestInterface for GET, HEAD, DELETE, etc; and an EntityEnclosingRequestInterface for PUT, POST, PATCH, etc.

If setMethod() is not included, how do you set the method?

1. Just brainstorming, but could the "isSecure()" method be replaced by a more generic "getScheme()" method that returned "http", "https", etc?

I've included this method in the Buzz interface so a cookie jar can determine whether to apply secure cookies to a particular request. 

1. I think a PSR client should deal with headers using keys and values rather than passing the full HTTP header line.  So getHeader($header), setHeader($header, $value), addHeader($header, $value), getHeaders(), setHeaders($headers),  etc.

This is the main issue to be resolved before proposing request and response interfaces. I've designed Buzz to store header lines in a list in order to maintain the true order of headers. Maybe this is not important?

1. I think we should be clear that headers should be specific to HTTP headers and not affect the start line of an HTTP message (examples of start lines are "GET / HTTP/1.1" for requests and "HTTP/1.1 200 OK" for responses).  Allowing headers to change things like the request method is an implementation assumption that a HTTP vendor uses the same request classes for each type of method.

That's a good point. I see now that the HTTP spec distinguishes between the request line and headers.

Thanks! 

Kris

1. Guzzle uses "addHeader($header, $value)" to add a header to a message.  If a header already exists, then the new value is appended to the existing header. If the header does not exist, then the value is added.  "setHeader($key, $value)" is used to add a header to a message and replace any existing headers by that name. Everything is handled case-insensitively.
2. I think there should be a proper response interface that has methods like getStatusCode() and getReasonPhrase().  Both Guzzle and Buzz use these same method names.
3. Can/should a PSR interface account for the ability to send HTTP requests in parallel?

-Michael

[Dowling, Michael]

> I think we should encourage consumers to create and work with request objects. 

Agreed!  However, I don't want to dictate the constructors of anything in our interfaces.  So that means we need either a separate factory interface or you can treat the createRequest() method on a client as a factory method that can delegate the responsibility of creating a request however it makes sense for that particular vendor. The latter would be a pretty lightweight approach to the problem, whereas providing something like a RequestFactoryInterface would be a more imposing PSR proposal.

I'm open to suggestions on this from others as well.

> The client convenience methods are nice, but they conceal too much.

I don't see that as a bad thing.  I see that as the point of an interface, and I think we should strive to conceal implementation details as much as possible.

We should not be designing a framework with this PSR, and we need to use the interfaces of particular framework implementations with a grain of salt.  The interfaces used by specific vendors have their own separate goals that might not make sense for a PSR.  The goal of HTTP client PSR should be to provide simple interfaces so that we can easily connect components together.  That's why I'm advocating this methodology.

> The cookie specification does not mention a specific scheme, only that the client "secure means to contact the origin server."

To clarify, I wasn't talking about cookies, but rather having a getScheme() method on a request interface.  So in the interfaces you provided, isSecure() tells you whether or not the request is being sent using SSL, right?  Providing a getScheme() method provides that same information, but in a more generic way, and allows you to build a URL string from a request object.  Maybe there's room for both of these methods on a request interface?

Anyone else have opinions on this stuff?

-Michael

From: Kris Wallsmith <kris.wa...@gmail.com>
Reply-To: <php-st...@googlegroups.com>

To view this discussion on the web visit https://groups.google.com/d/msg/php-standards/-/djhcmxb7Uo0J.

To post to this group, send email to php-st...@googlegroups.com.

To unsubscribe from this group, send email to php-standard...@googlegroups.com.

[Beau Simensen]

So, how can we achieve that?  We could go nuts and write up interfaces for request factories, but I think that's overkill.  We can't and should not specify the constructors of the request or response objects either.  An alternative would be to have a method on a client used to create and return a request.  Further, the client could execute the request and return a response interface object when a request is sent.

To address your concerns of single responsibility, when implementing the PSR interface, your client object could  internally delegate to a factory used for creating requests and responses.  All of these implementation details would be internal to your implementation and should not concern the consumer of the PSR client.

I'm willing to go either way on this point. Does anyone else have an opinion?

When I asked for the use cases for the caller creating a Response object I did not really get anything back other than it might help with testing since it could be mocked and injected. Are there any use cases where it makes sense to create the Response before the Request is made by the Client?

As it stands right now I think that the Response object should be created and returned by Client::send rather than be sent to Client::send() as a parameter. I could probably be convinced otherwise if there are solid use cases floating around out there.

The Request is a bit trickier. I can see why a Client::createRequest method might be desirable since it would standardize the way that Request instances are created.

I played around a bit with ClientInterface based on some of these discussions:

namespace Fig\Psr\HttpClient;

interface ClientInterface
{
    /**
     * @return RequestInterface
     */
    public function createRequest($method, $url, array $headers = array(), $content = null);

    /**
     * @return ResponseInterface
     */

    public function sendRequest(RequestInterface $request);

    /**
     * @return ResponseInterface
     */

    public function request($method, $url, array $headers = array(), $content = null);
}

All three methods return a ResponseInterface instance. We can decide on changing sendRequest to accept ResponseInterface as a param instead.

The request method I'm a bit on the fence about. I think it is fair game if we are providing something like createRequest that is going to accept (most) everything to make a Request instance, though.

In any event I see the request method as more or less boilerplate code for PSR-HTTP-Client implementations.

I also took a crack at what a very simple Buzz implementation might look like to see how it felt. I did it with Buzz mainly because I've used Buzz and have not actually ever done anything with Guzzle. :) As it is now I think it will work with any existing Buzz client backing it.

namespace Buzz\PsrHttpClient;

class Client implements \Fig\Psr\ClientInterface
{
    public function __construct(\Buzz\Client\ClientInterface $client)
    {
        $this->client = $client;
    }

    public function createRequest($method, $url, array $headers = array(), $content = null)
    {
        // Construct the PSR Request however makes sense for Buzz
        // ... the set* methods may not be a part of PSR Request
        // but that does not mean Buzz implementation cannot use
        // them. Implementation detail.
        $request = new \Buzz\PsrHttpClient\Request;
        $request->setMethod($method);
        $request->setUrl($url);
        $request->setHeaders($headers);
        $request->setContent($content);
    }

    public function sendRequest(RequestInterface $request)
    {
        // Use util... or could be done inline here, brevity
        //
        // If Buzz Client ever accepts PSR Request natively
        // this conversion can be skipped.
        $buzzRequest = \Buzz\PsrHttpClient\Util::convertPsrRequestToBuzzRequest($request);
        $buzzResponse = new \Buzz\Message\Response;

        $this->client->send($buzzRequest, $buzzResponse);

        // Use util... or could be done inline here, brevity
        //
        // If \Buzz\Message\Response ever implements PSR Response
        // it can just be returned at this point.
        //
        // @return \Buzz\PsrHttpClient\Response
        return \Buzz\PsrHttpClient\Util::convertBuzzResponseToPsrResponse($buzzResponse);
    }

    public function request($method, $url, array $headers = array(), $content = null)
    {
        // boilerplate — conveniently mimics Benjamin's original proposal
        return $this->sendRequest($this->createRequest($method, $url, $headers, $content, $options));
    }
}

[Michael Dowling]

Beau,

I'm pretty much on board with everything you wrote except that you've never used Guzzle :)

-Michael

--
You received this message because you are subscribed to the Google Groups "PHP Standards Working Group" group.

To view this discussion on the web visit https://groups.google.com/d/msg/php-standards/-/VIOGwnTDjqsJ.

To post to this group, send email to php-st...@googlegroups.com.

To unsubscribe from this group, send email to php-standard...@googlegroups.com.

[Kris Wallsmith]

I'm coming around to Michael's point that what Buzz calls a client is more of an internal implementation detail than something that should be included in a standard.

So, what the PSR calls a client should look like this, in my mind:

interface Client

{

  /** @return Response */

  function send(Request $request);

  /** @return Response */

  function request($method, $url, $headers = array());

}

I don't see a place for a createRequest() method in the standard. A library can choose whether or not to provide factory functionality.

This interface maps roughly to what Buzz\Browser and Guzzle\HTTP\Client are doing right now. Maybe the folks on this thread can tentatively agree to this interface so we can move on to the message interfaces and put this thing to bed?

Thanks,
Kris

To unsubscribe from this group, send email to php-standards+unsubscribe@googlegroups.com.

[Michael Dowling]

Hi Kris,

I like what you have so far.

> I don't see a place for a createRequest() method in the standard. A library can choose whether or not to provide factory functionality.

The request() method you included has the inherent responsibility of
creating HTTP requests using the supplied arguments, thus it is a
factory. My suggestion for a createRequest() method has this same
behavior except that it returns the created request rather than
sending it.

In my opinion, we can include both a createRequest() method and a
request() method in the proposal, and both would serve an important
purpose.

* createRequest() - Used to create HTTP request objects. Can be used
to modify requests before sending, aggregate requests and transfer
them more efficiently, filter/update requests using application
specific requirements.
* request() - Used to send requests via a simple interface.

> function request($method, $url, $headers = array());

I think you forgot to include an optional $body argument in the
request() method signature. Entity bodies are a whole new can of
worms... The lowest common denominator, a string, forces the entire
body to load in memory before sending (try uploading a 5GB file to
S3). What do you think about allowing strings or open PHP resources
to be passed? I don't think we need something as full-fledged as
Guzzle's, but Guzzle has a class for entity bodies that internally
stores them as PHP resources:
https://github.com/guzzle/guzzle/blob/master/src/Guzzle/Http/EntityBody.php.
If a vendor does not support entity bodies represented as streams,
then they can simply do a type check and call stream_get_contents().

Thanks,
Michael

>> php-standard...@googlegroups.com.

>> For more options, visit this group at
>> http://groups.google.com/group/php-standards?hl=en.
>

> --
> You received this message because you are subscribed to the Google Groups
> "PHP Standards Working Group" group.
> To view this discussion on the web visit

> https://groups.google.com/d/msg/php-standards/-/iAoUulM7_4wJ.

>
> To post to this group, send email to php-st...@googlegroups.com.
> To unsubscribe from this group, send email to

> php-standard...@googlegroups.com.

[Nils Adermann]

Hey Michael,

On 06/17/2012 07:30 PM, Michael Dowling wrote:
> Hi Kris,
>
> I like what you have so far.
>
>> I don't see a place for a createRequest() method in the standard. A library can choose whether or not to provide factory functionality.
> The request() method you included has the inherent responsibility of
> creating HTTP requests using the supplied arguments, thus it is a
> factory. My suggestion for a createRequest() method has this same
> behavior except that it returns the created request rather than
> sending it.
>
> In my opinion, we can include both a createRequest() method and a
> request() method in the proposal, and both would serve an important
> purpose.
>
> * createRequest() - Used to create HTTP request objects. Can be used
> to modify requests before sending, aggregate requests and transfer
> them more efficiently, filter/update requests using application
> specific requirements.
> * request() - Used to send requests via a simple interface.
>

I'm not sure why you think it would be a client's responsibility to
create requests. Semantically the purpose of the client is to send
requests, accept responses and make these available to a user.

Request objects should be created and manipulated outside of the client.
The client's task is to serialize them to HTTP and send them, and to
parse the HTTP response and make this available as a Response object to
the user of the client.

It seems to be that creating and manipulating requests is an entirely
separate problem from serializing and sending them.

Cheers,
Nils

[Michael Dowling]

I agree that a client should not be responsible for creating requests; however, this does not mean a client cannot internally delegate this responsibility to a factory. This greatly simplifies the proposal, leaves the implementation completely up to the vendor, and is easier for consumers to work with.

Further, including a request() method still puts the responsibility of instantiating a request on the client. If I pass a method, URL, and headers to the request() method, then the client needs to know how to create a request object from the arguments. It's the same thing, except it isn't returning the created request.

-Michael

> --
> You received this message because you are subscribed to the Google Groups "PHP Standards Working Group" group.

[Beau Simensen]

The biggest reason I see for needing the client to construct the
request is that I'm not sure how we could handle this generically
otherwise. Either the client needs to construct the request itself
(factory) or we need to provide a PSR request implementation that
anyone can use. Otherwise as a user I'd have to know I've been passed
a buzz PSR http client implementation so that I could instantiate a
buzz PSR http request object. This sorta defeats the purpose I think?

[Kris Wallsmith]

I see your point about creating a request. If the standard includes a client interface that requires a request object but does not provide a way to create that request, the standard is not helpful.

With this in mind I would rather go the direction of not passing the request object, believe it or not. This is what I'm thinking now…

interface Client

{

  function get($url, array $headers = array());

  function post($url, $content = null, array $headers = array());

  function request($method, $url, $content = null, array $headers = array());

}

All methods return a TBD Response object.

Thoughts?

Kris

> To unsubscribe from this group, send email to php-standards+unsubscribe@googlegroups.com.

[Matthew Lanigan]

interface Client
{
  function get($url, array $headers = array());
  function post($url, $content = null, array $headers = array());
  function request($method, $url, $content = null, array $headers = array());
}

I too think this is the way to go. Mandating request objects is, I think, unnecessarily over-complicating things. If a library wishes to implement these methods using request objects, they may still certainly do so, but the methods above seem to be the least common denominator required by an HTTP library.

Matthew Lanigan

To view this discussion on the web visit https://groups.google.com/d/msg/php-standards/-/VA2B03Q3hU0J.

To post to this group, send email to php-st...@googlegroups.com.

To unsubscribe from this group, send email to php-standard...@googlegroups.com.

[Johannes Schmitt]

What about parallel requests? How would they be handled if at all?

Cheers,
Johannes

[Evert Pot]

On Jun 18, 2012, at 5:52 PM, Matthew Lanigan wrote:

> interface Client
> {
> function get($url, array $headers = array());
> function post($url, $content = null, array $headers = array());
> function request($method, $url, $content = null, array $headers = array());
> }
>
> I too think this is the way to go. Mandating request objects is, I think, unnecessarily over-complicating things. If a library wishes to implement these methods using request objects, they may still certainly do so, but the methods above seem to be the least common denominator required by an HTTP library.

I think the strongest argument for a Request object, is that it can potentially be re-used.

For me personally, a standard http client interface is nice, if well designed and simple.
But what I think is a much bigger benefit, is that a base Request and Response interface _also_ can be used to deal with incoming requests and responses.

As of right now, many frameworks will either:

1. Make the user directly access _GET, _POST, _SERVER, etc..
2. Provide a Request object in controllers (see Silex, Symfony, ZF2).
3. Merge these arrays and provide some $args or $params variable.

On the 'result' side, here's what often tends to happen:

1. Call echo and header() directly
2. Provide a Response object (analogue to the Request)
3. Provide some utility classes/functions to wrap this.

This may be an over-simplification :)

I feel that there's a lot of benefit to *before* defining a client, we define a Request and Response object.

With enough interest, we can unify how we do this in PHP, hide the ugly superglobals from plain sight, and provide something that's predictable and testable.
Much like python's wcgi system, or node.js':

http://nodejs.org/api/http.html#http_class_http_serverrequest
http://nodejs.org/api/http.html#http_class_http_serverresponse
http://nodejs.org/api/http.html#http_class_http_clientrequest
http://nodejs.org/api/http.html#http_http_clientresponse

http://docs.oracle.com/javaee/5/api/javax/servlet/ServletRequest.html
http://docs.oracle.com/javaee/5/api/javax/servlet/ServletResponse.html

https://github.com/symfony/HttpFoundation

https://github.com/evert/SabreDAV/tree/master/lib/Sabre/HTTP (shameless plug)


The win for a standard Request/Response interface is for me much larger than a Client interface, however.. if these interfaces exist it also implies that creating a potential Client interface is extremely easy.

.. Aside from all this, I think it's imperative that the $body arguments accept streams as well as strings. 'Dumb' http clients can always convert this to a string using stream_get_contents().

Evert

[Paul M. Jones]

On Jun 18, 2012, at 11:28 AM, Evert Pot wrote:

> I feel that there's a lot of benefit to *before* defining a client, we define a Request and Response object.

...

> The win for a standard Request/Response interface is for me much larger than a Client interface, however.. if these interfaces exist it also implies that creating a potential Client interface is extremely easy.

Totally agreed here.


-- pmj

[Dowling, Michael]

Here's how I think the client should look.

This allows a PSR consumer to send requests and receive responses, create
requests, and possibly send requests in parallel (pending further
definitions).

interface Client
{
/**
* Send a request
*
* @param RequestInterface $request
*
* @return ResponseInterface
*/
function send(RequestInterface $request);


/**
* Create and return a request
*
* @param string $method
* @param string $url
* @param array $headers
* @param resource|string $body
*
* @return RequestInterface
*/
function createRequest($method, $url, array $headers = array(), $body
= null);


/**
* Create and send a request
*
* @param string $method
* @param string $url
* @param array $headers
* @param resource|string $body
*
* @return ResponseInterface
*/
function request($method, $url, array $headers = array(), $body =
null);
}

We're making good progress on a client interface. While I think we must
define request and response interfaces too, I don't think we have to wait
to finish the client before we define them.

> I think it's imperative that the $body arguments accept streams as well
>as strings. 'Dumb' http clients can always convert this to a string using
>stream_get_contents().

Great point, and I fully agree.



-Michael

[Andreas Möller]

If

> <snip>

> function send(RequestInterface $request);

and


> <snip>

> function createRequest($method, $url, array $headers = array(), $body
> = null);

are part of the interface, then

> function request($method, $url, array $headers = array(), $body =
> null);
> }

seems like duplication to me. Or shall interfaces define convenience methods, too?


Andreas

[Dowling, Michael]

You're right. I'd be fine with removing it if that's the consensus.

-Michael

[Evert Pot]

On Jun 18, 2012, at 6:45 PM, Dowling, Michael wrote:

> You're right. I'd be fine with removing it if that's the consensus.
>
> -Michael

I'd be a proponent of removing it.

Here's some other thoughts:

1. Any response with any HTTP status should return a Response object, including responses in the 400 and 500 range.
2. I personally don't think a client is very useful, if there's no way to to deal with connection-level errors (e.g.: timeouts, dns lookup failure and so on). I feel this aspect should be clearly defined.
3. Personally I do a lot with HTTP, and actually have my 'backoffice' and 'frontend' completely separated, communicating through a REST service. Being able to specify a Proxy server is vital debugging. Would this be considered 'implementation detail' ? My gut says 'yes', but wanted to mention it anyway.
4. I feel that in order to 'not break the web' and to adhere with HTTP design, it should be recommended to follow redirects by default. I can still see that this is an implementation detail, but this should be mentioned.
5. In relation to that; If you use Curl and follow redirects, you will actually be able to retrieve all the headers for every 'hop', as well as the headers for a HTTP/1.1 100 Continue response. Is this something we should think about? (e.g.: an array of Response objects, or: just return the very last HTTP response).
6. Since this Client has a dependency on the Request and Response object (provided that that's what we want to do), this really should be defined first. Not doing this would be irresponsible.

Evert

[Kirill Chebunin]

If you add methods like createRequest you have to add setters to the Request interface to allow client to modify a created object. And all this process seems strange.
Client interface can realy have only one send method. It will be simple and clear.

Moreover Evert Pot mentioned more interesting things.
* Exceptions for send errors.
* Request and Response interfaces, may be some interfaces for set of parameters (headers, get, post)
* Redirect handling: for example getPreviousResponse() in Response interface and return just last response.

--
Best Regards,
Kirill chEbba Chebunin,
Moscow, Russia.

[mtdo...@gmail.com]

Hi Evert,

1. Any response with any HTTP status should return a Response object, including responses in the 400 and 500 range.

Sounds reasonable.

2. I personally don't think a client is very useful, if there's no way to to deal with connection-level errors (e.g.: timeouts, dns lookup failure and so on).

I don't think we can abstract every network error nor can we expect every vendor to be as capable or as compliant as another; however, we can recommend that PSR vendors throw an exception when an unrecoverable network error occurs. We would need to define the HttpException class (or whatever we call it).

3. [...] Being able to specify a Proxy server is vital debugging. Would this be considered 'implementation detail' ? My gut says 'yes', but wanted to mention it anyway.

I think this is an implementation detail and would be outside of the scope of a PSR client.

4. [...] It should be recommended to follow redirects by default. I can still see that this is an implementation detail, but this should be mentioned.

Seems logical, but I could see some consumers wanting the ability to handle redirects manually (for whatever reason). This could be considered an implementation detail that a PSR consumer could mention in their documentation what expectation it has for how PSR clients handle redirection.

5. In relation to that; If you use Curl and follow redirects, you will actually be able to retrieve all the headers for every 'hop', as well as the headers for a HTTP/1.1 100 Continue response. Is this something we should think about? (e.g.: an array of Response objects, or: just return the very last HTTP response).

I think this is outside of the scope of a PSR client. If someone needs this level of detail, then they should pick a vendor that supports this rather than choose to utilize a PSR client.

6. Since this Client has a dependency on the Request and Response object (provided that that's what we want to do), this really should be defined first. Not doing this would be irresponsible.

We've already touched on both a request and response interface though nothing concrete came out of it. I don't think a client interface requires a request or response interface though. Either way, I'm willing to discuss whatever, I just would like to see some sort of agreement on something, and I feel like we're close to a client interface.

-Michael

[Andreas Möller]

> If you add methods like createRequest you have to add setters to the Request interface to allow client to modify a created object. And all this process seems strange.

I understood that createRequest() is a factory that returns a request object.

The signature of createRequest() is the same as of request().
Therefore, if the former wouldn't work out, one would still have to
manipulate the request object. For a request object I believe it
wouldn't be critical to have accessors, as it's merely a data transfer
object, right? Thus, it would be critical *not* to be able to do so.

But, as has been suggested, it would make a lot of sense to define the
interfaces of request and response objects.

From my feeling this probably boils down to something near the lines
of how these have been implemented in Zend Framework 1.


Best regards,

Andreas

[Andreas Möller]

> 1. Any response with any HTTP status should return a Response object, including responses in the 400 and 500 range.

And also the *cough* 700 range, if it gets through:
https://github.com/joho/7XX-rfc

> 6. Since this Client has a dependency on the Request and Response object (provided that that's what we want to do), this really should be defined first. Not doing this would be irresponsible.

+1


Andreas

[Evert Pot]

On Jun 19, 2012, at 5:53 AM, mtdo...@gmail.com wrote:

> Hi Evert,

>
> 2. I personally don't think a client is very useful, if there's no way to to deal with connection-level errors (e.g.: timeouts, dns lookup failure and so on).
>
> I don't think we can abstract every network error nor can we expect every vendor to be as capable or as compliant as another; however, we can recommend that PSR vendors throw an exception when an unrecoverable network error occurs. We would need to define the HttpException class (or whatever we call it).

I think there would be a few 'pretty standard' ones we could define though. Looking at:

http://curl.haxx.se/libcurl/c/libcurl-errors.html

This would be my list:

1. Couldn't resolve Host
2. Couldn't connect
3. Operation timeout
4. Too many redirects

I feel that exceptions (or exception codes) just for these would be a good thing, as well as a code for 'everything else'.

>
> 3. [...] Being able to specify a Proxy server is vital debugging. Would this be considered 'implementation detail' ? My gut says 'yes', but wanted to mention it anyway.
>
> I think this is an implementation detail and would be outside of the scope of a PSR client.

Fair enough!

>
> 4. [...] It should be recommended to follow redirects by default. I can still see that this is an implementation detail, but this should be mentioned.
>
> Seems logical, but I could see some consumers wanting the ability to handle redirects manually (for whatever reason). This could be considered an implementation detail that a PSR consumer could mention in their documentation what expectation it has for how PSR clients handle redirection.

Actually.. I disagree here. The main problem we're solving is a standard Client interface that everybody can use.
I think it's fair for a user of such a client to expect, when they make a request that redirects are followed.

If this is not the case, then the consumer of the Client interface can no longer rely on it's correct behaviour.
Redirecting is a fundamental part of how the web works.

It's a Bad Thing™ for me as a developer of webservices that I cannot rely on consumers to not break when I redirect them to a new location.
Since the primary target audience is likely going to be consumers of web services, it's pretty important to push for the 'correct thing'.

>
> 5. In relation to that; If you use Curl and follow redirects, you will actually be able to retrieve all the headers for every 'hop', as well as the headers for a HTTP/1.1 100 Continue response. Is this something we should think about? (e.g.: an array of Response objects, or: just return the very last HTTP response).
>
> I think this is outside of the scope of a PSR client. If someone needs this level of detail, then they should pick a vendor that supports this rather than choose to utilize a PSR client.

I can agree with this.. I'd opt to keep the Client simple. Frameworks could supply more complex versions, which *should* be easy with a common Request/Response interface.

>
> 6. Since this Client has a dependency on the Request and Response object (provided that that's what we want to do), this really should be defined first. Not doing this would be irresponsible.
>
> We've already touched on both a request and response interface though nothing concrete came out of it. I don't think a client interface requires a request or response interface though. Either way, I'm willing to discuss whatever, I just would like to see some sort of agreement on something, and I feel like we're close to a client interface.

If you're looking for agreement on this mailing list, you're going to have a bad time ;)

Cheers,
Evert

[Jurgens du Toit]

I most certainly agree on the fact that a Request Interface will be a big win. Not just in terms of enhancing code quality (enabling users to inject requests, instead of operating on the super globals), but also for interoperability.

If you want to use a Request object in a small application, you either need to write your own Request class, or import an existing one. If a defined interface exists and is used, you have a starting point for writing your own, and you know you won't be locked in to the library / framework you chose to copy from should you go that route.

The same goes for a Response interface. It also has the added benefit that it will guide the coder into separating HTML / presentation and code, as the code will happen around the Response object, and presentation in the body of the Response.

J

On Saturday, 24 March 2012 18:06:55 UTC+2, Benjamin Eberlei wrote:

See https://github.com/php-fig/fig-standards/pull/24

From the introduction:

Many libraries and applications require an HTTP client to talk to other servers. In general all these libraries either ship their own HTTP client library, or use low-level PHP functionality such as file_get_contents, ext/curl or the ext/socket. Depending on the use-cases there are very tricky implementation details to be handled such as proxies, SSL, authentication protocols and many more. Not every small library can afford to implement all the different details. However there are only a few http client libraries that are widely used between different projects, because of NIH or fears of vendor lock-in.

Motivation:

Doctrine has about 4 projects that need an HTTP client. Currently every projects implements them itself, which is annoying. We could abstract this into our "Common" library, however that would mean we would start being a "http client" vendor. Now personally, i don't care about http clients and would rather let others do this, however i also don't want to face vendor lock-in by deciding for any of the many http clients. In a perfect world (with this standard) Doctrine could ship one very simple http client using sockets, and if anyone needs something more awesome, he could just use any other provider of a PSR http client.

Questions:

1. Do the voting members think this is something to standardize?
2. API: I didn't include a Request object as i think its not really necessary. The proposal is expclicitly very simple.
3. How to proceed?
4. Feedback?

greetings,
Benjamin

[Beau Simensen]

On Tuesday, June 19, 2012 7:18:19 AM UTC-5, Evert Pot wrote:

> 4. [...] It should be recommended to follow redirects by default. I can still see that this is an implementation detail, but this should be mentioned.
>
> Seems logical, but I could see some consumers wanting the ability to handle redirects manually (for whatever reason). This could be considered an implementation detail that a PSR consumer could mention in their documentation what expectation it has for how PSR clients handle redirection.

Actually.. I disagree here. The main problem we're solving is a standard Client interface that everybody can use.
I think it's fair for a user of such a client to expect, when they make a request that redirects are followed.

If this is not the case, then the consumer of the Client interface can no longer rely on it's correct behaviour.
Redirecting is a fundamental part of how the web works.

It's a Bad Thing™ for me as a developer of webservices that I cannot rely on consumers to not break when I redirect them to a new location.
Since the primary target audience is likely going to be consumers of web services, it's pretty important to push for the 'correct thing'.

I can't seem to find where it was proposed, but I feel that Response having a getPreviousResponse method is the best of both worlds. You end up with the final Response, but can back track if you need to.

Only problem with this is that I'm not sure how easy that would be to implement. The easiest solution would be to turn off follow redirects for the backing transports (curl, php streams, whatever) and follow them manually. This would come at a hit to performance. I'm not sure it is even possible with $php_response_headers without going this route, though.

Maybe this behavior (tracking redirected requests) can be disabled by default and enabled on a Request-by-Request basis?

  $request->enableRedirectHistory();

[Ryan McCue]

Beau Simensen wrote:
> I can't seem to find where it was proposed, but I feel that Response
> having a getPreviousResponse method is the best of both worlds. You end
> up with the final Response, but can back track if you need to.
>
> Only problem with this is that I'm not sure how easy that would be to
> implement. The easiest solution would be to turn off follow redirects
> for the backing transports (curl, php streams, whatever) and follow them
> manually. This would come at a hit to performance. I'm not sure it is
> even possible with $php_response_headers without going this route, though.

With Requests [1][2], previous Response objects are stored
chronologically in an array. For both cURL and fsockopen, this requires
disabling autofollowing redirects. (Although, I do believe it might be
possible using cURL to autofollow the redirects and still get the
headers out.)

The performance hit is small, but it does exist there.

[1]: http://requests.ryanmccue.info/
[2]: https://github.com/rmccue/Requests
--
Ryan McCue
<http://ryanmccue.info/>

[Matt Farina]

Out of curiosity, where does this proposal stand. In an off list discussion I heard it was dead and until a couple days ago there wasn't any activity. But, there are new comments and some new emails.

I'm interested in this topic if there is going to be movement on this and would participate. But, if it's dead I don't want to put in the work.

Note, this is not something I am saying needs to be a FIG standard. I'm just saying that if it is going to be pursued I'll participate.

[Beau Simensen]

On Friday, July 13, 2012 9:16:43 AM UTC-5, Matt Farina wrote:

Out of curiosity, where does this proposal stand. In an off list discussion I heard it was dead and until a couple days ago there wasn't any activity. But, there are new comments and some new emails.

I'm interested in this topic if there is going to be movement on this and would participate. But, if it's dead I don't want to put in the work.

Note, this is not something I am saying needs to be a FIG standard. I'm just saying that if it is going to be pursued I'll participate.

There is a lot of work to be done but I think a lot of progress has been made. I'd like for anyone who thinks this proposal is dead to say as much on the list. I think it would be interesting to hear where they are coming from. If we are all wasting our time here I'd love to know why.

[Larry Garfield]

It was probably just because it got swamped out by other noise on the
list for the past few months. I haven't looked at the proposal itself
but in concept I agree that Request/Response objects are a good
candidate for PSR-ification.

--Larry Garfield

[Matt Farina]

@Larry, thanks for clarifying. This is a place a PSR could make a lot of sense.