# Regarding the ext/curl extension - Thread: https://externals.io/message/31335 - Original archive: https://news-web.php.net/php.internals/31335 - Started by Daniel Stenberg on 2007-07-31T08:43:34+00:00 - Messages: 16 - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #31335 — Daniel Stenberg — 2007-07-31T08:43:34+00:00 URL: https://externals.io/message/31335#31335 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. --- ## #31336 — Steph Fox — 2007-07-31T09:18:00+00:00 URL: https://externals.io/message/31335#31336 · In reply to: #31335 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" To: 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. --- ## #31340 — Rasmus Lerdorf — 2007-07-31T16:37:10+00:00 URL: https://externals.io/message/31335#31340 · In reply to: #31335 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. --- ## #31341 — Stanislav Malyshev — 2007-07-31T18:57:28+00:00 URL: https://externals.io/message/31335#31341 · In reply to: #31335 > 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 --- ## #31343 — Daniel Stenberg — 2007-07-31T20:42:30+00:00 URL: https://externals.io/message/31335#31343 · In reply to: #31340 > 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) --- ## #31344 — Derick Rethans — 2007-07-31T20:48:32+00:00 URL: https://externals.io/message/31335#31344 · In reply to: #31343 > > > > […] > > 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 --- ## #31345 — Rasmus Lerdorf — 2007-07-31T20:55:38+00:00 URL: https://externals.io/message/31335#31345 · In reply to: #31343 Daniel Stenberg wrote: > > > > […] > > 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. > > > […] > > 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 --- ## #31346 — Steph Fox — 2007-08-01T00:06:09+00:00 URL: https://externals.io/message/31335#31346 · In reply to: #31344 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" To: "Daniel Stenberg" Cc: Sent: Tuesday, July 31, 2007 9:48 PM Subject: Re: [PHP-DEV] Regarding the ext/curl extension > > > > […] > > 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 --- ## #31347 — Alan Milnes — 2007-08-01T07:39:10+00:00 URL: https://externals.io/message/31335#31347 · In reply to: #31346 > 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 --- ## #31348 — Pierre — 2007-08-01T08:23:12+00:00 URL: https://externals.io/message/31335#31348 · In reply to: #31343 Hi Daniel, > > […] > > 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 --- ## #31354 — Philip Olson — 2007-08-01T15:33:41+00:00 URL: https://externals.io/message/31335#31354 · In reply to: #31347 > > […] > > 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 --- ## #31355 — Steph Fox — 2007-08-01T15:57:45+00:00 URL: https://externals.io/message/31335#31355 · In reply to: #31348 > 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 > > Cheers > --Pierre --- ## #31356 — Steph Fox — 2007-08-01T15:59:13+00:00 URL: https://externals.io/message/31335#31356 · In reply to: #31347 Shh, Philip will see you! (Thanks!) ----- Original Message ----- From: "Alan Milnes" To: Cc: "Steph Fox" Sent: Wednesday, August 01, 2007 8:39 AM Subject: Re: [PHP-DEV] Regarding the ext/curl extension > > > > […] > > That's fine but if you need help with the documentation please give me a > shout. > > Alan --- ## #31357 — Pierre — 2007-08-01T21:23:25+00:00 URL: https://externals.io/message/31335#31357 · In reply to: #31355 > > […] > > Erm... where did I suggest that? Nowhere :) No idea why I misunderstood your post, but a second read did it ;) --Pierre --- ## #31461 — Richard Lynch — 2007-08-05T03:47:23+00:00 URL: https://externals.io/message/31335#31461 · In reply to: #31336 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. :-) > 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" > To: > Sent: Tuesday, July 31, 2007 9:43 AM > Subject: [PHP-DEV] Regarding the ext/curl extension > > > > […] > > -- > > > > -- 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? --- ## #31463 — Daniel Stenberg — 2007-08-05T21:06:34+00:00 URL: https://externals.io/message/31335#31463 · In reply to: #31461 > 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.