search

php / php-tasks

Tasks that need doing. This is for php-src maintainers. The end-user bug tracker is at https://bugs.php.net/.
27 stars 6 forks source link

Improve remaining stubs with `= UNKNOWN` where possible #24

Closed TysonAndre closed 3 years ago

TysonAndre commented 4 years ago

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 commented 4 years ago

@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:

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 commented 4 years ago

I’m working on a PR for ext/ldap

MCMic commented 4 years ago

See https://github.com/php/php-src/pull/6153

kocsismate commented 4 years ago

For ext/odbc see https://github.com/php/php-src/pull/6154

kocsismate commented 4 years ago

For ext/pdo_pgsql: https://github.com/php/php-src/pull/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 commented 3 years ago

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

kocsismate commented 3 years ago

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):

dtakken commented 3 years ago

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

https://github.com/php/php-src/pull/6184

nikic commented 3 years ago

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

kocsismate commented 3 years ago

@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: https://github.com/php/php-src/pull/6176

nikic commented 3 years ago

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.