Improve remaining stubs with `= UNKNOWN` where possible

[TysonAndre]

Related to #23

See the discussion in https://externals.io/message/111878

Currently, for ldap_sasl_bind, null is coerced to the empty string for string $bind_rdn = UNKNOWN with strict_types=0, and is a TypeError in strict_types=1, and the stubs use UNKNOWN.

If it's safe to change the default to the empty string or null, it'd be an improvement to do so - I'm not familiar with the ldap implementation (etc) in detail.

Mentioned by @MCMic - I assume it'll be possible until 8.0 is stable if done in a backwards compatible way

EDIT: It seems like most other things are correct other than ldap. Documenting the reasons why UNKNOWN had to be used in a line comment above the stub would help contributors or PECL maintainers writing new stubs. E.g. https://www.php.net/dateperiod has multiple signatures.

ext/date/php_date.stub.php
402:    public function __construct($start, $interval = UNKNOWN, $end = UNKNOWN, $options = UNKNOWN) {}

ext/dba/dba.stub.php
12:function dba_popen($path, $mode, $handlername = UNKNOWN, ...$handler_parameters) {}
21:function dba_open($path, $mode, $handlername = UNKNOWN, ...$handler_parameters) {}
37:function dba_fetch($key, $skip, $handle = UNKNOWN): string|false {}

ext/gd/gd.stub.php
126:function imagegd(GdImage $im, string $to = UNKNOWN): bool {}
128:function imagegd2(GdImage $im, string $to = UNKNOWN, int $chunk_size = UNKNOWN, int $type = UNKNOWN): bool {}

ext/imap/php_imap.stub.php
8:function imap_open(string $mailbox, string $user, string $password, int $options = 0, int $n_retries = 0, array $params = UNKNOWN) {}
30:function imap_headerinfo($stream_id, int $msg_no, int $from_length = 0, int $subject_length = 0, string $default_host = UNKNOWN): stdClass|false {}
36:function imap_header($stream_id, int $msg_no, int $from_length = 0, int $subject_length = 0, string $default_host = UNKNOWN): stdClass|false {}
151:function imap_append($stream_id, string $folder, string $message, string $options = UNKNOWN, string $internal_date = UNKNOWN): bool {}
183:function imap_sort($stream_id, int $criteria, int $reverse, int $options = 0, string $search_criteria = UNKNOWN, string $charset = UNKNOWN): array|false {}
261:function imap_mail(string $to, string $subject, string $message, string $additional_headers = UNKNOWN, string $cc = UNKNOWN, string $bcc = UNKNOWN, string $rpath = UNKNOWN): bool {}

ext/intl/php_intl.stub.php
31:function intlcal_set(IntlCalendar $calendar, int $year, int $month, int $dayOfMonth = UNKNOWN, int $hour = UNKNOWN, int $minute = UNKNOWN, int $second = UNKNOWN): bool {}
108:function intlgregcal_create_instance($timeZoneOrYear = UNKNOWN, $localeOrMonth = UNKNOWN, $dayOfMonth = UNKNOWN, $hour = UNKNOWN, $minute = UNKNOWN, $second = UNKNOWN): ?IntlGregorianCalendar {}

ext/ldap/ldap.stub.php
7:function ldap_connect(string $hostname = UNKNOWN, int $port = 389, string $wallet = UNKNOWN, string $wallet_passwd = UNKNOWN, int $authmode = GSLC_SSL_NO_AUTH) {}
10:function ldap_connect(string $hostname = UNKNOWN, int $port = 389) {}
23:function ldap_bind($link_identifier, string $bind_rdn = UNKNOWN, string $bind_password = UNKNOWN): bool {}
29:function ldap_bind_ext($link_identifier, string $bind_rdn = UNKNOWN, string $bind_password = UNKNOWN, array $servercontrols = []) {}
33:function ldap_sasl_bind($link, string $binddn = UNKNOWN, string $password = UNKNOWN, string $sasl_mech = UNKNOWN, string $sasl_realm = UNKNOWN, string $sasl_authc_id = UNKNOWN, string $sasl_authz_id = UNKNOWN, string $props = UNKNOWN): bool {}
88:function ldap_first_attribute($link_identifier, $result_entry_identifier, int $dummy_ber = UNKNOWN): string|false {}
94:function ldap_next_attribute($link_identifier, $result_entry_identifier, int $dummy_ber = UNKNOWN): string|false {}

ext/odbc/odbc.stub.php
20:function odbc_execute($result_id, array $parameters_array = UNKNOWN): bool {}
34:function odbc_exec($connection_id, string $query, int $flags = UNKNOWN) {}
41:function odbc_do($connection_id, string $query, int $flags = UNKNOWN) {}
58:function odbc_fetch_row($result_id, int $row_number = UNKNOWN): bool {}
120:function odbc_error($connection_id = UNKNOWN): string {}
123:function odbc_errormsg($connection_id = UNKNOWN): string {}
132:function odbc_tables($connection_id, ?string $qualfier = null, string $owner = UNKNOWN, string $name = UNKNOWN, string $table_types = UNKNOWN) {}
138:function odbc_columns($connection_id, ?string $qualifier = null, string $owner = UNKNOWN, string $table_name = UNKNOWN, string $column_name = UNKNOWN) {}
157:function odbc_procedurecolumns($connection_id, ?string $qualifier = null, string $owner = UNKNOWN, string $proc = UNKNOWN, string $column = UNKNOWN) {}
163:function odbc_procedures($connection_id, ?string $qualifier = null, string $owner = UNKNOWN, string $name = UNKNOWN) {}

ext/pdo_pgsql/pgsql_driver.stub.php
8:    public function pgsqlCopyFromArray(string $table_name, array $rows, string $delimiter = "\t", string $null_as = "\\\\N", string $fields = UNKNOWN) {}
11:    public function pgsqlCopyFromFile(string $table_name, string $filename, string $delimiter = "\t", string $null_as = "\\\\N", string $fields = UNKNOWN) {}
14:    public function pgsqlCopyToArray(string $table_name, string $delimiter = "\t", string $null_as = "\\\\N", string $fields = UNKNOWN) {}
17:    public function pgsqlCopyToFile(string $table_name, string $filename, string $delimiter = "\t", string $null_as = "\\\\N", string $fields = UNKNOWN) {}

ext/pgsql/pgsql.stub.php
// EDIT: Never mind, the $connection can be omitted to use the default connection. This is discouraged in docs.
// https://www.php.net/manual/en/function.pg-query-params.php
45:function pg_parameter_status($connection, string $param_name = UNKNOWN): string|false {}
54:function pg_query($connection, string $query = UNKNOWN) {}
61:function pg_exec($connection, string $query = UNKNOWN) {}
68:function pg_query_params($connection, $query, array $params = UNKNOWN) {}
74:function pg_prepare($connection, string $stmt_name, string $query = UNKNOWN) {}
81:function pg_execute($connection, $stmt_name, array $params = UNKNOWN) {}
159:function pg_fetch_result($result, $row_number, string|int $field = UNKNOWN): string|false|null {}
166:function pg_result($result, $row_number, string|int $field = UNKNOWN): string|false|null {}
199:function pg_field_prtlen($result, $row_number, string|int $field = UNKNOWN): int|false {}
206:function pg_fieldprtlen($result, $row_number, string|int $field = UNKNOWN): int|false {}
212:function pg_field_is_null($result, $row_number, string|int $field = UNKNOWN): int|false {}
219:function pg_fieldisnull($result, $row_number, string|int $field = UNKNOWN): int|false {}
249:function pg_lo_create($connection = UNKNOWN, $large_object_id = UNKNOWN): string|int|false {}
256:function pg_locreate($connection = UNKNOWN, $large_object_id = UNKNOWN): string|int|false {}
262:function pg_lo_unlink($connection, $large_object_id = UNKNOWN): bool {}
269:function pg_lounlink($connection, $large_object_id = UNKNOWN): bool {}
276:function pg_lo_open($connection, $large_object_id = UNKNOWN, string $mode = UNKNOWN) {}
284:function pg_loopen($connection, $large_object_id = UNKNOWN, string $mode = UNKNOWN) {}
328:function pg_lo_import($connection, $filename = UNKNOWN, $large_object_id = UNKNOWN): string|int|false {}
337:function pg_loimport($connection, $filename = UNKNOWN, $large_object_id = UNKNOWN): string|int|false {}
345:function pg_lo_export($connection, $large_object_id = UNKNOWN, $filename = UNKNOWN): bool {}
354:function pg_loexport($connection, $large_object_id = UNKNOWN, $filename = UNKNOWN): bool {}
366:function pg_set_error_verbosity($connection, int $verbosity = UNKNOWN): int|false {}
369:function pg_set_client_encoding($connection, string $encoding = UNKNOWN): int {}
375:function pg_setclientencoding($connection, string $encoding = UNKNOWN): int {}
390:function pg_put_line($connection, string $query = UNKNOWN): bool {}
399:function pg_escape_string($connection, string $data = UNKNOWN): string {}
402:function pg_escape_bytea($connection, string $data = UNKNOWN): string {}
407:function pg_escape_literal($connection, string $data = UNKNOWN): string|false {}
410:function pg_escape_identifier($connection, string $data = UNKNOWN): string|false {}

ext/reflection/php_reflection.stub.php
326:    public function getStaticPropertyValue(string $name, mixed $default = UNKNOWN) {}
386:    public function setValue(mixed $objectOrValue, mixed $value = UNKNOWN) {}

ext/session/session.stub.php
46:function session_set_save_handler($open, $close = UNKNOWN, callable $read = UNKNOWN, callable $write = UNKNOWN, callable $destroy = UNKNOWN, callable $gc = UNKNOWN, callable $create_sid = UNKNOWN, callable $validate_sid = UNKNOWN, callable $update_timestamp = UNKNOWN): bool {}

ext/soap/soap.stub.php
16:    public function __construct(string $namespace, string $name, mixed $data = UNKNOWN, bool $mustunderstand = false, string|int|null $actor = null) {}

ext/spl/spl_iterators.stub.php
77:    public function getSubIterator(int $level = UNKNOWN) {}
119:    public function __construct($iterator, string $class_name = UNKNOWN) {}

ext/standard/basic_functions.stub.php
111:function array_walk(array|object &$input, callable $callback, mixed $argument = UNKNOWN): bool {}
113:function array_walk_recursive(array|object &$input, callable $callback, mixed $argument = UNKNOWN): bool {}
158:function array_keys(array $array, mixed $filter_value = UNKNOWN, bool $strict = false): array {}
537:function assert_options(int $what, $value = UNKNOWN): array|object|int|string|null {}
// not very useful to change, max=mt_getrandmax() and argument count must be 0 or 2
1185:function rand(int $min = UNKNOWN, int $max = UNKNOWN): int {}
1187:function mt_rand(int $min = UNKNOWN, int $max = UNKNOWN): int {}
1218:function stream_context_set_option($context, array|string $wrapper_or_options, ?string $option_name = null, mixed $value = UNKNOWN): bool {}
1233:function stream_filter_prepend($stream, string $filtername, int $read_write = 0, mixed $params = UNKNOWN) {}
1239:function stream_filter_append($stream, string $filtername, int $read_write = 0, mixed $params = UNKNOWN) {}

ext/xmlwriter/php_xmlwriter.stub.php
83:function xmlwriter_write_dtd_entity(XMLWriter $xmlwriter, string $name, string $content, bool $isparam = false, string $publicId = UNKNOWN, string $systemId = UNKNOWN, string $ndataid = UNKNOWN): bool {}

[kocsismate]

@TysonAndre I've been doing this task for quite a long while (we were above 300 UNKNOWN default values initially), and I'd say most of the remaining UNKNOWN defaults cannot be changed (easily) in PHP 8.0, or the change isn't worth, mostly because of the following reasons:

• Sometime we just can't add a new default value, e.g. in case of mixed parameters, like in stream_filter_prepend()
• The function signature is inherently overloaded (e.g. I wanted to refactor DatePeriod::__construct() not long ago in php/php-src@9adde72#diff-7b738accc3d60f74c259da18588ddc5dR4128 but neither Nikita nor Derick found it useful. But most of the listed ext/pgsql functions are similar)

On the other hand, I haven't checked ext/dba and ext/imap since I try to ignore these extensions, and it seems to me that both ext/ldap and ext/odbc could benefit from another round of review :) And as far as I see, the most remaining UNKNOWN defaults could be fixed via deprecations (either on the function or on the parameter level) in a next version.

[MCMic]

I’m working on a PR for ext/ldap

[MCMic]

See php/php-src#6153

[kocsismate]

For ext/odbc see php/php-src#6154

[kocsismate]

For ext/pdo_pgsql: php/php-src#6159

And I'll directly commit the fix for xmlwriter_write_dtd_entity(), since its ZPP already has been fixed recently, but I only updated the stub for its method counterpart.

[Girgias]

I'll try to handle IMAP as I'm already working on it

[kocsismate]

Zend functions as well as SAPI functions are not included in this list, but I've just submitted two PRs for them to fix the last remaining UNKNOWN default values (where possible):

• Improve default value handling of Exception constructors php-src#6166
• Fix UNKNOWN default value of apache_note() php-src#6167

[dtakken]

I tried my hand at the rand() and rand_mt() functions:

php/php-src#6184

[nikic]

We're done here, right? I think everything either has an open PR or is intentional.

[kocsismate]

@nikic I also think we're done. The only functions I haven't looked at are the ones in ext/dba, but apart from that we should be good.

I'm now linking my last PR: php/php-src#6176

[nikic]

Okay, I'm closing this one then. I looked at ext/dba and think the UNKNOWN in dba_open/dba_popen could be made nullable, but given the state of that code, I don't think it's worth the bother.