Everything

php

Regarding the ext/curl extension

php.internals

Daniel Stenberg

19 years ago

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.

Steph

19 years ago

Hi Daniel, all -

Bit of history here: I promised Daniel last week I'd put some effort into
the documentation side. That was before I started looking at the
extension... it has no tests and it needs a bit of love before it should be
documented. I got as far as the simplest function having the wrong signature
and realized this wasn't going to be a quickie.

I don't have time to spend on ext/curl before disappearing on vacation,
although I should have enough time after I get back if nobody else gets to
it first. It's not complicated code, it just needs research. And tests. And
then docs.

- Steph


----- Original Message -----
From: "Daniel Stenberg" <daniel@haxx.se>
To: <internals@lists.php.net>
Sent: Tuesday, July 31, 2007 9:43 AM
Subject: [PHP-DEV] Regarding the ext/curl extension

Richard Lynch

19 years ago

I intend to subscribe to the php-and-curl list or whatever it's called
:-) and MAY even be able to squeeze out some cycles to hack and/or
document some stuff...

That said, I personally never had a problem searching the haxx.se site
and finding out what CURLOPT_XYZ meant, except for the php-specific
CURLOPT_BINARYTRANSFER... :-)

I'd be hesitant to try and duplicate the libcurl docs onto the PHP
site, as the whole point of PHP being a "glue" language and
maintaining as much as possible of external lib idioms is to get
documentation re-use out of the original docs, presumably maintained
better by the original authors -- and they're pretty darn nice docs
over on haxx.se, at least when I went looking for stuff.

And anybody on the internals list can tell you I'm NOT the brightest
bulb in the package. :-)

On Tue, July 31, 2007 4:18 am, Steph Fox wrote:

> Hi Daniel, all -
>
> Bit of history here: I promised Daniel last week I'd put some effort
> into
> the documentation side. That was before I started looking at the
> extension... it has no tests and it needs a bit of love before it
> should be
> documented. I got as far as the simplest function having the wrong
> signature
> and realized this wasn't going to be a quickie.
>
> I don't have time to spend on ext/curl before disappearing on
> vacation,
> although I should have enough time after I get back if nobody else
> gets to
> it first. It's not complicated code, it just needs research. And
> tests. And
> then docs.
>
> - Steph
>
>
> ----- Original Message -----
> From: "Daniel Stenberg" <daniel@haxx.se>
> To: <internals@lists.php.net>
> Sent: Tuesday, July 31, 2007 9:43 AM
> Subject: [PHP-DEV] Regarding the ext/curl extension
>
>
>> 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.
>>
>> --
>> PHP Internals - PHP Runtime Development Mailing List
>> To unsubscribe, visit: http://www.php.net/unsub.php
>>
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

--
Some people have a "gift" link here.
Know what I want?
I want you to buy a CD from some indie artist.
http://cdbaby.com/browse/from/lynch
Yeah, I get a buck. So?

Daniel Stenberg

19 years ago

On Sat, 4 Aug 2007, Richard Lynch wrote:

> That said, I personally never had a problem searching the haxx.se site and
> finding out what CURLOPT_XYZ meant, except for the php-specific
> CURLOPT_BINARYTRANSFER... :-)

The binding has a 1:1 mapping on all its option names (except
CURLOPT_BINARYTRANSFER) to libcurl's as far as I know, but libcurl offers a
lot more options than what the binding offers. There's also the not so minor
detail that the PHP binding has its own way of interpreting and acting on some
options that isn't done by libcurl. (I'm mainly thinking about
CURLOPT_HTTPPOST.)

The funtion names of the binding are also all different than the ones used by
libcurl.

> I'd be hesitant to try and duplicate the libcurl docs onto the PHP site, as
> the whole point of PHP being a "glue" language and maintaining as much as
> possible of external lib idioms is to get documentation re-use out of the
> original docs, presumably maintained better by the original authors -- and
> they're pretty darn nice docs over on haxx.se, at least when I went looking
> for stuff.

Thanks.

I'm all for trying to get things as good as possible, but the libcurl docs
have the minor drawbacks to PHP users that they speak of the C API so it
refers to data types and operations etc that PHP user won't care about or in
worst cases will get confused by.

So, while I wouldn't mind adapt somewhat or even do additional hacks in order
to help others to host or extract partical docs from the curl site or the curl
docs (since most of our docs are in fact the man pages converted to HTML), I
just don't know how or what I could do.

Rasmus Lerdorf

19 years ago

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:

Daniel Stenberg

19 years ago

On Tue, 31 Jul 2007, Rasmus Lerdorf wrote:

> Daniel, I don't really understand what renaming the extension would
> accomplish.

Then I didn't make myself clear.

The point of renaming would be to allow people to search for something with a
name that doesn't confuse them. If the binding would be called 'mombamoolo',
they would search for that and they would certainly not be confused by
products or projects called curl or libcurl (even if they would know that
mombamoolo uses libcurl).

Now they search for curl and libcurl instead, and they read the docs on our
site, and yes some of them get angry or even hostile on us when they can't
find enough details about PHP on our curl site.

Then again, I did say I realize that a rename won't happen.

> And the curl_setopt() page lists more than just the names of the
> options.

Hm, I stand corrected. I obviously haven't paying attention. I guess I was
fooled by the "constants" page... Sorry, my bad.

Still, this is a real problem to many PHP users of this extension. Like it or
not...

(and no, I don't suggest that name, it was picked randomly just to make my
point)

Derick Rethans

19 years ago

On Tue, 31 Jul 2007, Daniel Stenberg wrote:

> On Tue, 31 Jul 2007, Rasmus Lerdorf wrote:
>
> > Daniel, I don't really understand what renaming the extension would
> > accomplish.
>
> Then I didn't make myself clear.
>
> The point of renaming would be to allow people to search for something
> with a name that doesn't confuse them. If the binding would be called
> 'mombamoolo', they would search for that and they would certainly not
> be confused by products or projects called curl or libcurl (even if
> they would know that mombamoolo uses libcurl).

This has another side as well. If it was called mombamoolo then how
would people know that PHP is actually providing a wrapper for curl?
There have been some examples of this in the past "sattelite" and
"universe" where both extensions around corba for example- and if you
didn't know you'd have no idea where to look for. So I'd say that with
picking a different name you'd confuse people.

regards,
Derick

--
Derick Rethans
http://derickrethans.nl | http://ez.no | http://xdebug.org

Steph

19 years ago

Guys,

I don't think battling helps anyone.

I thought Daniel and myself had come to an (admittedly vague) agreement last
week that a good way to approach this might be by fixing the php.net docs to
give all the PHP-related info currently held on the libcurl site, and then
ditch that page on the libcurl site and just link to the downloads rather
than the libcurl project homepage.

As you might gather from that, I do agree with Daniel that the current setup
with ext/curl is utterly confusing for PHP users. I don't really care whose
fault it is, it just needs fixing.

Gwynne and myself have been talking under cover, and it seems we both are
keen to do something with this. She has other projects outstanding at
present (mainly the phpdoc build system) and I have a bunch of commitments
to fulfill before I head off on holiday. For both of us, September's the
first sane attack date when it comes to ext/curl.

There's also a bit more to this than straightforward documentation. I think
I mentioned already.

Can we please drop this now until we both have space to work on it? After
all, the status quo didn't arrive overnight.

Cheers,

- Steph

----- Original Message -----
From: "Derick Rethans" <derick@php.net>
To: "Daniel Stenberg" <daniel@haxx.se>
Cc: <internals@lists.php.net>
Sent: Tuesday, July 31, 2007 9:48 PM
Subject: Re: [PHP-DEV] Regarding the ext/curl extension

Alan Milnes

19 years ago

On 01/08/07, Steph Fox <steph@zend.com> wrote:

> There's also a bit more to this than straightforward documentation. I think
> I mentioned already.

That's fine but if you need help with the documentation please give me a shout.

Alan

Philip Olson

19 years ago

>> There's also a bit more to this than straightforward
>> documentation. I think
>> I mentioned already.
>
> That's fine but if you need help with the documentation please give
> me a shout.

Consider this a shout from the PHP Manual! Please send
phpdoc@lists.php.net an email introducing yourself and we'll talk.
There are many parts of the manual in need of help, always, so
welcome to the team ;)

Regards,
Philip

Steph

19 years ago

Shh, Philip will see you!

(Thanks!)

----- Original Message -----
From: "Alan Milnes" <alan@itfoundation.org.uk>
To: <internals@lists.php.net>
Cc: "Steph Fox" <steph@zend.com>
Sent: Wednesday, August 01, 2007 8:39 AM
Subject: Re: [PHP-DEV] Regarding the ext/curl extension

Rasmus Lerdorf

19 years ago

Daniel Stenberg wrote:

> On Tue, 31 Jul 2007, Rasmus Lerdorf wrote:
>
>> Daniel, I don't really understand what renaming the extension would
>> accomplish.
>
> Then I didn't make myself clear.
>
> The point of renaming would be to allow people to search for something
> with a name that doesn't confuse them. If the binding would be called
> 'mombamoolo', they would search for that and they would certainly not be
> confused by products or projects called curl or libcurl (even if they
> would know that mombamoolo uses libcurl).
>
> Now they search for curl and libcurl instead, and they read the docs on
> our site, and yes some of them get angry or even hostile on us when they
> can't find enough details about PHP on our curl site.
>
> Then again, I did say I realize that a rename won't happen.
>
>> And the curl_setopt() page lists more than just the names of the
>> options.
>
> Hm, I stand corrected. I obviously haven't paying attention. I guess I
> was fooled by the "constants" page... Sorry, my bad.
>
> Still, this is a real problem to many PHP users of this extension. Like
> it or not...
>
> (and no, I don't suggest that name, it was picked randomly just to make
> my point)

We'll go through and clean up and improve the documentation.  We even
have volunteers to do so now.  But many people don't take the time to
read the docs, no matter how good they may be, so this problem isn't
really going to go away.  Perhaps you should simply redirect people to
the php-general list, or at least have an automatic FAQ answer with the
relevant links to the PHP documentation.  Even the current curl_setopt
page should answer many questions people have.  The short url for it is
http://php.net/curl_setopt

We have had the problem of support spillover before in the project,
especially to the smaller 3rd-party libs we link against, and it tends
to simply be a matter of scale.  The number of people using PHP is
massive, and there will always be a certain percentage of people using
any technology that will be confused and start sending uninformed
questions to every mailing list they can find.  We do our best to
provide good and accessible documentation to alleviate this, but there
is only so much we can do.

-Rasmus

Pierre Joye

19 years ago

Hi Daniel,

On 7/31/07, Daniel Stenberg <daniel@haxx.se> wrote:

> > Daniel, I don't really understand what renaming the extension would
> > accomplish.
>
> Then I didn't make myself clear.
>
> The point of renaming would be to allow people to search for something with a
> name that doesn't confuse them. If the binding would be called 'mombamoolo',
> they would search for that and they would certainly not be confused by
> products or projects called curl or libcurl (even if they would know that
> mombamoolo uses libcurl).
>
> Now they search for curl and libcurl instead, and they read the docs on our
> site, and yes some of them get angry or even hostile on us when they can't
> find enough details about PHP on our curl site.

I would like to suggest you a few things I did for libgd. It has the
same problem (even worst, as PHP forked gd a few years back).

- Add abinding entry in the navigation menu in all your pages (not
only for libcurl)

- Add a notice (in bold, italic and red :) on the homepages (curl and
libcurl)  that you have nothing to do with the binding and put a link
to the binding page (which should only have a "see
myfavouritescriptinglanguage.net/curl" for further details)

- Drop the PHP doc on your site as soon as you consider the PHP manual
as good enough

But pushing the PHP docs (as Steph suggested later) to your site will
only bring you more questions about php's CURL binding. It sounds like
a bad idea :)

Cheers
--Pierre

Steph

19 years ago

> But pushing the PHP docs (as Steph suggested later) to your site will
> only bring you more questions about php's CURL binding. It sounds like
> a bad idea :)

Erm... where did I suggest that? I'm saying the exact opposite - you're
right, it's an extremely bad idea! and it also happens to describe the
current situation.

- Steph

Pierre Joye

19 years ago

On 8/1/07, Steph Fox <steph@zend.com> wrote:

> > But pushing the PHP docs (as Steph suggested later) to your site will
> > only bring you more questions about php's CURL binding. It sounds like
> > a bad idea :)
>
> Erm... where did I suggest that?

Nowhere :) No idea why I misunderstood your post, but a second read did it ;)

--Pierre

Stanislav Malyshev

19 years ago

> 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?

It's called "CURL extension", I'd say. As there's MySQL extension, Json
extension, DOM extension, SOAP extension - there's CURL extension.

> 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".

Don't they?

> 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.

Missing docs are bad. PHP being open-source community project, it means
nobody did it - and somebody has to step up and do it.

>   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.

ext/curl is the path where the extension resides. As for name for the
extension, there are many names used in different context (as a person
can have first name, last name, email, driver's license number, Skype
ID, Facebook username, a nickname for close friends, other nickname only
parents use, etc.). Usually it is just referred to as curl extension,
unless the context requires different name.

> 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

It doesn't make sense to name the extension "php/curl" - everything
inside PHP is, well, PHP and no extension ever had php/ prefix in it's
name. It is custom to name extensions by the functional module they
represent. Externally, of course, you can refer to it as PHP/curl but
I'd still suggest to use something like "curl PHP extension" because
most people wouldn't know what is "PHP/CURL".

>   *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

I do not think it is proper to refer to the extension name as
"hijacking". No more than having file named MyApplet.java is a
"hijacking" of the Java language name. The extension name simply refers
to the functional module it implements.

> 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...

Of course, any help with improving the docs is always welcome.
Unfortunately, writing good docs is not always a strong side of the code
hackers. While I think PHP manual documents functions available
reasonably well, every improvement that can be done to it is most welcome.

--
Stanislav Malyshev, Zend Software Architect
stas@zend.com   http://www.zend.com/
(408)253-8829   MSN: stas@zend.com