# White Canvas WordPress Plugin Boilerplate
Welcome to the White Canvas Plugin Boilerplate! This boilerplate serves as the foundation for all our WordPress plugins at White Canvas. To get started with your new plugin, follow the steps below:
## Index
1. [Configuring GitLab for Your Plugin](#1-configuring-gitlab-for-your-plugin)
2. [Rename Plugin Folder and Main File](#2-rename-plugin-folder-and-main-file)
3. [Set Up Your Plugin's Composer Configuration](#3-set-up-your-plugins-composer-configuration)
4. [Configure PHPCS](#4-configure-phpcs)
5. [Update package.json](#5-update-packagejson)
6. [Adjust Namespaces, Package Names, and Text Domains](#6-adjust-namespaces-package-names-and-text-domains)
7. [Modify the Main Plugin File](#7-modify-the-main-plugin-file)
8. [Set Up Your Local Environment](#8-set-up-your-local-environment)
9. [Install Dependencies and Build](#9-install-dependencies-and-build)
10. [Update VSCode Settings for Linters](#10-update-vscode-settings-for-linters)
11. [Deployments with GitLab CI/CD](#11-deployments-with-gitlab-cicd)
12. [Plugin Updates and License Key Configuration](#12-plugin-updates-and-license-key-configuration)
---
## 1. Configuring GitLab for Your Plugin
### Repository Creation
1. Navigate to the `plugins` subgroup on GitLab.
2. Create a new repository. Ensure the repository name matches your plugin's slug. For instance, if your plugin is named `awesome-feature`, the repository slug should also be `awesome-feature`.
### Setting Up CI/CD Variables
1. Once your repository is created, go to `Settings` > `CI/CD`.
2. Under the `Variables` section, click on `Add Variable`.
3. Enter the following details:
- **Key**: `PLUGIN_SLUG`
- **Value**: Your plugin slug (e.g., `awesome-feature`).
- **Flags**:
- [ ] Protect variable
- [ ] Mask variable
- [x] Expand variable reference
### Starting with the Plugin Boilerplate
1. Clone the boilerplate repository to your local machine:
```bash
git clone git@gitlab.com:white-canvas/plugins/plugin-boilerplate.git your-plugin-name
```
Replace `your-plugin-name` with your desired plugin name or slug.
2. Navigate to your plugin directory:
```bash
cd your-plugin-name
```
3. Remove the existing Git history:
```bash
rm -rf .git
```
4. Initialize a new Git repository:
```bash
git init
```
5. Add your new repository as the remote:
```bash
git remote add origin git@gitlab.com:white-canvas/plugins/your-plugin-name.git
```
6. Commit and push your changes to the new repository:
```bash
git add .
git commit -m "Initial commit from boilerplate"
git push -u origin master
```
## 2. Rename Plugin Folder and Main File
Before making any changes, rename the plugin folder (`plugin-boilerplate`) and the main plugin file (`plugin-boilerplate.php`) to match your new plugin's name. Ensure your plugin names are in kebab-case, lowercase, and without special characters. For example, if your plugin's name is "Awesome Feature", the folder and main file should be named `awesome-feature` and `awesome-feature.php` respectively.
## 3. Set Up Your Plugin's Composer Configuration
Open the `composer.json` file:
[composer.json](composer.json)
You'll need to make the following changes:
- Update the `name` field to match your plugin's name.
- Modify the `psr-4` namespace from `LISWC` to your desired namespace.
```json
{
"name": "whitecanvas/your-plugin-name",
"autoload": {
"psr-4": {
"YourNamespace\\": "src/"
}
},
```
## 4. Configure PHPCS
Edit the `phpcs.xml` file:
[phpcs.xml](phpcs.xml)
- Set the new namespace you configured in the `composer.json`.
- Change the text domain to a name that describes your plugin.
```xml
```
## 5. Update package.json
Edit the `package.json` file:
[package.json](package.json)
Change the `name` field to match your plugin's slug, but retain the "white-canvas" prefix:
```json
"name": "white-canvas-your-plugin-slug"
```
## 6. Adjust Namespaces, Package Names, and Text Domains
For the following files, update the namespace, package name, and text domain to match what you set in the `composer.json`:
- [Updates.php](src/Admin/Updates.php)
- [Scripts.php](src/Admin/Scripts.php)
Example for `Scripts.php`:
```php
/**
* Admin scripts and styles
*
* @package YourNamespace
*/
namespace YourNamespace\Admin;
```
Similarly, in the [user-key-page.php](templates/user-key-page.php) template, update the package name:
```php
/**
* Page that adds an input field for user plugin credentials.
*
* @package YourNamespace
*/
```
Remember to also update the text domain throughout your plugin. For instance, if you come across:
```php
esc_html_e( 'Insert the key that we provided to allow plugin updates.', 'LISWC' )
```
Replace `'LISWC'` with your new text domain.
## 7. Modify the Main Plugin File
Edit the main plugin file:
[your-plugin-name.php](wp-content/plugins/your-plugin-name/your-plugin-name.php)
Update the plugin comment, package name, and menu title constant to match your new plugin's name.
## 8. Set Up Your Local Environment
Copy the [.env-webpack](.env-webpack) file and rename the copy to `.env`. Then, set your local URL:
```
LOCAL_SERVER_URL=http://your-local-url.com # Replace with your virtualhost URL
```
## 9. Install Dependencies and Build
In the root folder of the plugin, run the following commands:
```bash
composer install
npm install
npm run dev
```
## 10. Update VSCode Settings for Linters
Edit the settings file located at:
[.vscode/settings.json](.vscode/settings.json)
Update the paths to match the new plugin location:
```json
"phpsab.executablePathCS": "wp-content/plugins/your-plugin-name/vendor/bin/phpcs",
"phpsab.executablePathCBF": "wp-content/plugins/your-plugin-name/vendor/bin/phpcbf",
```
For the linters to work correctly, you'll need to reload VSCode. If the linters still don't function as expected, move the `.vscode` folder from:
`wp-content/plugins/your-plugin-name/.vscode`
to the root of your WordPress installation.
## 11. Deployments with GitLab CI/CD
At White Canvas, we use GitLab's CI/CD pipelines to automate the deployment and update processes for our plugins. Here's a brief overview of how it works:
### Merge Requests to `master`
1. **Linters Check**: When you create a merge request targeting the `master` branch, the pipeline will automatically run a series of linters to ensure code quality. This includes checks for PHP, JavaScript, and SCSS.
2. **Merge**: If all linters pass, you can merge the changes into the `master` branch.
### Creating a New Release
1. **Tagging**: After merging your changes, navigate to `Releases` > `New Release` on GitLab.
2. **Versioning**: Create a new tag from the `master` branch. The tag should follow semantic versioning, like `0.0.1`.
3. **Release Notes**: For the release title, use "Updates". In the release notes, start with # Updates and then list the changes in the following format:
```
# Updates
- Hero section
- Added new cta button
- Fixed mobile layout
- Added new footer
```
Once you've created the release, the pipeline will automatically:
1. **Build**: Install npm packages and run the build process. It will also install composer dependencies.
2. **Zip**: After building, the pipeline will clean up unnecessary files and folders, then zip the plugin.
3. **Upload**: The zipped plugin will be uploaded to an AWS S3 bucket.
### Important Notes
- Ensure you've set the `PLUGIN_SLUG` variable in the GitLab CI/CD settings. This variable should match your plugin's slug.
- The pipeline is configured to only run the build and zip stages when a new tag is created. Linters run on merge requests.
---
Adhering to this process ensures that every release of your plugin is built, tested, and deployed consistently. This approach not only elevates the quality of your releases but also streamlines the deployment process.
## 12. Plugin Updates and License Key Configuration
### License Key for Updates
To enable updates for the plugin across all environments (development, staging, and production), a valid license key must be entered. This key can be set through a menu item that the `src/Admin/Updates.php` file creates in the WordPress admin dashboard. If you don't have a license key, request one from an administrator. Without a valid license, updates won't be available.
### License Menu Configuration
The `src/Admin/Updates.php` file is responsible for adding a menu or submenu item in the WordPress admin dashboard for license key configuration:
- If the plugin already has a main menu, the license configuration will be added as a submenu item.
- If the plugin doesn't have a main menu, a new menu will be created specifically for the license configuration.
The title of this menu or submenu will match the name set in the main plugin file under the constant:
```php
define( 'LISWC_MENU_TITLE', 'Plugin Boilerplate' );
```
Ensure that you update the `'Plugin Boilerplate'` value to reflect the name of your plugin.
### Development and Staging Environments
For development and staging environments, ensure the `wp-config.php` file contains the following constant:
```php
define('WC_PLUGIN_FACTORY_DEVELOPMENT', true);
```
With this constant set to `true`, the plugin will allow updates for every release made.
### Production Environment
In a production environment, automatic updates based on every release are not recommended. Instead, ask an administrator to set a specific stable version for the plugin in the plugin updater panel. This ensures that only vetted and stable releases are deployed in production.
---
By integrating this update mechanism and ensuring the license key is correctly set, you ensure that your plugins are always up-to-date in development and staging environments, while maintaining stability and control in production.
---
Congratulations! By following these steps, you've successfully set up your new plugin on GitLab using the White Canvas Plugin Boilerplate. Happy coding!