There I was. Working on adding PHP docblocks to widgets.php in /wp-includes, like you do, when I came across this:
So I set about trying to figure out the appropriate
@since parameter to use. Do I base the
@since on when the
WP_Widget function was first added (2.8)? Or from when the time it was downgraded to a PHP4 compatibility wrapper for the
__construct function (3.2)? I decided to ask the almighty Ben Lobaugh, my dev lead, to see what he thought. And Ben says:
I think you should erase the PHP4 constructor as PHP5 is required by WP now and submit it in another patch.
Done! Patch created and ticket submitted. That was easy.
[Chris]…are you going to update [your] custom widgets to not use WP_Widget?
WHADDYAMEAN? Surely I’m not using some old PHP4 compatibility wrapper function!
There! Right there, see, I’m using a
__construct! It’s fine!
And therein lies the problem and the topic of this post.
WordPress discontinued support for PHP4 back in 3.2. But, to make a smooth transition and break as few things as possible, some necessary evils were put in the code in the form of compatibility functions. These weren’t so much to support PHP4, per se, so much as they were put in to support code that was being used that was expecting or based around PHP4 standards.
There are lots of tutorials and guides that tell you how to build WordPress widgets. And many of them are going to tell you to use the
$this->WP_Widget( ... ) syntax.
I’m here to tell you that they are wrong. And this is coming from someone who is right there with you, doing it wrong, too.
Why should I care?
If it works, why bother? Who cares if the WP_Widget function is just a wrapper for the PHP5 constructor? Let me put it this way: WordPress 3.2 was released in 2011 — three years ago. PHP4 officially stopped active development in 2008 — six years ago. By continuing to use what are essentially unnecessary compatibility functions, we’re making it so that WordPress core is forced to retain pointless functions like this one to prevent breaking other people’s code that might be using these functions.
While it’s not technically
__doing_it_wrong() to use the WP_Widget function, it’s confusing. We already have a
WP_Widget in core — it’s the class we extend to create a new widget. While it may look like we’re using a method in that class based on a quick view of that line of code, what’s actually happening is the opposite.
I propose that we STOP. DOING. IT. NOW.
In order to get functions like these ultimately pulled out of core — or at least moved to deprecated functions — we need to stop using them. (Sidenote: My ticket for this was closed for compatibility reasons)
Instead of using the
WP_Widget function, replace
$this->WP_Widget( ... ) with
parent::__construct( ... ), so that code I showed you above from my custom widget would be rewritten like this:
This is the way the Codex currently suggests creating custom widgets. Not only are we doing exactly the same thing we were doing before, but it’s much clearer what’s going on. Even if I don’t know anything about Object Oriented Programming, and I don’t know what a construct is, at the very least I’m not going to get confused by the
WP_Widget function (as compared with the
Right now, there’s no immediate reason to change your code. But that doesn’t mean you shouldn’t. There are reasons why this function isn’t getting removed from WordPress core anytime soon, but most of those have to do with plugin compatibility. It seems silly to still be supporting PHP4 — in some form or another — when WordPress officially dropped support for PHP4 eight versions ago (soon to be nine), but this is a solvable problem. If we just fix our plugins and themes, we won’t need to use old PHP4 compatibility functions, and we can help move WordPress core forward in supporting modern standards.