Notify user of theme using deprecated code

[Otto42]

Suggestion:
In the event that a theme uses "deprecated" code (basically anything in deprecated.php), set some sort of flag to notify the user on the main wp-admin screen. This would tell him that he needs to look for an upgraded version of his theme.

Further suggestion:
Keep trak of which deprecated functions his theme is using and tell him, along with suggested alternatives (and appropriate codex links), in case he wants to update the theme himself.

[rob1n]

I like it. We should really become more active in "urging" theme developers to use the new API.

[docwhat]

In light of bug #5033, maybe also adding warnings, too, would be helpful? That way a developer/debug mode would show the plugin developer that they shouldn't be using that function?

This is in reference to the thread here:
​http://comox.textdrive.com/pipermail/wp-hackers/2007-October/015570.html

Ciao!

[docwhat]

Okay, to make the patch I submitted to work, the error_reporting needs to change:
From:

  error_reporting(E_ALL ^ E_NOTICE);

To:

  error_reporting(E_ALL ^ E_NOTICE ^ E_USER_NOTICE);

Ciao!

[johnbillion]

docwhat, s/depreciated/deprecated/g

[docwhat]

D'oh!

On the plus side, I've submitted several patches to things like google-sitemaps and sandbox-theme using this patch.

Ciao!

[docwhat]

Spelling Me Hard

[darkdragon]

This is interesting ticket.

If WordPress wishes to maintain backwards compatibility for PHP 4.2+ and provide functions that it uses, then I don't believe WordPress is suddenly going to one day drop the current deprecated functions.

If it is decided that when either WordPress 3.0 comes out to drop deprecated functions, or even some later 2.x version, I think theme authors have had far enough time to update their themes to not use the deprecated functions. Not all deprecated functions are moved to deprecated.php.

I think the argument on wp-hackers was a good one. The better way would be to just have an online web site that checks the theme. However, no web site currently exists that does that.

I would recommend this be closed as won't fix, since throwing user errors for something trivial is a generally bad idea (a big Fatal Error: function does not exist is far better indicator that something is wrong). It is also unlikely to be ignored.

[docwhat]

darkdragon:

I think there are two audiences to consider. End users and theme/plugin developers. A developer should have user errors turned on and should be made aware of potential problems. A user should probably only care when something goes away (creating a Fatal Error).

These sort of features are a user interface where the user is a developer. It helps the developer be more productive and to better understand the platform and how to use it properly.

Ciao!

[darkdragon]

I'm not saying this feature wouldn't be awesome, I'm saying the patch is not awesome. You have a few options other than throwing an user error.

1. Use the file logging (the same used in the wpdb object).
   
2. An API which records which deprecated functions have run, how many times and by what functions (using debug_backtrace since well, if you are debugging then performance isn't an issue, but allow this to be enabled), and allow plugins to output the results.

I would go with the second, since someone who is likely to be debugging would want know. You can name the plugin something like, "Find out if your theme is compatible with the next WordPress release!" and people should come.

However, an epiphany came to me and I think creating a web site for the purpose of finding out if a theme or plugin uses deprecated functions is not difficult at all.

[darkdragon]

Also the patch is stale, so another patch needs to be made.

[docwhat]

I'm not familiar with file logging and debug_backtrace(). I see debug_backtrace() on PHP.net. I imagine file logging is just writing to log someplace? Or is it a specific log?

I like throwing errors because the normal development loop is to modify the code and then run it, then repeat. This way, it shows up in the normal loop. Having to add a "review logs" to the loop slows a developer down and makes it less likely he or she will do it.

Is there some way to make the feedback more instantaneous? I would actually prefer to have the errors be fatal, if debug is turned on, but it could stop a developer from fixing his or her problems because of an earlier problem in some other code.

Ciao!

[docwhat]

Patch against trunk at revision 6429

[docwhat]

darkdragon:

One other point. This patch is here. It won't hurt anything to include it now. We can invest in an API later, if we want. I could see some nifty debugging tools being added into WordPress (integrated bug log, etc), but it's not something that will happen right away. But this can benefit developers now.

We can always do a search and replace to make it use the (currently non-existant) debugging API when we have it. If we get this in now, then the data will be recorded and switching over to the debugging API will be alot easier.

Ciao!

[santosj]

Again, does not cover the full scope of all deprecated functions.

I would rather invest in an API so that functionality can be changed later.

function wp_marked_deprecated($file, $function, $line, $useinstead);

wp_marked_deprecated(__FILE__, __FUNCTION__, __LINE__, 'somefunction');

Which can throw an error or record to a database or file.

[santosj]

I'll provide a improved patch for all known deprecated functions when I get home, I still want to invest in building a web site, which I can list all deprecated on both.

[docwhat]

I would make the 4th argument $seeinstead, to line up with the new doc strings in trunk.

I like it. Right now, this could just do the user_error(), but in the future, we can make this even better. Spiffy!

Ciao!

[westi]

Replying to santosj:

Again, does not cover the full scope of all deprecated functions.

I would rather invest in an API so that functionality can be changed later.

function wp_marked_deprecated($file, $function, $line, $useinstead);

wp_marked_deprecated(__FILE__, __FUNCTION__, __LINE__, 'somefunction');

Which can throw an error or record to a database or file.

+100

Yes please. someone write a patch to do this and it will surely get committed

[santosj]

Give me 7 hours and it will totally be done. It is good to hear that there is support for the API version.

[westi]

Closing #5184 as duplicate of this as they both share the same intent of increasing the obviousness of depreceated function usage.

[darkdragon]

Teaser, for feedback and discussion

[darkdragon]

All wp-includes functions have been marked to using the new API to throw user_error.

[darkdragon]

Okay, went through all of the wp-includes and found all of the known deprecated functions and marked them using the API.

The function has two hooks that can be used by a plugin to get more information and print more information.

My thoughts were to display how many deprecated elements were used by themes/plugins on the theme by default or display in the admin to inform the user of their theme status.

However, this single function allows for a plugin to do the above. The tracking can take place in the action hook and the filter will overwrite the trigger_error so that the notice won't be printed.

[docwhat]

I like it. It looks good.

I have only two comments:

1) You should be able to pass in none or empty or something for $seeinstead.
2) The error message should then not include an alternative.

Then you can remove the 'none alternatives available for use' messages which would make the sentence read weird.

Ciao!

[darkdragon]

Improved patch based off of docwhat suggestions

[darkdragon]

Okay, I agreed with docwhat suggestions and implemented them. So now there are only two places instead of ~10 that need to be translated. Still needs to be tested.

[darkdragon]

Fixed two errors, based off of docwhat suggestions

[darkdragon]

Works! Used a deprecated function and it output the correct text. Just have to wait for i18n folks, but it is ready to go.

[docwhat]

Awesome! Great work, darkdragon. Thank you very much! It'll be much easier to make high quality plugins and themes, now.

Ciao!

[darkdragon]

Now all it needs is to be committed.

[darkdragon]

Is it possible to get this into 2.4?

[westi]

(In [6514]) Mark functions and files as deprecated. Fixes #4361 props docwhat and darkdragon

[westi]

Replying to darkdragon:

Is it possible to get this into 2.4?

Done! I was busy hacking the patch around.

[darkdragon]

So every function in deprecated.php are ones that are no longer supported, but the ones found in other functions can technically still be used and will no longer be supported in a later version?

In that way, the functions in deprecated.php are obsolete and the rest are deprecated. The only difference would be that the obsolete functions are still supported and in danger of no longer being included in a later version.

Would it make sense to move the other deprecated functions to that file or will they stay for the next few versions? At what point will the functions in deprecated.php be purged?

[darkdragon]

Oh yeah, by the way the commit was sweet! I like the version details, however it appears that deprecated is spelled wrong in the parameter phpdoc tag.

See previous comment about the other deprecated functions that don't use the function.

[darkdragon]

My bad westi, just looked at the timeline.