Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:31340
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain lerdorf.com from 204.11.219.139 cause and error)
Message-ID: <46AF6536.4010600@lerdorf.com>
Date: Tue, 31 Jul 2007 09:37:10 -0700
User-Agent: Thunderbird 2.0.0.5 (Macintosh/20070716)
MIME-Version: 1.0
To: Daniel Stenberg <daniel@haxx.se>
CC:  internals@lists.php.net
References: <Pine.LNX.4.64.0707301316440.22586@yvahk3.pbagnpgbe.fr>
In-Reply-To: <Pine.LNX.4.64.0707301316440.22586@yvahk3.pbagnpgbe.fr>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Regarding the ext/curl extension
From: rasmus@lerdorf.com (Rasmus Lerdorf)

Daniel, I don't really understand what renaming the extension would
accomplish.  It's a thin wrapper on top of the curl library which isn't
something we can nor want to hide, so no matter what we call it, people
are still going to go looking for more information about curl and the
opening paragraph at http://www.php.net/manual/en/ref.curl.php describes
the extension pretty well I think.  If you have some suggestions on
wording changes for that opening paragraph that might make your life
easier, we'd be happy to make changes to that.

And the curl_setopt() page lists more than just the names of the
options.  There is a small blurb next to each one describing what it
does:  http://www.php.net/manual/en/function.curl-setopt.php
Combine that with all the examples in the user comments at the bottom of
that page, and I think at least all the common options are pretty well
covered.  That doesn't mean the docs can't be improved and that we
should pull some of those user examples up into the main docs, but I
don't think it is accurate to say that we only list the names of most
options and nothing else.

-Rasmus

Daniel Stenberg wrote:
> Hi PHP hackers!
> 
> (I'm not subscribed, please CC me if you want me to read your responses.)
> 
> I am the primary author and maintainer of the libcurl library, the
> underlying library that supports the PHP extension named... eh, right.
> What is the extension called really? CURL? ext/curl? curl?
> 
> I'm writing to you to ask for your help to clear up some of the worst
> confusions you (in the PHP project) and we (in the cURL project) are
> causing the users of your PHP binding for libcurl.
> 
> Here's the story (of course described here with my heavy bias):
> 
> o You call the binding CURL or similar. The heavy mentioning of libcurl in
>   your docs also tend to make PHP people to believe they actually "use
>   libcurl".
> 
> o There's a huge lack of docs for the PHP binding for libcurl on the
> php.net
>   site. Most options are only listed with their names, so to figure out
>   exactly what the names mean (and more) they need to search elsewhere.
> 
> o The elsewhere is very much likely the curl web site, which indeed does
> have
>   all the options documented (but for the libcurl C API, where they have
> the
>   same names...).
> 
> o But before the poor PHP users have reached the docs and figured out what
>   they mean, they have run head-first into this wall: in our project we
> have a
>   "libcurl" (which is a library with a C API/function interface) and we
> have a
>   "curl" command line tool.
> 
>   So now the users are mighty confused. They think they're using CURL,
> curl or
>   libcurl and here we claim they are not using curl nor libcurl...
> 
>   In a (private) conversation with a PHP team member he said the
> extension is
>   called 'ext/curl' but I don't think that's a lot better since that's just
>   going to be seen as "the extension called curl" to people. And then we're
>   back on square 0.
> 
> o In order to remedy this problem that really is a huge support issue
> for us
>   (since for some funny reason the curl-and-php mailing list is hosted
> by us
>   and I think I do the majority of the support on this list even though the
>   binding is the product of your project...), I have simply decided to
> refer
>   to the binding with a unique name that is not the exact same (case
>   differences ignored) as one of our products. I call it PHP/CURL. (I
> did try
>   to contact some of you back when this problem made my bubble burst, but I
>   never got any responses and thus I proceeded anyway.) But now I'm here to
>   let you know about my pains.
> 
> o I've been told by more than one PHP team member that renaming the
> extension
>   in your end is more or less out of the question, so even though I would
>   *really* want that (and no other libcurl binding has hijacked one of our
>   names like this), I can only see one really good way to solve this
> problem.
>   And please do notice that this problem occurs only to YOUR users of YOUR
>   binding.
> 
> The Solution (as i see it - I'll just stress that again)
> 
> You need to vastly extend the amount of documentation for the PHP
> binding for libcurl (I seriously don't know how to refer to it) on your
> site to drastically reduce the need for your users to go searching for
> the information on other sites, since the very moment they do that they
> enter the name- confusion maze and then a large amount of them are lost...
> 
> This solution is rather half-baked, but I can't see any proper solution
> without a rename of the binding.
> 
> Of course, it would also help if there would actually be PHP hackers
> involved on the curl-and-php mailing list to help out.
> 
> I'll be happy to hear if you have any other thoughts or ideas on how to
> improve this situation.
>