devinvinson / wordpress-plugin-boilerplate Goto Github PK

https://github.com/GaryJones/WordPress-Plugin-Boilerplate/commit/a6d468fd68a22504efe2f80e8e49a9f13a0e7122

That's a commit that addresses various little bits and pieces that I think could improve the boilerplate. I've not done it as a set of commits and pull requests, as I can leave it up to you to pick and choose what you like from it. I've commented the commit with my reasoning, but am happy to provide further explanation if something isn't clear.

In class-plugin-boilerplate.php, in line 25, you have

protected $version = '1.0.0';

Shouldn't it be?:

protected $version = PLUGIN_NAME_VERSION; // PLUGIN_NAME_VERSION is defined in plugin-boilerplate.php

I've been doing custom WordPress sites for a few months, now it's time to branch out into plugin development. This is my first attempt.

I'm running MAMP on a MacBook Pro. Have a fresh install of WordPress (version 3.5.1), and the ZIP file from http://tommcfarlin.github.io/WordPress-Plugin-Boilerplate/.

I've copied the 'plugin-name' folder into my plugins directory.

The plugin isn't showing in my list of installed plugins.

Any thoughts? And thanks for any help you can offer.

David R

At this point, I'm interested in moving the assets directory above the root of the plugin directory.

This is the follow the new practices of the WordPress Theme repository (as @garyj) has pointed out not long ago.

The typical Subversion repository structure is:

• assets
• branches
• tags
• trunk

As far as I'm concerned, plugin-name is analagous to the trunk directory, so this means that assets should be moved up one level; however, this places the directory with the changelog and the README which doesn't make sense.

Instead, it feels almost like we should create a trunk directory of sorts, but I'm looking for some additional input on how to best handle this.

hi,

it seems that on line 49 in plugin.php the hook used for registering plugin styles, wp_enqueue_scripts, is not the right one and sould be wp_print_styles.

thanks Tom for sharing this very usefull boilerplate.

Have you thought of including this to the top
https://github.com/tommcfarlin/WordPress-Plugin-Boilerplate/blob/master/plugin-boilerplate/plugin-boilerplate.php#L57

// Exit if accessed directly
if ( !defined( 'ABSPATH' ) ) exit;

if ( !class_exists( 'PluginName' ) ) :

EasyDigitalDwnloads does it.
https://github.com/easydigitaldownloads/Easy-Digital-Downloads/blob/master/easy-digital-downloads.php#L32-l34

Because we're using a variable for the locale of a plugin, a section should be added to the README that outlines recommended tools that people should use when working with the Boilerplate.

If we're also going to be including the GitHub updater, we need to note this in the README as well so that users are aware that if their plugin is on GitHub, then it can use @GaryJones' GitHub updater by providing a URL.

Related #59, #75

Refer to #75 for more information.

Specifically, we need to introduce documentation on how to use various branches other than the master.

Just decided to give it a try for a new plugin I'm working on. I get the following notice twice:

PHP Notice: register_uninstall_hook was called incorrectly. Only a static class method or function can be used in an uninstall hook.

It occurs on these two lines:

register_deactivation_hook( __FILE__, array( $this, 'deactivate' ) );
register_uninstall_hook( __FILE__, array( $this, 'uninstall' ) );

I have an existing WordPress 3.5.1 with a custom theme and a bunch of plugins. Could it be on my side?

HI, first of all, thanks for this fantastic base to create a plugin.
I tried to extend the main class of plugin so i can separate its various features. My plugin allows to add shortcode, two custom post types and some widgets.

For example, i tried to extend the main class like this:

Class MyShortcodes extends MainClass {

function __construct() {
    add_action(...);
    add_action(...);
}

public function my_function_to_hook() {
    ....
}
public function another_function_to_hook() {
    ....
}

}   //end MyShortcodes class

$my_shortcodes = new MyShortcodes();

All the above code is in a php file (shortcodes.php) that I include in the main php file of plugin (plugin-name.php):

require_once( plugin_dir_path( __FILE__ ) . 'shortcodes.php' );

The whole process works perfectly but I'd like to know if my way is correct or is there a better and more syntactically correct procedure.

Thanks!

I have seen a WordPress conference talk from a core dev (@nacin I think) who said that its better when you call actions hooks during init rather then just when the plugin loads.

What are your thoughts on this?

I've already written a general boilerplate in this answer on WPSE.

Quickly summed up. The following checks are so far missing:

• referrers
• user capabilities
• if the current file is the one that should get uninstalled
• if the plugin name is inside the $_REQUEST object.

I also highly advice to leave that stuff in a separate class, so everyone can get an overview on what's happening as quick as possible.

• Various lines are not indented correctly, making it harder to read.
• No @since tags on each of the methods.
• Line 222 documentation in plugin.php is incorrect.
• With relatively short methods, the // end ... only adds to the visual clutter. This isn't legacy code that needs to be commented to be deciphered. See your own update in response to my comment at http://tommcfarlin.com/commenting-code-blocks/ as to why these should be removed from this boilerplate.
• Enqueueing of scripts and styles don't have a version number parameter.
• The .po file should have a .pot extension.
• The .po file Keywords list is incomplete for all of the translation functions available within WP.
• The admin view shouldn't need to manually repeat the title - it can be grabbed from when the admin page was registered via echo esc_html( get_admin_page_title() );
• The page-level documentation for uninstall.php is incomplete.

On your plugin.php, I was going to suggest moving this into a static class so that you can call class methods from add_action() and add_filter() without needing an object instantiation.

Also, I know you only created this recently, but I suspect you'll be creating a functions.php file, right?

In Views, there's also possibly list view and form view, and perhaps you could have subfolders delineating those if they're going to be used.

Some things to add in the stylesheet that's pretty generic and useful would be:

• twitter boilerplate theme buttons
• tab API in jQuery and in the stylesheet
• twitter boilerplate theme for alerts

FYI - The indentions are not up to WordPress coding standards.
http://make.wordpress.org/core/handbook/coding-standards/php/#indentation

You can still avoid direct (public) access by using protected properties and constructor, instead of private. The former allows the class to be extended in some way, to add additional functionality.

add_plugin_admin_menu() uses add_plugins_page. This outputs the admin settings page under Plugins. Personally I've never seen a plugin's settings page in this location.

The most standard location for most plugins is under Settings - add_options_page() ; or more rarely under Tools - add_management_page() . (Perhaps just mentioning add_management_page() in a comment as an alternative)

https://github.com/tommcfarlin/WordPress-Plugin-Boilerplate/blob/master/plugin-name/class-plugin-name.php#L214

I think you meant to type $this->plugin_slug

Would there be any benefit in creating an assets directory, and including within init three images - screenshot-1.png, banner-772x250.png and banner-1544x500.png? These images would be plain textual images that explained the purpose, or gave the size in the case of the screenshot file, as placeholders for when the plugin is to be uploaded to the .org repo.

Having the images already created at the right size saves someone having to look them up, introduces them and the assets folder for someone who don't know about them, and encourages screenshots to be placed into the assets folder so they aren't part of the downloaded plugin. If someone isn't planning on uploading to the .org repo, they can delete the assets folder in a couple of seconds.

Variables for the text domain seems like a great idea, but it causes issues.

See: https://twitter.com/nacin/status/194635610785447938

From Otto: "that text domain must be a plain string. Not a variable. Not a define."
http://ottopress.com/2012/internationalization-youre-probably-doing-it-wrong/

And Mark Jaquith:
http://markjaquith.wordpress.com/2011/10/06/translating-wordpress-plugins-and-themes-dont-get-clever/

Let me know if you'd like a pull request for this.

Hi,

I don't think it is a good idea to internationalize the permissions.

__('read', 'plugin-name-locale'),
https://github.com/tommcfarlin/WordPress-Plugin-Boilerplate/blob/master/plugin-boilerplate/plugin-boilerplate.php#L265

I am not sure about the meta slug. I would say not to internationalize it as the url in WordPress is not translated and I am not sure what issues this could cause.
__('plugin-name', 'plugin-name-locale'),

Consider taking a look at this when you get a chance:

http://www.wptavern.com/forum/plugins-hacks/1129-using-non-official-plugin-repository.html#post10180

http://w-shadow.com/blog/2010/09/02/automatic-updates-for-any-plugin/

Perhaps you could consider integrating something into your sample here, but reduce the code down as much as possible and make it easy to follow? The other thing that something like this needs to do is use $wpdb to run a schema.php file to load CREATE TABLE IF NOT EXISTS stuff if the plugin uses special tables, and then to call the plugin's custom getOptions() and updateOptions() static class methods after that so that it uses the latest downloaded plugin codebase to apply the options changes.

hi,

i'm trying to make a plugin right now using your template but encountered an issue :)

there is a "} // end if" in plugin.php line 59 that should not be there. or there is an "if" statment missing...

thank you for providing all these very good resources.

seb.

Since moving the class to it's own file, the __FILE__ references for the register_activation_hook() and register_activation_hook() calls are going to cause them to fail.

Is it possible to set that $this->version works in every class without needing to be added again?

Good PHP practice says that files should either define stuff (classes, functions and so on) with no side effects, or be a file that uses those definitions and therefore has an effect.

See PSR-1 for an example.

As such, the class itself should be in it's own file. This would, in theory, allow it to be autoloaded or otherwise included by other parts of the system as needed, without it also calling a static method.

Reference

The page level documentation for the .php files could be improved. See https://github.com/GaryJones/visual-subtitle/blob/master/visual-subtitle.php as an example.

It contains the plugin name as the short description, followed by several useful phpDocumentor tags (the copyright tag can be included after author, before license). This should be at the top of each .php file, so that, when seen out of context, all of the relevant data about the project the file comes from is present.

For the main plugin file, it is then followed by the custom @Wordpress-Plugin tag which then starts the plugin header tags. WordPress is happy with this, as it is still within the first 8192 characters of the file, but also allows a plugin for phpDocumentor or other documentation generation application to parse out this plugin header data and display it in some way, and not just as one continuous long description which has line breaks removed, which is would do otherwise. The custom tag follows the format of being prefixed with a vendor ID.

Plugin Name is used here and here

TODO is used here

'Changelog
2.0 (7 May 2012)...' :)

Maybe use Plugin_Name instead of PluginName as suggested in the the wp coding standards.

http://make.wordpress.org/core/handbook/coding-standards/php/#naming-conventions

As per WP coding, version numbers should be given as 1.0.0, and not just 1.0. This is so you can explicitly search for 1.0.0 and not get all of the 1.0 and 1.0.1 etc. results.

At some point, you may consider changing the create_function php method to an anonymous function supported in PHP 5.3, in order to improve performance: http://framework.zend.com/issues/browse/ZF-7646

So you would change . . .

add_action( 'widgets_init', create_function( '', 'register_widget( "foo_widget" );' ) );

Into . . .

add_action( 'widgets_init', function(){ return register_widget( 'a\b\c\My_Widget_Class' ); });

Plus, you can use namespaces with it.

Source: http://codex.wordpress.org/Widgets_API

In the register_scripts_and_styles() method, plugin_dir_path(FILE) is used, which produces a full local server path. Concatenated to this is the file directory and name '/js/admin.js'.

In the load_file method this full local server path + file_path is added to the WP_PLUGIN_URL and WP_PLUGIN_DIR constants. This results in a really large and wrong paths (for both $url as $file).

The right way to do it is to use the Wordpress provided plugins_url() and plugin_dir_path() methods (and only in the load_file method). As stated here http://codex.wordpress.org/Determining_Plugin_and_Content_Directories the constants WP_PLUGIN_URL and WP_PLUGIN_DIR should not be used directly by plugins and themes.

To fix the whole thing:

• Remove plugin_dir_path(FILE) in the register_scripts_and_styles() method. (also remove the first slash of file path as it is always added by the wordpress methods)
• In the load_file method use:
  $url = plugins_url($file_path, FILE);
  $file = plugin_dir_path(FILE) . $file_path;

That's it. Cheers Sjoerd

I've been working on the GitHub Updater plugin. With that plugin active on a site, it enables plugins that include a GitHub Plugin URI: https://github.com/<owner>/<repo> plugin header to be automatically updateable from the GitHub source.

There's an optional GitHub Branch: <branch> option, should it be a specific branch that should be checked for updates (e.g. master when using git-flow, and the default branch is develop), and a tag for providing access tokens for private repos (I've not looked into this code, so I don't know how well it works).

Would there be any interest in having these two tags added to the Boilerplate? If the GitHub Updater plugin isn't active, then the headers simply become inactive and have no side-effect.

I would have the top of the pot file like this.

You are missing the gettext keywords, the plural form and path.

msgid ""
msgstr ""
"Project-Id-Version: TODO 1.0.0\n"
"Report-Msgid-Bugs-To: http://wordpress.org/tag/plugin-boilerplate\n"
"POT-Creation-Date: 2013-05-10 11:23:19+00:00\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"PO-Revision-Date: 2013-05-10 10:37-0500\n"
"Last-Translator: Tom McFarlin <[email protected]>\n"
"Language-Team: LANGUAGE <[email protected]>\n"
"X-Generator: Poedit 1.5.5\n"
"X-Poedit-KeywordsList: __;_e;_n;_x;esc_html_e;esc_html__;esc_attr_e;"
"esc_attr__;_ex:1,2c;_nx:4c,1,2;_nx_noop:4c,1,2;_x:1,2c;_n:1,2\n"
"X-Poedit-Basepath: ../\n"
"Plural-Forms: nplurals=2; plural=n != 1;\n"
"X-Poedit-SearchPath-0: .\n"

If you wanted to top it off then you could add Text Domain: TODO like I mentioned in my comment.
http://tommcfarlin.com/internationalize-wordpress-plugins/#comment-167129

Since the contents of the GPL license don't need to be within each or any file, then it may be beneficial to move the contents to a LICENSE.txt file. Any further commits on this file then stand out more than just text within another file, which make any licensing changes for the project easier to spot.

That leaves the plugin header License tag with GPL-2.0+ as the default value, as per the SPDX registry.

I was talking to @GaryJones at wceu and he mentioned placing the settings function in another class.

I thought it was good idea. So that is why I have done in on my fork. https://github.com/grappler/WordPress-Plugin-Boilerplate/tree/patch-2

What do you think?

Is there any information anywhere on best practice for using files in the views directory?

For example, if I want to render a public facing form from a plugin, I might create a function to do that. Do you advocate putting that form in a view and then including it from the aforementioned function?

Some of the method names use verbs already - register_*, which is good. You can tell instantly what happens when it's called.

Others are not so clear from the method name alone. plugin_textdomain - Is that returning a slug of the text domain? Is it registering one or more text domains? What does plugin_admin_menu do? If it's adding or registering a menu item to the admin menu, then that's the verb you should include within the method name.

The template looks to be a little behind the current standard / demo file: http://wordpress.org/extend/plugins/about/readme.txt

I'd suggest also changing the Tested Up to to be 3.6.0, and the Stable Tag to be 1.0.0.

In plugin.php line 166 has plugins_dir_path, it should be plugin_dir_path.

Hi Tom,

I am having trouble working out how I can have the variable in further class.

Thanks

You should probably have an example of hooking in a menu item and settings page, along with registering a couple of settings.

If I can find time, I'll try to work up a pull request.

Or README Installation section incomplete. I had to add following lines to make it work as described:
/*
Plugin Name: Plugin_Name
*/

Issue observed on wordpress 3.6.1.

Hey Tom,

I'm working on my own version of a boilerplate for plugins (https://github.com/omarabid/WordPress-Plugin-Boilerplate). It has a different mindset/structure, but we share some traits. Here are a few suggestions that I think could help improve your own version:

1 Correctly calling the Uninstall function.

The correct way to do this is by using a static function.

register_uninstall_hook( __FILE__, 'PluginName::uninstall' );

2 Prevent direct access

if (!defined('ABSPATH')) {
    exit;
}

3 Check if the class already exists. This will prevent collusion with other plugins that might happen to have the same class name

if (!class_exists('PluginName')) {
  class PluginName {
  }
}

My current version is a bit messy right now and still a work in progress. But I welcome any feedback on it.

Hi

Whenever I develop a plugin using Plugin/Widget Boilerplate, I have no problem using them on linux severs, but once I install it on a wordpress that is running on a windows server I get error 500 and the whole wordpress installation collapses.

Any idea how to fix it?

The class properties are not documented with @var. The $instance can be documented as being an object, and can then be optionally replaced with the class name if the developer wishes. The slug would be a @var string.

I think the get_instance function should be updated to:
return null == self::$instance ? self::$instance = new self : self::$instance;
so that the new self is being put into the instance variable, as opposed to current code which creates an orphaned object.

Say I use this boilerplate, and add a filter to modify the menu order.

2 months later, developers Alice and Bob arrive, and notice an issue with my filter. So they need to remove my filter, but how?

I'd suggest code such as this to instantiate the main object

if ( PluginName::start_me() )
    add_action(
        'wp_loaded',
        array ( PluginName::get_instance(), 'plugin_setup' )
    );