Check: Generic function/class/define/option prefix names

[davidperezgar]

This check aims to detect short or common prefixes that could cause fatal errors in WordPress installations.
We consider as an error for this check.

How could develop this check?

We need to have a white list of common function starts. Actually we have in our internal scanner: __,_,-,set,get,is,save,show,update,add,wordpress,wp,woocommerce,wc,table,html,css,js,input,output,plugin,plugins,my_plugin,myplugin,prefix,my_custom,custom,as,widget,oauth2,handle,generate,post,site,remove,filter,display,init,start,check,sync,cache,phpmailer,declare,register,enable,include,search,upgrade,update,setup,create,admin,load,theme,fetch,apply,clear,verify,test,insert,acme,app,render,rest

And after, We check the list of named functions that are outside a Class, and a list o named Classes. Maybe we can go to Namespaces as well.

Our description to developers:

Generic function/class/define/namespace/option names

 
All plugins must have unique function names, namespaces, defines, class and option names. This prevents your plugin from conflicting with other plugins or themes. We need you to update your plugin to use more unique and distinct names.

A good way to do this is with a prefix. For example, if your plugin is called "Easy Custom Post Types" then you could use names like these:
 
function ecpt_save_post()
define( ‘ECPT_LICENSE’, true );
class ECPT_Admin{}
namespace EasyCustomPostTypes;
update_option( 'ecpt_settings', $settings );
 
Don't try to use two (2) or three (3) letter prefixes anymore. We host nearly 100-thousand plugins on WordPress.org alone. There are tens of thousands more outside our servers. Believe us, you’re going to run into conflicts.
 
You also need to avoid the use of __ (double underscores), wp_ , or _ (single underscore) as a prefix. Those are reserved for WordPress itself. You can use them inside your classes, but not as stand-alone function.

Please remember, if you're using _n() or __() for translation, that's fine. We're only talking about functions you've created for your plugin, not the core functions from WordPress. In fact, those core features are why you need to not use those prefixes in your own plugin! You don't want to break WordPress for your users.

Related to this, using if (!function_exists(‘NAME ‘)) { around all your functions and classes sounds like a great idea until you realize the fatal flaw. If something else has a function with the same name and their code loads first, your plugin will break. Using if-exists should be reserved for shared libraries only.

Remember: Good prefix names are unique and distinct to your plugin. This will help you and the next person in debugging, as well as prevent conflicts.
 
Example(s) from your plugin:

[swissspidy]

So this basically the WordPress.NamingConventions.PrefixAllGlobals PHPCS sniff in WPCS?

[davidperezgar]

Yes! You're right. We're asking 4 letters and WPCS has 3 letters. I'm going to make an issue for that.

[davidperezgar]

Ok, I've asked to update the 4 letters in the developer documentation and PrefixAllGlobals sniff.

[ernilambar]

I was digging more about this issue and I found out that PrefixAllGlobalsSniff has already a list of restricted prefixes in variable $prefix_blocklist. But it is not customizable as of now.

Ref: https://github.com/WordPress/WordPress-Coding-Standards/blob/develop/WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php#L86-L91

protected $prefix_blocklist = array(
	'wordpress' => true,
	'wp'        => true,
	'_'         => true,
	'php'       => true, // See #1728, the 'php' prefix is reserved by PHP itself.
);

If we could make this array customizable then we can feed our own list of restricted prefixes.
But also we need to find a way to run this sniff without passing list of prefixes and only check for those restricted prefixes. Currently this sniff runs only if we give a list of allowed prefixes.

[swissspidy]

Sounds like a good upstream contribution to WPCS :)

[davidperezgar]

Yeah!

[ernilambar]

Hope you don't mind me pinging here. CC @jrfnl for the the input and suggestion whether this customization is feasible in WPCS repo.

[jrfnl]

@ernilambar Please read the linked issues before pinging people: #523 (comment)

As for:

If we could make this array customizable then we can feed our own list of restricted prefixes.

Making it customizable would allow for people to clear out the list, resulting in the opposite effect.

But also we need to find a way to run this sniff without passing list of prefixes and only check for those restricted prefixes. Currently this sniff runs only if we give a list of allowed prefixes.

I suggest opening separate new issues for each of these questions in the WPCS repo to discuss (also see the existing issue, though that's a different ask/decision point: WordPress/WordPress-Coding-Standards#2467).

[ernilambar]

Another approach could be modifying PrefixAllGlobalsSniff.php class as per PCP requirement and using composer-patches for the implementation.

• We would be able to take benefit of handling different cases for functions, classes, defines, traits, etc. This class already handle such cases efficiently. So we would not have to reinvent the wheel for the same task.
• We have a list of block list of prefixes which we need to check. Since we would not be able to make that block list customizable in the upstream, directly using WordPress.NamingConventions.PrefixAllGlobals sniff is not viable.
• Also our requirement is quite inverse of what current sniff is doing. Currently an array of allowed prefixes are checked against but we require check whether given prefix is in the block list or not.

Cons of this approach is addition of burden to maintain the patch.

This is PR which I was testing to see if we can implement the feature: https://github.com/ernilambar/WordPress-Coding-Standards/pull/1/files

In this PR:

• Block list could be updated with new items but default list would not be removed.
• Add separate function to check if token has valid prefix or not.

[swissspidy]

Instead of patching I‘d just port this sniff over to this repo and modify it to our needs

[jrfnl]

Instead of patching I‘d just port this sniff over to this repo and modify it to our needs

That would be violating both the copyright as well as the license.

Instead of trying to reinvent the wheel, you may want to try to collaborate and contribute to WPCS instead.