WordPress Plugin Boilerplate Powered

https://github.com/wpbp/wordpress-plugin-boilerplate-powered
Admin
A foundation for building WordPress plugins following PSR-4 standards, featuring a code generator,...
Tokens:3,780
Snippets:22
Trust Score:7.1
License:GPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### GitHub Actions Workflow for Integration

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

An example GitHub Actions workflow file (.github/workflows/integrate.yml) used for continuous integration within the WordPress Plugin Boilerplate Powered project. It defines steps for checking out code, setting up PHP, installing dependencies, and running tests.

```YAML
name: Integrate

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.1'
    - name: Install Composer dependencies
      run: composer install --prefer-dist --no-progress --no-suggest
    - name: Run PHPStan
      run: vendor/bin/phpstan analyse --level=5 src/ --configuration=phpstan.neon
    - name: Run GrumPHP
      run: vendor/bin/grumphp run
```

--------------------------------

### Shortcode Example

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Provides a basic example of how to create and register a custom shortcode within WordPress. Shortcodes allow users to embed dynamic content into posts and pages using simple tags.

```PHP
// Example of a custom shortcode
function my_custom_shortcode( $atts ) {
    // Default attributes
    $atts = shortcode_atts( array(
        'name' => 'World'
    ), $atts, 'my_shortcode' );

    return 'Hello, ' . esc_html( $atts['name'] ) . '!';
}
add_shortcode( 'my_shortcode', 'my_custom_shortcode' );

// Usage in content: [my_shortcode name="User"]
```

--------------------------------

### Transient API Examples

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Demonstrates the usage of WordPress's Transient API for caching data. Transients are temporary cached data that can expire, useful for performance optimization.

```PHP
// Example of using WordPress Transients API
$transient_key = 'my_plugin_data_cache';
$cached_data = get_transient( $transient_key );

if ( false === $cached_data ) {
    // Data not found in transient, fetch it
    $data_to_cache = fetch_external_data(); // Your function to get data
    $expiration_time = HOUR_IN_SECONDS; // Cache for 1 hour

    set_transient( $transient_key, $data_to_cache, $expiration_time );
    $cached_data = $data_to_cache;
}

// Use $cached_data here
```

--------------------------------

### PSR-4 Autoloading Extension Example

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

A PHP code snippet demonstrating the extended PSR-4 autoloading mechanism used in the boilerplate. This example from class-initialize.php shows how classes are loaded based on request type and folder structure, going beyond standard Composer autoloading.

```PHP
<?php

namespace YourPluginNamespace\Engine;

use Composer\Autoload\ClassLoader;

class Initialize {
    private ClassLoader $loader;

    public function __construct(ClassLoader $loader) {
        $this->loader = $loader;
        $this->register_namespace();
    }

    private function register_namespace(): void {
        // Example: Registering a custom namespace mapping
        // This could be extended to map based on request type or folder structure
        $this->loader->addPsr4('YourPluginNamespace\', plugin_dir_path(__FILE__) . '../');
    }

    // ... other initialization methods ...
}
```

--------------------------------

### WP_Query Loop with Generators

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/wiki/Cool-libraries

Demonstrates how to use PHP generators with WordPress's WP_Query to efficiently loop through posts. This approach can be more memory-efficient for large queries. It includes a generator function and an example of how to display recent post titles.

```php
<?php
/**
 * Plugin Name: WP_Query Generators
 * Description: Demonstrates using generators with WP_Query.
 * Version: 1.0
 * Author: gmazzap
 */

// Prevent direct access
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Generator function to yield posts from WP_Query.
 *
 * @param array $args WP_Query arguments.
 * @yield WP_Post The next post object.
 */
function wp_query_generator( array $args = [] ) {
    $query = new WP_Query( $args );

    if ( $query->have_posts() ) {
        while ( $query->have_posts() ) {
            $query->the_post();
            yield $query->post; // Yield the current post object
        }
    }

    // Reset post data after the loop
    wp_reset_postdata();
}

/**
 * Example usage: Displaying post titles from the last 10 posts.
 */
function display_recent_post_titles() {
    echo '<h2>Recent Post Titles:</h2>';
    echo '<ul>';

    $args = [
        'posts_per_page' => 10,
        'post_status'    => 'publish',
        'orderby'        => 'date',
        'order'          => 'DESC',
    ];

    // Iterate through the posts using the generator
    foreach ( wp_query_generator( $args ) as $post ) {
        // $post is a WP_Post object
        echo '<li>' . esc_html( $post->post_title ) . '</li>';
    }

    echo '</ul>';
}

// Hook the example function to a WordPress action, e.g., the admin footer
add_action( 'admin_footer', 'display_recent_post_titles' );

// You could also use it directly in a theme template or shortcode.
// Example for a shortcode:
/*
add_shortcode( 'recent_posts_generator', 'display_recent_post_titles' );
*/

```

--------------------------------

### WPBP Generator CLI Commands

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Commands to generate and manage a WordPress Plugin Boilerplate Powered project. These commands help in creating configuration files, downloading the boilerplate, and setting up the project structure.

```Shell
wpbp-generator --json
# Generates a new wpbp.json configuration file.

wpbp-generator
# Downloads WPBP and extracts it to a new folder, removing unwanted parts based on wpbp.json.

cd your-plugin-folder
# Navigates into the newly created plugin directory.

composer install
# Installs Composer dependencies, including development files.

composer --no-dev update
# Updates Composer dependencies, excluding development packages.

composer dumpautoload -o
# Optimizes the Composer autoloader for production.

npm install
# Installs Node.js packages required for frontend assets.

npm run plugin-zip
# Zips the plugin files for distribution.
```

--------------------------------

### WordPress Plugin Metadata Specification

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/plugin-name/README.txt

Defines the standard metadata fields required in a WordPress plugin's readme.txt file. This includes essential information for plugin directories and user understanding.

```APIDOC
Plugin Name:
  - Title of the plugin.

Contributors:
  - Comma-separated list of WordPress.org user IDs.

Donate link:
  - URL for donations (e.g., http://example.com/).

Tags:
  - Comma-separated list of relevant tags (max 12).

Requires at least:
  - Minimum WordPress version required (e.g., 4.9).

Tested up to:
  - Highest WordPress version tested successfully (e.g., 5.3).

Stable tag:
  - Subversion tag of the latest stable version, or 'trunk'.

License:
  - Name of the license (e.g., GPLv3 or later).

License URI:
  - URL for the license details (e.g., http://www.gnu.org/licenses/gpl-3.0.html).

Requires PHP:
  - Minimum PHP version required (e.g., 7.0).

Short description:
  - A brief, 150-character maximum description without markup.

Description:
  - The main, detailed description of the plugin, supporting Markdown.

Installation:
  - Instructions for installing the plugin, including methods like WordPress Dashboard, Upload, and FTP.
    - Example: Using The WordPress Dashboard:
      1. Navigate to 'Add New' in the plugins dashboard.
      2. Search for 'plugin-name'.
      3. Click 'Install Now'.
      4. Activate the plugin.

Frequently Asked Questions:
  - A section for common questions and their answers.
    - Format: = Question =
      Answer.

Screenshots:
  - Descriptions for plugin screenshots, referencing files in /assets or the stable tag directory.
    - Example: 1. This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif).

Changelog:
  - A record of changes made in each version.
    - Format: = Version Number =
      * Change 1
      * Change 2

Upgrade Notice:
  - Information for users about upgrading to new versions.
    - Format: = Version Number =
      Upgrade notices describe the reason a user should upgrade. No more than 300 characters.
```

--------------------------------

### Composer Configuration for WPBP

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Illustrates the use of composer.json for managing project dependencies and autoloading in a WordPress Plugin Boilerplate Powered project. It highlights the importance of optimizing the autoloader for production.

```JSON
{
  "name": "your-vendor/your-plugin",
  "description": "Your WordPress plugin description.",
  "type": "wordpress-plugin",
  "license": "GPL-2.0-or-later",
  "authors": [
    {
      "name": "Your Name",
      "email": "your.email@example.com"
    }
  ],
  "require": {
    "php": ">=7.4",
    "composer/installers": "^1.10"
  },
  "autoload": {
    "psr-4": {
      "YourPluginNamespace\\": "plugin-name/engine/"
    }
  },
  "require-dev": {
    "phpro/grumphp": "^1.7",
    "phpstan/phpstan": "^1.9"
  }
}
```

--------------------------------

### CMB2 Options Page Integration

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Demonstrates how to integrate CMB2 (a metabox and custom field framework) to create custom options pages within the WordPress admin area for plugin settings.

```PHP
// Example of creating an options page with CMB2
function my_plugin_register_options_page() {
    $args = array(
        'page_title' => 'My Plugin Settings',
        'menu_title' => 'My Plugin',
        'menu_slug'  => 'my-plugin-settings',
        'capability' => 'manage_options',
        'redirect'   => false
    );
    $cmb_options = new_cmb2_box( $args );

    $cmb_options->add_field( array(
        'name'    => 'API Key',
        'desc'    => 'Enter your API key',
        'id'      => 'my_plugin_api_key',
        'type'    => 'text'
    ) );
}
add_action( 'cmb2_admin_init', 'my_plugin_register_options_page' );
```

--------------------------------

### Template System Integration

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Refers to a system for loading template files, potentially with features like autosearch, multilanguage folder support, or specific structures for email templates. This snippet would show template loading functions.

```PHP
// Placeholder for template-system functionality
// This snippet would likely involve a custom function to load template files,
// potentially searching in multiple directories or handling theme overrides.
```

--------------------------------

### Import/Export Settings

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Provides functionality to import and export plugin settings, often used for backup or migration purposes. This typically involves creating forms for upload/download and handling data serialization (e.g., JSON, XML).

```PHP
// Placeholder for impexp-settings functionality
// This snippet would include functions for exporting settings (e.g., to JSON)
// and importing settings (e.g., from an uploaded file), often using
// WordPress options API and admin page hooks.
```

--------------------------------

### Plugin Upgrade Procedure

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Defines a basic procedure that executes automatically when the plugin is updated. This is commonly used for database schema changes, option updates, or data migrations.

```PHP
// Placeholder for upgrade-procedure functionality
// This snippet would typically use the 'upgrader_process_complete' hook
// or check the plugin version stored in options to trigger update routines.
```

--------------------------------

### WP-CLI Support

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Adds custom commands to WP-CLI, the command-line interface for WordPress. This allows plugin management, data manipulation, or other tasks to be performed via the terminal.

```PHP
// Placeholder for WP-CLI support functionality
// This snippet would involve creating a PHP class that extends WP_CLI_Command
// and registering it using WP_CLI::add_command().
```

--------------------------------

### Dashicons as Dependency

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Ensures that WordPress Dashicons are loaded as a dependency for admin stylesheets, allowing easy use of WordPress's built-in icon set in the admin area.

```PHP
// Example of enqueuing admin styles with Dashicons dependency
function my_plugin_admin_styles() {
    wp_enqueue_style( 'my-plugin-admin-style', plugins_url( '/css/admin-style.css', __FILE__ ), array('dashicons'), '1.0' );
}
add_action( 'admin_enqueue_scripts', 'my_plugin_admin_styles' );
```

--------------------------------

### Block Support Integration

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Enables or configures support for Gutenberg block editor features within custom post types or themes. This involves registering block assets and potentially adding theme support for editor features.

```PHP
// Placeholder for block support functionality
// This snippet would involve functions like add_theme_support('wp-block-styles'),
// register_block_type, or enqueueing block assets.
```

--------------------------------

### Custom Capabilities with CPTs and Taxonomy Support

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Implements custom user capabilities for managing custom post types (CPTs) and taxonomies. This enhances WordPress's role and capability system for granular access control.

```PHP
// Placeholder for capability-system functionality
// This snippet would involve functions like add_cap(), remove_cap(),
// and potentially custom role management, tied to CPT and taxonomy registration.
```

--------------------------------

### wp_localize_script for Frontend Data

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Demonstrates how to use `wp_localize_script` to pass PHP variables and data securely to JavaScript on the frontend. This is crucial for making PHP data available to client-side scripts.

```PHP
// Example of wp_localize_script usage
function my_plugin_enqueue_scripts() {
    wp_enqueue_script( 'my-plugin-script', plugins_url( '/js/script.js', __FILE__ ), array('jquery'), '1.0', true );

    $php_data = array(
        'ajax_url' => admin_url( 'admin-ajax.php' ),
        'nonce'    => wp_create_nonce( 'my_plugin_nonce' )
    );
    wp_localize_script( 'my-plugin-script', 'myPluginData', $php_data );
}
add_action( 'wp_enqueue_scripts', 'my_plugin_enqueue_scripts' );
```

--------------------------------

### REST API Support

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Enables or integrates with the WordPress REST API, allowing data to be exposed or manipulated via HTTP requests. This involves registering custom endpoints or modifying existing ones.

```PHP
// Placeholder for rest support functionality
// This snippet would involve using the 'rest_api_init' hook to register
// custom REST API routes and callbacks.
```

--------------------------------

### CPT Search Support

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Enhances the global WordPress search functionality to include custom post types (CPTs) managed by the plugin. This requires modifying the main WordPress query or using filters like 'pre_get_posts'.

```PHP
// Placeholder for cpt-search-support functionality
// This snippet would typically hook into 'pre_get_posts' to modify the query
// to include specific post types when a search is performed.
```

--------------------------------

### Donate Link in Plugin List

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Integrates a 'donate' link into the plugin description area within the WordPress admin's plugin list. This is a common way to solicit support for plugins. It likely uses the 'plugin_row_meta' filter.

```PHP
// Placeholder for donate-link-plugin-list functionality
// This snippet would typically use the 'plugin_row_meta' filter to add
// a custom link to the plugin's metadata row in the plugins list.
```

--------------------------------

### Frontend Body Class

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Adds a specific CSS class to the `<body>` tag on the frontend, based on the plugin's slug or identifier. This allows for targeted styling of plugin-specific elements. It uses the 'body_class' filter.

```PHP
// Placeholder for body-class functionality
// This snippet would use the 'body_class' filter to add a custom class
// to the body tag, often based on the plugin's directory name or slug.
```

--------------------------------

### Bubble Notification for Pending CPTs

Source: https://github.com/wpbp/wordpress-plugin-boilerplate-powered/blob/master/README.md

Adds a visual notification to custom post types (CPTs) that have pending items, improving backend workflow visibility. This snippet likely involves WordPress admin hooks and custom post type status checks.

```PHP
// Placeholder for bubble-notification-pending-cpt functionality
// This snippet would typically involve hooks like 'admin_notices' or
// custom column additions to display counts of pending CPTs.
```
Tokens:
Raw