How to deprecate a function in PHP?

Question

At the team with which I work, we have an old codebase using PHP's ibase_* functions all over the code to communicate with database. We created a wrapper to it that would do something else beside just calling the original function and I did a mass search-replace in the entire code to make sure that wrapper is used instead.

Now, how do we prevent usage of ibase_* functions in the future?

Preferably, I'd like to still have them available, but make it throw a NOTICE or WARNING when it is used.

A solution in pure PHP (not needing to compile a custom version of PHP) is preferred.

Answer 1

I haven't checked it by myself, but found this in my bookmarks: http://wiki.php.net/rfc/e-user-deprecated-warning

Edit: Okay this doesn't work yet - so instead of E_USER_DEPRECATED just use something like E_USER_NOTICE:

<?php
class Foo
{   
    public function __construct()
    {
        trigger_error('Use Bar instead', E_USER_NOTICE);
    }
}

$foo = new Foo()

This will end up with this:

Notice: Use Bar instead in /home/unexist/projects/ingame/svn/foo.php on line 6

Answer 2

trigger_error()

function my_deprecated_function() {
    trigger_error("Deprecated function called.", E_USER_NOTICE);
    // do stuff.
}

Answer 3

If your functions are part of a class, then you could use trigger_error in the constructor to warn of the deprecation.

Alternatively, if the functions are in a single file, then triggering a deprecation warning at the top of the file would show the error whenever the file is included elsewhere.

Finally, you could throw the error on the first line of any of the deprecated functions.

Answer 4

If I understand correct, you want to trigger an error when a built-in PHP function is used? In that case, take a look at the Override Function function.

Answer 5

Instead of raising a runtime warning on usage, you could consider writing a script, that can scan your code base for the use of this function, then generate a report of offending code. Once in a while, run it through.

If you use a version control system, you could set the script as a commit-hook. I would probably recommend a post-hook, that simply sends an email, when a script, containing deprecated functions, is checked in, but if you really want to enforce it, you could have a pre-hook completely prevent anyone from checking it in.