====== PHP RFC: Enable strict_types checking for curl_setopt() ======
  * Version: 0.1
  * Date: 2017-04-21
  * Author: Colin O'Dell <colinodell@gmail.com>
  * Author: Sara Golemon <pollita@php.net>
  * Status: Under Discussion
  * First Published at: https://wiki.php.net/rfc/curl_setopt_strict_types

===== Introduction =====

PHP 7.0 introduced strict type checking as part of the [[rfc:scalar_type_hints_v5|scalar types RFC]].  When enabled, PHP will use strict type-checking mode for function calls and return statements in the file.  However, this does not currently apply to the third argument of ''curl_setopt()'' where option values are set.

This RFC proposes that we introduce strict type enforcement inside ''curl_setopt()'' when ''declare(strict_types=1)'' is being used.

===== Background =====

Strict type enforcement does not currently apply to the third argument of ''curl_setopt'' because this argument is heavily overloaded into a mixed type which accepts any of the following:

  * ''bool''
  * ''int''
  * ''string''
  * ''\Callable''
  * ''\Iterable''
  * ''resource<stream>''

However, each particular option always expects a certain type, so it makes sense to enforce these types in strict type checking mode.

(The full list of options and expected value types can be found in the manual: [[http://php.net/manual/en/function.curl-setopt.php]])

Using weak types can also have unintended consequences.  For example, prior to curl 7.28.1, the [[https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html|CURLOPT_SSL_VERIFYHOST]] option (which controls how to verify an SSL certificate's name against the host) had three possible values:

  * ''0'': Allow the connection regardless of the names in the certificate.
  * ''1'': Allow the connection if a common name exists in the certificate.
  * ''2'': Allow the connection if a common name exists in the certificate AND it matches the hostname provided.

However, if a developer wasn't careful and set this option as ''true'', PHP would interpret this as ''1'' and therefore would not check that the certificate matches the hostname (essentially disabling proper hostname validation).

Introducing strict type checks would help prevent these types of issues.

===== Proposal =====

When ''declare(strict_types=1)'' is used, PHP will now check the third argument of ''curl_setopt()'' to ensure it contains the expected type for the given setting.  Checks will be added for the following types:

  * ''bool''
  * ''int''
  * ''string''
  * ''\Callable''
  * ''\Iterable''
  * ''resource<stream>''

Passing the incorrect type while strict type checks are enabled would result in a ''TypeError'' with a message like this:

<blockquote>Argument 3 passed to curl_setopt() must be of type integer, boolean given</blockquote>

This behavior matches existing strict type checking functionality.

===== Backward Incompatible Changes =====

Any existing code using ''curl_setopt()'' with strict type checking enabled will need to be updated if it doesn't provide the proper types.

Code not using strict type checking (or which already passes the proper types) would be unaffected.

===== Proposed PHP Version(s) =====

PHP 7.2

===== RFC Impact =====

These changes would only impact the curl extension.

===== Proposed Voting Choices =====
Should strict type checking be enforced on the third parameter of ''curl_setopt'' when strict type checking is enabled? As it is not a language or syntax change, the vote will pass if 50%+1 vote yes.

===== Patches and Tests =====
The proposed patch can be found here: https://github.com/php/php-src/pull/2495

===== References =====
Mailing list discussion: [[http://marc.info/?l=php-internals&m=149286128912117&w=2]]