Update stubs for PHP 7.2 (JetBrains#662)

* WI-37330 Update stubs for PHP 7.2

https://github.com/php/php-src/blob/php-7.2.0beta1/UPGRADING

Core/Core.php

@@ -152,7 +152,7 @@ function strncasecmp ($str1, $str2, $len) {}
  * false.
  * @since 4.0
  * @since 5.0
- * @deprecated 7.2
+ * @deprecated 7.2.0 Use a foreach loop instead.
  */
 function each (array &$array) {}
 
@@ -750,7 +750,7 @@ function get_defined_vars () {}
  * @return string a unique function name as a string, or false on error.
  * @since 4.0.1
  * @since 5.0
- * @deprecated 7.2
+ * @deprecated 7.2.0 Use anonymous functions instead.
  */
 function create_function ($args, $code) {}
 

PhpStormStubsMap.php

@@ -3547,6 +3547,7 @@ final class PhpStormStubsMap
   'oci_parse' => 'oci8/oci8.php',
   'oci_password_change' => 'oci8/oci8.php',
   'oci_pconnect' => 'oci8/oci8.php',
+  'oci_register_taf_callback' => 'oci8/oci8.php',
   'oci_result' => 'oci8/oci8.php',
   'oci_rollback' => 'oci8/oci8.php',
   'oci_server_version' => 'oci8/oci8.php',
@@ -3557,6 +3558,7 @@ final class PhpStormStubsMap
   'oci_set_module_name' => 'oci8/oci8.php',
   'oci_set_prefetch' => 'oci8/oci8.php',
   'oci_statement_type' => 'oci8/oci8.php',
+  'oci_unregister_taf_callback' => 'oci8/oci8.php',
   'ocibindbyname' => 'oci8/oci8.php',
   'ocicancel' => 'oci8/oci8.php',
   'ocicloselob' => 'oci8/oci8.php',
@@ -4157,6 +4159,10 @@ final class PhpStormStubsMap
   'snmpwalk' => 'snmp/snmp.php',
   'snmpwalkoid' => 'snmp/snmp.php',
   'socket_accept' => 'sockets/sockets.php',
+  'socket_addrinfo_bind' => 'sockets/sockets.php',
+  'socket_addrinfo_connect' => 'sockets/sockets.php',
+  'socket_addrinfo_explain' => 'sockets/sockets.php',
+  'socket_addrinfo_lookup' => 'sockets/sockets.php',
   'socket_bind' => 'sockets/sockets.php',
   'socket_clear_error' => 'sockets/sockets.php',
   'socket_close' => 'sockets/sockets.php',

exif/exif.php

@@ -5,9 +5,10 @@
 /**
  * Reads the EXIF headers from JPEG or TIFF
  * @link https://php.net/manual/en/function.exif-read-data.php
- * @param string $filename <p>
- * The name of the image file being read. This cannot be an
- * URL.
+ * @param string|resource $stream <p>
+ * The location of the image file. This cannot be an URL.
+ * Since 7.2.0 this can either be a path to the file (stream wrappers are also supported as usual)
+ * or a stream resource.
  * </p>
  * @param string $sections [optional] <p>
  * Is a comma separated list of sections that need to be present in file
@@ -77,7 +78,7 @@
  * @since 4.2.0
  * @since 5.0
  */
-function exif_read_data ($filename, $sections = null, $arrays = false, $thumbnail = false) {}
+function exif_read_data ($stream, $sections = null, $arrays = false, $thumbnail = false) {}
 
 /**
  * Alias of <b>exif_read_data</b>
@@ -88,7 +89,7 @@ function exif_read_data ($filename, $sections = null, $arrays = false, $thumbnai
  * @param $thumbnail [optional]
  * @since 4.0.1
  * @since 5.0
- * @deprecated 7.2
+ * @deprecated 7.2.0 Use {@see exif_read_data()} instead.
  */
 function read_exif_data ($filename, $sections = null, $arrays = false, $thumbnail = false) {}
 
@@ -108,9 +109,10 @@ function exif_tagname ($index) {}
 /**
  * Retrieve the embedded thumbnail of a TIFF or JPEG image
  * @link https://php.net/manual/en/function.exif-thumbnail.php
- * @param string $filename <p>
- * The name of the image file being read. This image contains an
- * embedded thumbnail.
+ * @param string|resource $stream <p>
+ * The location of the image file. This cannot be an URL.
+ * Since 7.2.0 this can either be a path to the file (stream wrappers are also supported as usual)
+ * or a stream resource.
  * </p>
  * @param int $width [optional] <p>
  * The return width of the returned thumbnail.
@@ -127,7 +129,7 @@ function exif_tagname ($index) {}
  * @since 4.2.0
  * @since 5.0
  */
-function exif_thumbnail ($filename, &$width = null, &$height = null, &$imagetype = null) {}
+function exif_thumbnail ($stream, &$width = null, &$height = null, &$imagetype = null) {}
 
 /**
  * Determine the type of an image

gd/gd.php

@@ -844,7 +844,8 @@ function imagecopyresampled ($dst_image, $src_image, $dst_x, $dst_y, $src_x, $sr
 function imagerotate ($image, $angle, $bgd_color, $ignore_transparent = null) {}
 
 /**
- * Should antialias functions be used or not
+ * Should antialias functions be used or not. <br/>
+ * Before 7.2.0 it's only available if PHP iscompiled with the bundled version of the GD library.
  * @link https://php.net/manual/en/function.imageantialias.php
  * @param resource $image 
  * @param bool $enabled <p>
@@ -1129,7 +1130,8 @@ function imagejpeg ($image, $filename = null, $quality = null) {}
 function imagewbmp ($image, $filename = null, $foreground = null) {}
 
 /**
- * Output GD image to browser or file
+ * Output GD image to browser or file. <br/>
+ * Since 7.2.0 allows to output truecolor images.
  * @link https://php.net/manual/en/function.imagegd.php
  * @param resource $image 
  * @param string $filename [optional] <p>

gmp/gmp.php

@@ -532,6 +532,7 @@ function gmp_sign ($a) {}
  * @return resource|GMP A random GMP number.
  * @since 4.0.4
  * @since 5.0
+ * @deprecated 7.2.0 Use {@see gmp_random_bits()} or {@see gmp_random_range()} instead.
  */
 function gmp_random ($limiter = 20) {}
 

hash/hash.php

@@ -57,7 +57,8 @@ function hash_file ($algo, $filename, $raw_output = false) {}
  * Generate a keyed hash value using the HMAC method
  * @link https://php.net/manual/en/function.hash-hmac.php
  * @param string $algo <p>
- * Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) See <b>hash_algos</b> for a list of supported algorithms.
+ * Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) See <b>hash_algos</b> for a list of supported algorithms.<br/>
+ * Since 7.2.0 usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) was disabled.
  * </p>
  * @param string $data <p>
  * Message to be hashed.
@@ -80,7 +81,8 @@ function hash_hmac ($algo, $data, $key, $raw_output = false) {}
  * Generate a keyed hash value using the HMAC method and the contents of a given file
  * @link https://php.net/manual/en/function.hash-hmac-file.php
  * @param string $algo <p>
- * Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) See <b>hash_algos</b> for a list of supported algorithms.
+ * Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) See <b>hash_algos</b> for a list of supported algorithms.<br/>
+ * Since 7.2.0 usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) was disabled.
  * </p>
  * @param string $filename <p>
  * URL describing location of file to be hashed; Supports fopen wrappers.
@@ -103,7 +105,8 @@ function hash_hmac_file ($algo, $filename, $key, $raw_output = false) {}
  * Initialize an incremental hashing context
  * @link https://php.net/manual/en/function.hash-init.php
  * @param string $algo <p>
- * Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..). For a list of supported algorithms see <b>hash_algos</b>.
+ * Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..). For a list of supported algorithms see <b>hash_algos</b>.<br/>
+ * Since 7.2.0 usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) was disabled.
  * </p>
  * @param int $options [optional] <p>
  * Optional settings for hash generation, currently supports only one option:
@@ -239,12 +242,27 @@ function hash_hmac_algos() {}
 /**
  * Generate a PBKDF2 key derivation of a supplied password
  * @link https://php.net/manual/en/function.hash-pbkdf2.php
- * @param $algo
- * @param $password
- * @param $salt
- * @param $iterations
- * @param $length [optional]
- * @param $raw_output [optional]
+ * @param string $algo <p>
+ * Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) See <b>hash_algos</b> for a list of supported algorithms.<br/>
+ * Since 7.2.0 usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) was disabled.
+ * </p>
+ * @param string $password <p>
+ * The password to use for the derivation.
+ * </p>
+ * @param string $salt <p>
+ * The salt to use for the derivation. This value should be generated randomly.
+ * </p>
+ * @param int $iterations <p>
+ * The number of internal iterations to perform for the derivation.
+ * </p>
+ * @param int $length [optional] <p>
+ * The length of the output string. If raw_output is TRUE this corresponds to the byte-length of the derived key,
+ * if raw_output is FALSE this corresponds to twice the byte-length of the derived key (as every byte of the key is returned as two hexits). <br/>
+ * If 0 is passed, the entire output of the supplied algorithm is used.
+ * </p>
+ * @param bool $raw_output [optional] <p>
+ * When set to TRUE, outputs raw binary data. FALSE outputs lowercase hexits.
+ * </p>
  * @return mixed a string containing the derived key as lowercase hexits unless
  * <i>raw_output</i> is set to <b>TRUE</b> in which case the raw
  * binary representation of the derived key is returned.

intl/intl.php

@@ -6072,9 +6072,10 @@ function intl_error_name($error_code) { }
 define ('IDNA_NONTRANSITIONAL_TO_UNICODE', 32);
 
 /**
- * Use IDNA 2003 algorithm in <b>idn_to_utf8</b> and
- * <b>idn_to_ascii</b>. This is the default.
+ * Use IDNA 2003 algorithm in {@see idn_to_utf8} and
+ * {@see idn_to_ascii}. This is the default.
  * @link https://php.net/manual/en/intl.constants.php
+ * @deprecated 7.2.0 Use {@see INTL_IDNA_VARIANT_UTS46} instead.
  */
 define ('INTL_IDNA_VARIANT_2003', 0);
 

json/json.php

@@ -111,11 +111,12 @@ function json_encode ($value, $options = 0, $depth = 512) {}
  * User specified recursion depth.
  * </p>
  * @param int $options [optional] <p>
- * Bitmask of JSON decode options. Currently only
- * <b>JSON_BIGINT_AS_STRING</b>
- * is supported (default is to cast large integers as floats)
- *
- * <b>JSON_THROW_ON_ERROR</b> when passed this flag, the error behaviour of these functions is changed. The global error state is left untouched, and if an error occurs that would otherwise set it, these functions instead throw a JsonException
+ * Bitmask of JSON decode options:<br/>
+ * {@see JSON_BIGINT_AS_STRING} decodes large integers as their original string value.<br/>
+ * {@see JSON_INVALID_UTF8_IGNORE} ignores invalid UTF-8 characters,<br/>
+ * {@see JSON_INVALID_UTF8_SUBSTITUTE} converts invalid UTF-8 characters to \0xfffd,<br/>
+ * {@see JSON_OBJECT_AS_ARRAY} decodes JSON objects as PHP array, since 7.2.0 used by default if $assoc parameter is null,<br/>
+ * {@see JSON_THROW_ON_ERROR} when passed this flag, the error behaviour of these functions is changed. The global error state is left untouched, and if an error occurs that would otherwise set it, these functions instead throw a JsonException<br/>
  * </p>
  * @return mixed the value encoded in <i>json</i> in appropriate
  * PHP type. Values true, false and
@@ -295,6 +296,12 @@ function json_last_error_msg () {}
  * @link https://php.net/manual/en/json.constants.php
  */
 define ('JSON_ERROR_SYNTAX', 4);
+
+/**
+ * Decodes JSON objects as PHP array.
+ * @since 5.4.0
+ * @link https://php.net/manual/en/json.constants.php
+ */
 define ('JSON_OBJECT_AS_ARRAY', 1);
 define ('JSON_PARSER_NOTSTRICT', 4);
 
@@ -321,11 +328,13 @@ function json_last_error_msg () {}
 define('JSON_UNESCAPED_LINE_TERMINATORS', 2048);
 
 /**
+ * Ignore invalid UTF-8 characters.
  * @since 7.2
  */
 define('JSON_INVALID_UTF8_IGNORE', 1048576);
 
 /**
+ * Convert invalid UTF-8 characters to \0xfffd (Unicode Character 'REPLACEMENT CHARACTER').
  * @since 7.2
  */
 define('JSON_INVALID_UTF8_SUBSTITUTE', 2097152);
@@ -347,6 +356,10 @@ function json_last_error_msg () {}
 define('JSON_ERROR_UTF16',10);
 
 /**
+ * Throws JsonException if an error occurs instead of setting the global error state
+ * that is retrieved with json_last_error() and json_last_error_msg().
+ *
+ * {@see JSON_PARTIAL_OUTPUT_ON_ERROR} takes precedence over JSON_THROW_ON_ERROR.
  * @since 7.3
  */
 define('JSON_THROW_ON_ERROR', 4194304);

mbstring/mbstring.php

@@ -864,7 +864,7 @@ function mb_decode_numericentity ($str, array $convmap, $encoding = null) {}
  * @param string $to <p>
  * The mail addresses being sent to. Multiple
  * recipients may be specified by putting a comma between each
- * address in to. 
+ * address in to.
  * This parameter is not automatically encoded.
  * </p>
  * @param string $subject <p>
@@ -873,9 +873,10 @@ function mb_decode_numericentity ($str, array $convmap, $encoding = null) {}
  * @param string $message <p>
  * The message of the mail.
  * </p>
- * @param string $additional_headers [optional] <p>
- * additional_headers is inserted at
- * the end of the header. This is typically used to add extra
+ * @param string|array $additional_headers [optional] <p>
+ * String or array to be inserted at the end of the email header. <br/>
+ * Since 7.2.0 accepts an array. Its keys are the header names and its values are the respective header values.<br/>
+ * This is typically used to add extra
  * headers. Multiple extra headers are separated with a
  * newline ("\n").
  * </p>
@@ -1325,22 +1326,28 @@ function mbereg_search_getregs () {}
 function mbereg_search_getpos () {}
 
 /**
+ * Get a specific character.
+ * @link https://www.php.net/manual/en/function.mb-chr.php
  * @param int $cp
  * @param string $encoding
- * @return string|false
+ * @return string|false specific character or FALSE on failure.
  * @since 7.2
  */
 function mb_chr($cp, $encoding) {}
 
 /**
+ * Get code point of character
+ * @link https://www.php.net/manual/en/function.mb-ord.php
  * @param string $str
  * @param string $encoding
- * @return int|false
+ * @return int|false code point of character or FALSE on failure.
  * @since 7.2
  */
 function mb_ord($str, $encoding) {}
 
 /**
+ * Scrub broken multibyte strings.
+ * @link https://www.php.net/manual/en/function.mb-scrub.php
  * @param string $str
  * @param string $encoding
  * @return string|false

oci8/oci8.php

@@ -367,6 +367,34 @@ public function free () {}
 
 }
 
+/**
+ * Register a user-defined callback function for Oracle Database TAF.
+ * @link https://www.php.net/manual/en/function.oci-register-taf-callback.php
+ * @param resource $connection <p>
+ * An Oracle connection identifier.
+ * </p>
+ * @param mixed $callbackFn [optional] <p>
+ * A user-defined callback to register for Oracle TAF. It can be a string of the function name or a Closure (anonymous function).<br/>
+ * The interface of a TAF user-defined callback function is as follows:<br/>
+ * <i>userCallbackFn ( resource $connection , int $event , int $type ) : int</i><br/>
+ * See the parameter description and an example on <a href="https://www.php.net/manual/en/oci8.taf.php">OCI8 Transparent Application Failover (TAF) Support</a> page.
+ * </p>
+ * @return bool TRUE on success or FALSE on failure.
+ * @since 7.2.0
+ */
+function oci_register_taf_callback($connection, $callbackFn) {}
+
+/**
+ * Unregister a user-defined callback function for Oracle Database TAF.
+ * @link https://www.php.net/manual/en/function.oci-unregister-taf-callback.php
+ * @param resource $connection <p>
+ * An Oracle connection identifier.
+ * </p>
+ * @return bool TRUE on success or FALSE on failure.
+ * @since 7.2.0
+ */
+function oci_unregister_taf_callback($connection) {}
+
 /**
  * (PHP 5, PECL OCI8 &gt;= 1.1.0)<br/>
  * Associates a PHP variable with a column for query fetches

pcre/pcre.php

@@ -517,6 +517,13 @@ function preg_last_error () {}
  */
 define ('PREG_BAD_UTF8_OFFSET_ERROR', 5);
 
+/**
+ * This flag tells {@see preg_match()} and {@see preg_match_all()}
+ * to include unmatched subpatterns in <b>$matches</b> as NULL values.
+ * Without this flag, unmatched subpatterns are reported as empty strings,
+ * as if they were empty matches. Setting this flag allows to distinguish between these two cases.
+ * @since 7.2.0
+ */
 define ('PREG_UNMATCHED_AS_NULL', 512);
 /**
  * PCRE version and release date (e.g. "7.0 18-Dec-2006").