110 WordPress Plugin Naming and Declaration (Video)

Part of ‘How to Write a WordPress Plugin’ Series

This Lesson – Overview

In the previous lesson we’ve covered the introduced to plugins.

In this lesson we’ll cover the naming and declaration of a WordPress plugin and create the main php plugin file.

This file has a pre-defined comment section called the header comment that is used by WordPress both to register and declare the plugin availablity to the WordPress installation.

Contents

Plugin Structure

You may be wondering why we need to discuss the structure of your plugins. Well, the structure of your plugin is important for two reasons:

1. To avoid naming collision, not just in your own code but with the thousands of other plugins available.
2. To enable other plugin writers easy access to your code.

I know everyone has their own way of working but if you follow a simple structural way of working, life becomes easier for everyone, and that can’t be a bad thing.

The Plugin Name

The first task in creating a WordPress Plugin is to create a unique name for your Plugin.

Choose a name that describes what your plugin does; for instance, a weather-related plugin would probably have the word “weather” in the name, i.e.:

PK Weather Map

Your unique name can be multiple words.

It’s a good idea to prefix your chosen plugin name with your initials or the initials of your website. This also helps guarantee the uniqueness of the name.

To verify the uniqueness of your plugins name, explore the WordPress plugins repositories, Official WordPress Plugins Repository. Also do a Google search on your proposed name and related keywords for the type of functionality you are seeking.

The Plugin File Structure

All WordPress plugins must be installed in the wp-content/plugins/ folder.

You could just drop your files into this folder, but think how confusing that would become, even with just a handful of plugins installed.

Just remember, everyone places their plugins in this folder, so no two plugins can have the same name. With potentially thousands of files stored here, the situation would soon become chaotic So don’t do it.

Instead, always create a folder for your plugin, even if your plugin consists of only one file. I’m sure you’ll agree, having a folder structure is a much cleaner and better idea.

• When creating your folder and file structure, to comply with WordPress standards, do not use spaces or special characters, separate words with a hyphen (-).

Your plugin folder structure should consist of one folder which takes the name of your plugin and contains all your related plugin folders and files.

Plugin Folder Name

• css folder (for StyleSheet files)
• Images folder (for all your image files)
• js folder (for JavaScript files)
• lang folder (for localisation files)
• php folder (for core plugin code)
• file-main-plugin.php
• file-readme.txt

Remember: No spaces or special characters to be used, seperate words with a hyphen.

The only file which must be in your plugins directory is a PHP file which has the same name as the folder, your plugin name.

Sub folders for all other code such as PHP, JS, CSS, Images, etc. should also be created within the main folder to keep related code.

If you intend to distribute your plugin through WordPress you will also need to include a readme text file as well. We’ll discuss that files structure in more detail another time.

pk-plugin-class
- css
– images
– js
– php
– pk-plugin-class.php
– readme.txt

WordPress does recommend the inclusion of a readme file for all your plugins. A description of the format can be found at: http://wordpress.org/extend/plugins/about/readme.txt

WordPress also provide a readme file validator at http://wordpress.org/extend/plugins/about/validator/

So they must consider the inclusion of this file important.

Standard Plugin Header

For WordPress to recognize your plugin, the top of your plugins main PHP file must contain a standard plugin information header comment.

This header comment lets WordPress

• recognize that your plugin exists,
• add the plugin to the plugin management screen so it can be activated,
• load it, and
• run the functions of the plugin.

Without the header, your plugin will never be activated and will never run. The header comment format consists of:

<?php
 /*
 Plugin Name: Your Plugin Name Here
 Plugin URI: Your Plugin URI
 Description: What your plugin does
 Version: Current Plugin Version
 Author: Who Are You?
 Author URI: URI of the plugin author
 Licence: A "Slug" license name e.g. GPL2
 */

The minimum information WordPress needs in order to recognize your plugin is the plugin name line.

The rest of the information (if present) will be used to create the table of Plugins on the Plugin management screen.

• The order of the lines is not important.

The License slug should be a short common identifier for the license the plugin is under, usually GPL2, and is meant to be a simple way of being explicit about the license of the code.

Standard Plugin Header – License

It is customary to follow the standard header with information about licensing for the plugin. As stated, most plugins use the GPL2 license used by WordPress or a license compatible with GPL2. To indicate a GPL2 license, just include the standard license declaration in your plugin, this can be found at the WordPress codex, http://codex.wordpress.org/Writing_a_Plugin#Licence

 

/*  Copyright YEAR  PLUGIN_AUTHOR_NAME  (email : PLUGIN AUTHOR EMAIL)
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License, version 2, as
 published by the Free Software Foundation.
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

Conclusion – Summary

Well, that’s all for this tutorial on the naming and declaration of a WordPress plugin.

You should feel quite comfortable with the technigues needed to name, declare and create the files needed for your plugins after this lesson. If you don’t, just delete the plugin and go through the lesson again.

See you in the next lesson when we will discuss and implement the plugin’s class structure.

Lesson Code

<?php
/*
Plugin Name: PK Plugin Class
Plugin URI: http://kingsolutions.org.uk/wordpress/wordpress/how-to-write-a-wp-plugin/
Description: A Simple Plugin Class for WordPress
Version: 0.1
Author: Philip King
Author URI: http://kingsolutions.org.uk/wordpress/
Licence: Licence GPL2
*/
/*  Copyright 2011  Philip King  (contact: http://kingsolutions.org.uk/wordpress/)

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License, version 2, as
    published by the Free Software Foundation.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/
?>