A standardized, organized, object-oriented foundation for building high-quality WordPress Plugins.
Now also compatible with Gutenberg. ;-)
The WordPress Plugin Boilerplate includes the following files:
.gitignore
. Used to exclude certain files from the repository.CHANGELOG.md
. The list of changes to the core project.README.md
. The file that you’re currently reading.- A
plugin-name
directory that contains the source code - a fully executable WordPress plugin.
-
The Boilerplate is based on the Plugin API, Coding Standards, and Documentation Standards.
-
All classes, functions, and variables are documented so that you know what you need to change.
-
The Boilerplate uses a strict file organization scheme that corresponds both to the WordPress Plugin Repository structure, and that makes it easy to organize the files that compose the plugin.
-
The project includes a
.pot
file as a starting point for internationalization. -
New file
make
to work with the console (into plugin-name folder):php make zip
to make a clean copy of the plugin into zipphp make class CLASS-NAME FOLDER-NAME
to create a new file into theFOLDER-NAME
indicate with the name:class-plugin-name-CLASS-NAME.php
with some base code to start to work
-
Auto generation of some utilities with console (into plugin-name folder):
grunt
to make auto theplugin-name.pot
into the folderlanguages
gulp
to starttest mode
in console and run all the test intotests folder
in auto mode when a file of the project is save it- Note: for both you need run before in console
npm install
&composer install
-
PHP CodeSniffer with WordPress standards:
- You can check te code with WordPress standards with
squizlabs/php_codesniffer
&wp-coding-standards/wpcs
already included with only makecomposer-install
. - After that to configure it set
vendor/bin/phpcs --config-set installed_paths vendor/wp-coding-standards/wpcs
. - And also set
vendor/bin/phpcs --config-set default_standard WordPress
. - If you have some software like
Visual Studio Code
(is free) and module likevscode-phpcs
or similars, you can see the problems in the code during your work in auto mode. In another case you can do the same and see the problems in console withvendor/bin/phpcs /path/to/code/file-name.php
orvendor/bin/phpcs /path/to/code/folder-name
- IMPORTANT: You can also solve most problems automatically by applying
phpcbf
instead ofphpcs
likevendor/bin/phpcbf /path/to/code/file-name.php
orvendor/bin/phpcbf /path/to/code/folder-name
- You can check te code with WordPress standards with
-
DEV MODE:
- The
admin bar
into WordPress dashboard put into different color and with a tagDEV MODE
when you activecomposer install
and some features to DEV with that. - Into dashboard page
index.php
of the backend you can see a notice with some information about all you can do in dev mode like:- Pretty error interface with Whoops. To see it in action just make a fatal error. ;-)
- Kint debugging helper. Inside your code insted of use var_dump($variable); try to use d( $variable ); for amazing debug.
- Into
tests folder
you have new files to test into different database wich you can setup with the file/wp-tests/wp-tests-config.php
and the filebootstrap.php
that execute the code to run and manually load the enviroment to test. For a good implementation of test you can see an example with some code as comments in the filetest-sample.php
. - Check also in the root of the plugin the file
phpunit.xml
to understad all the configuration about it. In this last file avoidbootstrap="tests/bootstrap.php"
if you don´t want to test with an extra database that you need to setup in the file/wp-tests/wp-tests-config.php
and also previous create in your dev enviroment. IMPORTANT: This dev database is reset in each test.
- The
-
GUTENBERG:
- This new folder work in similar way as
https://github.com/ahmadawais/create-guten-block
because of have their dependencies into thepackage.json
. Hassle-free updates from this single dependencycgb-scripts
. - You can create new blocks base on the provided examples modifying existing ones or you can just copy & paste each folder from
plugin-name\gutenberg\src\basic
to for example-->plugin-name\gutenberg\src\custom-block-name
. - Remember to include the new subfolders references into the file
plugin-name\gutenberg\src\blocks.js
and keep the name of the main JS file of the block asindex.js
to easier reference. - Work into each block with
Sass, React, JSX, and ES6
and send all work in a better compatible mode toplugin-name\gutenberg\dist
with:- First set the console into the folder
plugin-name\gutenberg
and runnpm install
. npm-start
to development mode: watches for any changes and reports back any errors in your code.npm run build
to finish and build production code into dist folder.
- First set the console into the folder
- All the code into
plugin-name\gutenberg\dist
is already enqueue by this boilerplate. Please see the files:plugin-name\core\class-plugin-name.php
&plugin-name\gutenberg\class-plugin-name-gutenberg.php
.
- This new folder work in similar way as
- The best choice is go to
https://boilerplate.pablocianes.com/
and make it easy with a plugin generator base on all this code and your custom personalization in auto mode.
The Boilerplate can be installed directly into your plugins folder "as-is". You will want to rename it and the classes inside of it to fit your needs. For example, if your plugin is named 'example-me' then:
- rename files from
plugin_name
toexample_me
- change
plugin_name
toexample_me
- change
PLUGIN_NAME_
toEXAMPLE_ME_
It's safe to activate the plugin at this point. Because the Boilerplate has no real functionality there will be no menu items, meta boxes, or custom post types added until you write the code.
grunt
to make auto theplugin-name.pot
into the folderlanguages
The WordPress Plugin Boilerplate uses a variable to store the text domain used when internationalizing strings throughout the Boilerplate. To take advantage of this method, there are tools that are recommended for providing correct, translatable files:
Any of the above tools should provide you with the proper tooling to internationalize the plugin.
The WordPress Plugin Boilerplate is licensed under the GPL v2 or later.
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
A copy of the license is included in the root of the plugin’s directory. The file is named LICENSE
.
The WordPress Plugin Boilerplate is licensed under the GPL v2 or later; however, if you opt to use third-party code that is not compatible with v2, then you may need to switch to using code that is GPL v3 compatible.
For reference, here's a discussion that covers the Apache 2.0 License used by Bootstrap.
Note that if you include your own classes, or third-party libraries, there are three locations in which said files may go:
plugin-name/gutenberg
is for all about the new WordPress editor: Gutenbergplugin-name/core
is for all core and loader functionalityplugin-name/admin
is for all admin-specific functionalityplugin-name/public
is for all public-facing functionalityplugin-name/includes
is where functionality shared between the admin area and the public-facing parts of the site reside -> here we can put libraries and helpers
Note that previous versions of the Boilerplate did not include Plugin_Name_Loader
but this class is used to register all filters and actions with WordPress.
The example code provided shows how to register your hooks with the Loader class.
The previous version of the WordPress Plugin Boilerplate included support for a number of different projects such as the GitHub Updater.
These tools are not part of the core of this Boilerplate, as I see them as being additions, forks, or other contributions to the Boilerplate.
The same is true of using tools like Grunt, Composer, etc. These are all fantastic tools, but not everyone uses them. In order to keep the core Boilerplate as light as possible, these features have been removed and will be introduced in other editions, and will be listed and maintained on the project homepage.
The WordPress Plugin Boilerplate was started in 2011 by Tom McFarlin and has since included a number of great contributions. In March of 2015 the project was handed over by Tom to Devin Vinson.
The current version of the Boilerplate was developed in conjunction with Josh Eaton, Ulrich Pogson, and Brad Vincent.
The homepage is based on a design as provided by HTML5Up, the Boilerplate logo was designed by Rob McCaskill of BungaWeb, and the site favicon
was created by Mickey Kay.
Since summer of 2018 is compatible with the new editor of WordPress: Gutenberg.
The new features about Gutenberg have the dependencies to work base on create-guten-block - Ahmad Awais.
If you’re interested in writing any documentation or creating tutorials please let me know .