Developer notes and secrets
- 1 I can't run this on PHP 5.3 or PHP 5.4 or ...
- 2 Multiple requests
- 3 Custom headers
I can't run this on PHP 5.3 or PHP 5.4 or ...
And you shouldn't. UPGRADE NOW!
There are still tests running for very low releases (down to at least PHP 5.4) but there is no longer any guarantee that this will work. As we work with such things as short hand arrays and chained requests, everything below v5.4 - and even 5.6 - is obsolete. The highest wish for netcurl is that we also leave all PHP releases where type hinting is incompatible, so it will probably be something for netcurl 6.2 och 7.0.
Generally having problems with PHP 5?
Yes. For netcurl 6.1, it's no longer my problem. It's yours and your inability to move forward with the world. Go PHP 7 NOW, so we can drop PHP 5 entirely! Netcurl still lives in an obsolete world of syntax, thanks to the slow upgrade rate. But as everybody - except you - are moving forward now, you will be left alone with your old releases.
Optionize netcurl
curl has been a big part of this library so most of the content are built around this driver, even if it's not needed. But a really huge part och at least WrapperConfig is using settings that is based on the constants. When other libraries requires special settings (i.e such that are not injected by you) the configurator could transform those settings to its right environment - or just keeps them as is inside the curlopts array.
CURLOPTs
CURLOPT options are no longer primarily set as constants, as we sometimes meet curlopts not set in the current release of curl on server level. This is very rare though, but if this happens it's a sign that the server owner runs something that is way too old for a production. In such cases, you should upgrade your system before bugtracking the library. However, for the sake, netcurl includes its own version of curlopts in case of any missing constants and the are fetched dynamically only when necessary and the default constants are missing - instead of running into undefined data warnings. If this happens it's more likely that the developer, that utilizes netcurl, has pushed in something wrong (usually something that is too old comparing to upgraded software).
The transformation happens here, in WrapperConfig:
private function getCurlConstants($curlOptConstant)
{
if (is_array($curlOptConstant)) {
foreach ($curlOptConstant as $curlOptKey => $curlOptValue) {
$constantValue = @constant($curlOptKey);
if (empty($constantValue)) {
// Fall back to internally stored constants if curl is not there.
$constantValue = @constant('TorneLIB\Module\Config\WrapperCurlOpt::NETCURL_' . $curlOptKey);
}
$this->options[$constantValue] = $curlOptValue;
}
}
}curlopt defaults in v6.0
In 6.0 some default curl constants is not in use. Information can be found at Known issues and fixes.
How we handle SSL
The below text is documented from prior releases of NetCurl 6.0 - it is a well documented fact that CURLOPT_SSL_VERIFYHOST has changed over time. In netcurl 6.1 it is still not decided whether this should be kept or discontinued to use as this was a problem discovered in a very specific version of PHP 5.4 combined with libcurl. Running this old PHP releases should be considered extremely disencouraged (and stupid) in a security point of view.
From libcurl 7.28.1 CURLOPT_SSL_VERIFYHOST is deprecated. However, using the value 1 can be usedas of PHP 5.4.11, where the deprecation notices was added. The deprecation has started before libcurl7.28.1 (this was discovered on a server that was running PHP 5.5 and libcurl-7.22). In full debugeven libcurl-7.22 was generating this message, so from PHP 5.4.11 we are now enforcing the value 2for CURLOPT_SSL_VERIFYHOST instead. The reason of why we are using the value 1 before this versionis actually a lazy thing, as we don't want to break anything that might be unsupported before this version.
SSL Certificate problems
This section covers:
SSL3_GET_SERVER_CERTIFICATE
CURLE_SSL_CACERT
SSL2_SET_CERTIFICATE (error)
Documented in
In some versions of PHP SSL verification fails with routines:SSL3_GET_SERVER_CERTIFICATE:certificate. For the tests, where the importance of result is not focused on SSL, we could disable the verification checks if we want to do so. In Bitbucket Pipelines docker environments errors has been discovered on some PHP releases, which we'd like to primary disable.
In version 6.0.20 a self adjusting feature was added to handle verification errors automatically. Especially the error codes 14090086 (routines:ssl3_get_server_certificate:certificate) and 1407E086 (routines:SSL2_SET_CERTIFICATE) was added to the core to make sure - if it was allowed by the system - such problems could be bypassed. By means, in this case it is equal to a security layer removal (by simply disable SSL verifications on fly).
For v6.1, netcurl is set to guess the SSL version used on the remote:
WrapperConfig
'CURLOPT_SSLVERSION' => CURL_SSLVERSION_DEFAULT,Configuration classes and verbosity
netcurl is written so that no preconfiguration is necessary; the defaults has from 6.0 been set to be as verbose as possible. This is from v6.1 not entirely true. In 6.0 the verbosity has been used to retrieve and handle full head and body and return them to the user as is. It is true that the content return will still be intact, but the structure of how the head is returned to clients has been changed. Instead of downloading the header and transform it to fetchable content, netcurl is instead using native functions to extract the header. This is done with the CURLOPT_HEADERFUNCTION option flag. Changing this is prevented from the core parts of netcurl, even if it's still potentially available from the getCurlHandle()-method.
Most of the options available in curl is configurable, by the WrapperConfig-class, except for the settings below (not getCurlHandle included).
curlopt | static value | notes |
|---|---|---|
| User defined url. | Legacy for fetching an URL, that potentially makes it possible to fetch an URL from a server that is normally not the one pointed out in DNS entries. |
|
|
|
|
|
|
|
|
|
| true |
|
| Internal getCurlHeaderRow. |
|
As for externally configurable, a developer may use something like this to set up own properties in netcurl:
$curlRequest =
(new CurlWrapper())
->setConfig((new WrapperConfig())->setOptions([CURLOPT_USERAGENT => 'ExternalClientName']))
->request(
sprintf('https://ipv4.netcurl.org/?func=%s', __FUNCTION__)
);... or a less complex request:
$wrapperConfig = new WrapperConfig();
$wrapperConfig->setOptions([CURLOPT_USERAGENT => 'ExternalClientName']);
$curlWrapper = new CurlWrapper();
$curlWrapper->setConfig($wrapperConfig);
$curlWrapper->request(sprintf('https://ipv4.netcurl.org/?func=%s', __FUNCTION__));MODULE_CURL is not completed yet, so this is examples used when the curlwrapper is called directly. More information will come soon.
Unspoofable Client & Self configuration
For v6.0 there's been a spoof protection placed in the core code. In all versions before 6.0.25, netcurl prevented its usage from "abuse" in the form of User-Agent hijacking. When a User-Agent has been set within netcurl, netcurl has forced core components to be logged in the user agent together with the user defined agent name. As of 6.0.25, as mentioned, a spoofable flag has been added to the setUserAgent parts so the user defined string is the only visible in the http requests. As of 6.1.0, this protection is entirely removed and the core curlops are set entirely free with the help of configuration class.
Global useragent handling
Normally user-agent setups is being done via internal WrapperConfig setups. However, this can be done via a global static variable in the WrapperConfig too. By using WrapperConfig::setSignature(), you can push a user agent on a global level without the need of an instance. This value has higher priority (currently at least) than the internal value. This simplifies client identification.
However, to make it harder to abuse this, it can also be disabled like this:
define('WRAPPERCONFIG_NO_SIGNATURE', true);