ClassicPress Plugin Development: Structure of a Plugin

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

Before you start developing a plugin, I’d recommend deciding on the plugin structure you want to use. At the simplest level, a plugin only actually requires the file which holds enough code for the plugin and the folder it sits within, but in reality you will have other files which are needed as well, such as style sheets, language files, images and so on.

Planning a structure for the plugin will ensure your plugin files are well organised which will make it easier to work with both now and again in future.

John Alarcon of Code Potent, did a blog post on this subject a while ago. I use a structure fairly similar to the one he described, and have used the same format for showing the structure I use.

The rows with plus signs (+) are directories and minus signs (-) are files:

+ azrcrv-plugin-name
	+ assets
		+ css
			- admin.css
			- index.php
			- styles.css
		+ images
			- image.png
			- index.php
		+ pluginimages
			- banner-772x250.php
			- banner-1544x500.php
			- index.php
			- icon-128.php
			- icon-256.php
		+ scripts
			- admin.js
			- index.php
			- scripts.js
    + includes
        - functions.php
        - index.php
    + languages
        - azrcrv-plugin-name-de_DE.po
        - azrcrv-plugin-name-fr_FR.po
        - index.php
    + libraries
        + some-lib
			- index.php
			- some-lib.php
        + some-other-lib
			- index.php
			- some-other-lib.php
        + updateclient
			- index.php
			- UpdateClient.class.php
        - index.php
    - azrcrv-plugin-name.php
    - index.php
    - license.txt
    - README
    - readme.txt

Main Directory – Line 1

The main directory holds all other directories and files in the plugin. The directory name should contain your developer prefix (for me this is azrcrv) and the name of the plugin. Word separators should be hyphens, not spaces or underscores. Your developer prefix will ensure there are no naming collisions between your plugin and those from other developers.

Subdirectories – Line 2, 3, 7, 10, 16, 20, 23, 27, 28, 31 and 34

The subdirectories included are the ones I commonly use; none of them are required and you may choose to place them differently. The pluginimages directory I have requires extra coding to make sure the update mechanism can correctly access the banner and icon images as it expects the images folder to be in the main plugin directory rather than as a subdirectory of the assets directory.

Image Files – Line 8, 9, 11, 12, 14 and 15

Image files should be stored in your images directory; if you have lots of images you might want to split them between more folders for ease of management.

Included Files – Line 21

If you include extra files in your plugin, they can be stored in the includes directory.

Language Files – Line 24 and 25

If you support the translation of your plugins, and you should, the po files should be named with the same name as the plugin with a hyphen separating the language code.

Libraries – Line 30, 33, 36

If you include existing libraries they can be stored in their own directories. I’ve included Code Potent’s Update Manager in the example as I include it with every plugin I release.

Scripts – Line 17 and 19

I typically split scripts between scripts.js for front-end JavaScript and admin.js for back-end scripts, but you could create additional script files to split out different JavaScript functions.

Styles – Line 4 and 6

I typically split styles between styles.css for front-end styling and admin.css for back-end styling, but you could create additional stylesheets.

Main Plugin File – Line 38

The main plugin file should duplicate the name of the main plugin directory, followed by the extension php.

Additional Files – Line 39, 40, 41 and 42

Additional files such as a readme.txt or license.txt would typically be stored in the plugin route directory.