mysqli::options does not respect error reporting configuration

[morozov]

Description

The following code:

<?php

$mysqli = new mysqli();
$value = $mysqli->options(-1, 'invalid_option');
var_dump($value);

Resulted in this output:

bool(false)

But I expected this output instead:

mysqli_sql_exception

Per the mysqli::options documentation,

If mysqli error reporting is enabled (MYSQLI_REPORT_ERROR) and the requested operation fails, a warning is generated. If, in addition, the mode is set to MYSQLI_REPORT_STRICT, a mysqli_sql_exception is thrown instead.

Per the mysqli_driver::$report_mode documentation, this should be the default behavior:

PHP 8.1. The default value is now MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT. Previously, it was MYSQLI_REPORT_OFF.

For reference, mysqli::set_charset behaves as expected:

<?php

$mysqli = new mysqli('127.0.0.1', 'root', 'Passw0rd!');
try {
    $mysqli->set_charset('garbage');
} catch (mysqli_sql_exception $e) {
    echo 'Caught exception: ',  $e->getMessage(), "\n";
}
// Caught exception: Invalid character set was provided

PHP Version

PHP 8.5.2 (cli) (built: Jan 13 2026 21:40:53) (NTS)
Copyright (c) The PHP Group
Built by Shivam Mathur
Zend Engine v4.5.2, Copyright (c) Zend Technologies
    with Xdebug v3.5.0, Copyright (c) 2002-2025, by Derick Rethans
    with Zend OPcache v8.5.2, Copyright (c), by Zend Technologies

Operating System

macOS

[kamil-tekiela]

Thanks for the issue report.

I can see how the behaviour can be confusing, especially when you compare it to set_charset. However, $mysqli->options(-1, 'invalid_option'); is not a failure. The operation was successful, but the option you specified isn't one of the options available, and so it has no effect. As opposed to setting an invalid charset, providing a non-existent option isn't a cause for concern from the standpoint of the API. It is a programmer's error, so maybe it makes sense to raise a warning or a ValueError, but definitely not a mysqli_sql_exception.

[morozov]

The operation was successful, but the option you specified isn't one of the options available, and so it has no effect.

What's the definition of success here and why does a "successful" call return false?

[kamil-tekiela]

The operation was successful, but the option you specified isn't one of the options available, and so it has no effect.

What's the definition of success here?

Whether the value was changed. As far as I know, the only one that can fail is MYSQLI_SET_CHARSET_NAME. All other ones will either set whatever value you provide or silently ignore out-of-bounds values. In other words, whether or not mysqlnd accepted the new value.

[morozov]

Whether the value was changed.

So in my case, it's failure because the call to mysqli::options() didn't affect the connection.

[kamil-tekiela]

Whether the value was changed.

So in my case, it's failure because the call to mysqli::options() didn't affect the connection.

No, it's just dead code. The same would happen if you didn't call this function.

[morozov]

No, it's just dead code.

It's not dead code. Dead code is the code that is never executed.

The same would happen if you didn't call this function.

That's the thing. I did intend to call this function to modify the connection. If I didn't want to modify it, I wouldn't make the call. If a function is called with invalid parameters, it should report an error, not silently ignore the call.

[kamil-tekiela]

That's the thing. I did intend to call this function to modify the connection. If I didn't want to modify it, I wouldn't make the call. If a function is called with invalid parameters, it should report an error, not silently ignore the call.

Which is why I agree that a Value Error can be helpful here.

[morozov]

so maybe it makes sense to raise a warning or a ValueError, but definitely not a mysqli_sql_exception.

I'm sorry, I missed this part in the original response. I don't have an opinion on which exactly exception class is thrown, I'm only concerned about exception not being thrown at all.

As for the choice of exception class, what's the difference? Is ValueError more appropriate because it's a programmer's error? I.e. unlike mysqli_sql_exception it's not meant to be caught and handled? That would make sense.

[kamil-tekiela]

IMHO neither is supposed to be caught. But you are correct Errors are not supposed to be caught. Exceptions can be caught if needed.

The main difference is where the difference comes from. mysqli_sql_exception is reserved for errors coming from the MySQL server or from the mysqlnd client, not from mysqli extension.