PHP MySQL to MySQLi migration shim library

Page contents

Purpose

Seamlessly redefines deprecated or missing mysql_ functions and MYSQL_ constants and calls the corresponding mysqli_ functions for PHP5.5+.

Moved to GitHub

The development of this library has moved to GitHub since december 2016. Information here may be outdated and this page is only here for reference purposes. Please visit the project at GitHub to get recent information.

Project goal

The goal is to have a library that emulates ALL the functions and that returns the SAME data as the original mysql_ versions.

Please share and improve, mail me if you have improved it and like to share your work here.

Problem

As of PHP5.5 the original mysql extension for PHP and its provided procedural functions for PHP are marked as deprecated and are removed in PHP 7.0.0.

Websites and other PHP enabled projects that use these functions (like mysql_connect, mysql_query etc.) may not work properly after this change in PHP. This because the required functions now trigger an E_DEPRECATED error in PHP 5.5 and in PHP 7.0.0 even cause fatal errors as the functions do not exist anymore, breaking the bridge between your code and your database.

Solutions

How the library works

The library defines many mysql_ functions that do not have any corresponding mysqli_ alternative, by combining mysqli_ functionality or by fiddling in other ways.

Good - benefits, features and things you get in return

Bad - pitfalls, problems and things to take in to consideration

Usage

The usage is targeted to be simple. In short: download the library to your source directory, disable the MySQL extension, make sure the MySQLi extension is there in it's place and then include the library in the top of your source code.

Then continue with your PHP project as if PHP never dropped their MySQL functions.

Disable the MySQL extension

For PHP below version 7.0.0 you need to disable the MySQL extension in PHP - if it is enabled. To check if it is enabled, put this into a .php file and browse to it with a web browser, then check for the MySQL extension on the page:


<?php echo phpinfo(); ?>

To disable MySQL extension in Debian Jessie 8.3 (Linux) for example you can go to /etc/php5/mods-available with a root terminal and rename the file mysql.ini to mysql.ini.OFF

On other systems you can edit the php.ini file and comment out the line:

extension=mysql.so

So it looks like this:

; extension=mysql.so

Make sure that the MySQLi extension is enabled and working too - it should show up in phpinfo(); too.

Usage of the library

The library is a standard .php-file that you include into the top of the source:

<?php require_once("mysql-shim/mysql-shim.php"); ?>

You may place the file in a directory covered by the global include paths stated in the php.ini file:

	include_path = ".:/path/to/directory/where/mysql-shim.php/is/located:/usr/lib/php"
	

This way you only need one copy of the library located in one of the directories in the include_path. You still need to include it though, using require_once() as stated above.

Alternative usage - auto_prepend

You don't need to explicitly include the library in each script (when you're working with a large codebase, and possibly one you've not written yourself this can be something of a problem). An alternative solution is use an auto_prepend file.

In php.ini:

	auto_prepend_file=/path/to/mysql-shim.php
	

or in apache's httpd.conf or .htaccess:

	php_value auto_prepend_file /path/to/mysql-shim.php
	

Alternative usage - rename functions

If do not have write access to the PHP configuration on the server or something else prevents you from disabling the MySQL extension then you do not have so many choices but to rename all the mysql_ functions in the library and in your code base - or rewrite the code base to use the new mysqli_ functions.

If the code base is not too big you could replace "mysql_" with "mysql_shim_" for example, to avoid name collision between the functions. You do also need to rename the MYSQL_ constants.

Testing

As of february 2016 I have written a testing script to test the library. It walks through the functions in the library and runs them to check if the return values and the return values upon errors are correct according to PHP.net manual.

Note that this script does live tests - it creates databases, tables, table rows, deletes databases and so on. The same words for the library goes for the testing script - it has been developed to be safe to use, but errors may exist. So if you want to be really safe then run the test file on a database server containing data you don't mind losing.

You are of course welcome to test the library yourself and also to modify both the library and the testing script. Please send me an e-mail if you find anything interesting - like errors. Below are usage instructions and links to the testing script.

Usage of the testing script

Place the testing script in the same directory as the library (but not in an outside world-accessible directory just to be safe)

Make sure that the MySQL extension is disabled and that the MySQLi extension is enabled

Go to the directory when you placed the testing script and the library with a terminal/console

Run it with PHP, replace credential placeholders with root username and password, or an MySQL user that has the same MySQL privileges:

/usr/bin/php mysql-shim.test.php -h localhost -u mysql-root-username -p mysql-root-password

If it works it runs through all the functions and does live tests.

Parameters for the testing script

You may pass the following parameters to the testing script:

-h [database server hostname, defaults to localhost]
-u [database username, defaults to root]
-p [database password, defaults to empty string]
-d [name of database to run in tests - will be re-created, deleted etc, defaults to testdatabase12345]
-? to get help
		

License

Public domain, edit and share without my permission. Contain comments from PHP.net that may rule under different licenses. I do not take any responsibility and I am not liable for any damage caused through use of the code on this site.

Sites and projects in the world using the library

Are you using the library? Drop me a mail with the address to your project and I may include it in the list. You may also supply a short comment to publish if you like to.

Contributors

Contact

You may send me a mail using: dotpointer-at-gmail.com

Downloads

Please visit the project page at GitHub: https://github.com/dotpointer/mysql-shim/ to download files that are up to date.

Counter