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.

Solution 1

trigger_error()

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

Solution 2

Generally speaking you can flag a method as deprecated to give your users warnings about code that will not work in future versions. I think the best way is to use trigger_error along with some phpdoc.

/**
 * @deprecated
 *
 * @return $this
 */
public function oldMethod()
{
    trigger_error('Method ' . __METHOD__ . ' is deprecated', E_USER_DEPRECATED);

    return $this;
}

The @deprecated phpdoc is important because many IDEs like PHPStorm recognise it and strike the method name if you try to use it, so you notice that is deprecated before actually running your code.

It will look more or less like this:

Beside the phpdoc you can make sure the user gets a warning by triggering the right error at runtime. Just make sure you use the right constant (i.e. E_USER_DEPRECATED).

E_DEPRECATED is instead used internally by PHP thus you should not be using it. More information here.

Solution 3

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

Solution 4

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.

Solution 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.

View more solutions

Comments

[Milan Babuškov]

It is not my function, but PHP's built in ibase_* functions like ibase_query for example.

[Milan Babuškov]

It is not my function, but PHP's built in ibase_* functions like ibase_query for example.

[emont01]

You may consider using E_USER_DEPRECATED for PHP 5.3.x and later versions