MySQL ext/mysql Converter Tool

About

This is the MySQL ext/mysql Converter Tool. The tool can be used to convert PHP files using the PHP MySQL extension (ext/mysql) to make the scripts use the PHP MySQLi extension. The PHP MySQL extension has been designed to work with the MySQL Server up to version 4.1.0. Some features introduced later, for example prepared statements, are not supported by the extension. To use these features, you have to use the PHP MySQLi extension. This tool helps you to convert your existing scripts from the old MySQL extension to the new MySQLi extension.

The tool uses a simple approach to map mysql_*-functions to their mysqli_*-counterparts. All mysql_*-functions can be converted automatically. The generated code will run out of the box. However, the tool does not take context and runtime information into account when it does the conversion. This can lead to situations where the tool is not sure if the generated code is semantically identical to the original code in all ways. If this happens, a warning will the thrown and you will be requested to check the automatically generated tool

The tool has been originally developed by MySQL AB. It is released under the terms of the PHP Licence 3.0. It is no longer maintained by MySQL, but lives on as a public github repository.

Where can I get more information?

Please consult the wiki for additional information.

What cannot be converted automatically?

Use the function MySQLConvertTool_Converter::getUnsupportedFunctions() to get a list of all functions which cannot be converted automatically. Currently, the tool does not support the conversion of the following, rarely used functions:

mysql_result() -- Note: it converts to mysqli_result() and suggests a mysqli_result() userland definition, as the mysqli extension does not have a true alternative to mysql_result().
mysql_fetch_field2()

All other mysql_*-functions can be converted automatically.

What else does this do that might affect me?

All functions are converted to lowercase
If your PHP version has short tags disabled, code using short tags will be skipped. This is a limitation of the tokenizer extension

What is considered to be a warning?

The converter tool works stateless. It does not take any context or runtime information into account. It does nothing but analyze existing mysql_*-functions and tries to translate them into their mysqli_*-counterparts. Most expressions can be translated into semantically identical expressions using this approach. But there are limits. Whenever such a limit gets hit, the tool throws an error and asks you to check your code manually.

A simple example of an expression which cannot be converted without context information is mysql_error(). Consider the following PHP code:

if (!mysql_connect())
    die(sprintf("[%d] %s\n", mysql_errno(), mysql_error()));

The author of the code relies on the default connection feature. mysql_errno() can be called with or without a link identifier. The function accepts one optional parameter:

mysql_errno ( [resource link_identifier] )

The mysqli_errno() counterpart of the MySQLi extension must be provided with a link identifier.

mysqli_errno ( mysqli link )

The tool is clever enough to store the return value of mysql_connect() [mysqli_connect()] in a global variable and pass the global variable to the mysqli_errno() function call. But if mysqli_connect() fails and does not return a link identifier, mysqli_errno() will be called with an invalid parameter. Again, the conversion tool is clever enough to add a conditional expression to ensure that the generated code behaves like the original code, but this is considered as a "hack" and a "warning" will be thrown. The warning tells you to check manually that the generated code is semantically identical to the original code. You could, for example, have a mysql_errno() somewhere in your code without a preceding mysql_connect(). That does not make too much sense, but it could be. As the converter tool does not consider any state and context information it cannot detect such problems. When the mysql_errno() call gets converted no information is available if it is preceded by a mysql_connect() call or not.

Yes, we think it is worth to throw a warning. You can call it picky. Most of the warnings can be safely ignored. But we give no warranty. Check your code manually!

There are many more situations when a warning gets thrown. For example, mysql_fetch_field() will be replaced by a semantically identical expression, but the replacement is a huge, ugly piece of code which you should streamline.

Can I safely ignore the warnings?

No, you are strongly requested to check the generated code manually. It is likely that the generated code works as expected in most cases, but not in all cases!

What is considered to be an error?

The tool considers a conversion as failed and all warnings as errors if the number of converted functions differs from the number of mysql_*-functions found in the given PHP source.

Where can I learn more about limitations?

The converter tool comes with more than 50 "real-life" test cases. At least one test case exists for every mysql_-function which can be handled by the tool. If a test case contains code which cannot be converted automatically into a semantically identical mysqli*-function, the test case name is preceded with the word "FAILURE". Check the test cases in the folder UnitTests/Converter/TestCode for details.

Help