WordPress Plugin Boilerplate

A standardized, organized, object-oriented foundation for building high-quality WordPress Plugins.

Contents

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.

Features

• 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.

Installation

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 to example-me
• change plugin_name to example_me
• change plugin-name to example-me
• change Plugin_Name to Example_Me
• change PLUGIN_NAME_ to EXAMPLE_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.

Rename files & directories, and replace content in files via Windows PowerShell:

# Define variables
$newSubstring = "aryo-activity-log-backup"

# Rename files and folders
Get-ChildItem -Recurse | Where-Object { $_.Name -like "*plugin-name*" } | ForEach-Object {
    # Replace "plugin-name" with the new substring
    $newName = $_.Name.Replace("plugin-name", $newSubstring)  # Use the .Replace method
    if ($newName -ne $_.Name) {
        Rename-Item $_.FullName -NewName $newName  # Rename the item if the name has changed
    }
}

# Function to convert a string to PascalCase
function Convert-ToPascalCase {
    param (
        [string]$inputString
    )
    
    # Split the input string and capitalize the first letter of each part
    $pascalCase = ($inputString -split '-') | ForEach-Object {
        $_.Substring(0, 1).ToUpper() + $_.Substring(1).ToLower()
    }

    return $pascalCase -join '_'  # Join the parts with underscores
}

# Function to convert a string to snake_case
function Convert-ToSnakeCase {
    param (
        [string]$inputString
    )
    return ($inputString -replace '-', '_' -replace ' ', '_').ToLower()  # Replace hyphens and spaces with underscores and convert to lowercase
}

# Function to convert a string to Upper Snake Case (all uppercase with underscores)
function Convert-ToUpperSnakeCase {
    param (
        [string]$inputString
    )
    return (Convert-ToSnakeCase -inputString $inputString).ToUpper()  # Convert to snake_case and then to uppercase
}

# Replace content in PHP files
Get-ChildItem -Recurse -Filter *.php | ForEach-Object {
    $content = Get-Content $_.FullName  # Read the content of the file

    # Generate the correct values for replacement
    $newPascalCase     = Convert-ToPascalCase -inputString $newSubstring
    $newSnakeCase      = Convert-ToSnakeCase -inputString $newSubstring
    $newUpperSnakeCase = Convert-ToUpperSnakeCase -inputString $newSubstring

    # Create an array to hold modified content
    $modifiedContent = @()

    # Loop through each line in the content
    foreach ($line in $content) {
        # Use a temporary variable for replacements
        $modifiedLine = $line  # Start with the original line
        $modifiedLine = $modifiedLine.Replace("PLUGIN_NAME", $newUpperSnakeCase)
        $modifiedLine = $modifiedLine.Replace("Plugin_Name", $newPascalCase)
        $modifiedLine = $modifiedLine.Replace("plugin_name", $newSnakeCase)
        $modifiedLine = $modifiedLine.Replace("plugin-name", $newSubstring)

        # Add the modified line to the array
        $modifiedContent += $modifiedLine
    }

    # Save the modified content back to the file
    Set-Content $_.FullName $modifiedContent
}

WordPress.org Preparation

The original launch of this version of the boilerplate included the folder structure needed for using your plugin on WordPress.org. That folder structure has been moved to its own repo here: https://github.com/DevinVinson/Plugin-Directory-Boilerplate

Recommended Tools

i18n Tools

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:

• Poedit
• makepot
• i18n

Any of the above tools should provide you with the proper tooling to internationalize the plugin.

License

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.

Important Notes

Licensing

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.

Includes

Note that if you include your own classes, or third-party libraries, there are three locations in which said files may go:

• plugin-name/includes is where functionality shared between the admin area and the public-facing parts of the site reside
• plugin-name/admin is for all admin-specific functionality
• plugin-name/public is for all public-facing functionality

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.

What About Other Features?

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.