Plugin boilerplate WordPress — WPPB vs Underscores vs custom

Build plugin từ con số không mỗi project lãng phí 4-8 giờ setup boilerplate cơ bản. Boilerplate là template plugin có sẵn structure, autoload, test config, build pipeline — chỉ cần fork rồi customize logic nghiệp vụ.

Bài này so sánh 3 boilerplate phổ biến 2026 (WPPB, Underscores, custom inhouse), PSR-4 autoload qua Composer, OOP vs procedural, modular feature toggle, PHPUnit setup, GitHub Actions deploy.

Plugin boilerplate là gì và 3 lý do team dev nào cũng nên dùng

Boilerplate plugin là template có scaffold sẵn folder layout, autoload, hook lifecycle, sample feature và test config. Dev fork boilerplate rồi customize cho project mới, tiết kiệm 4-16 giờ setup so với gõ từ file trống.

Khác với code generator (vd wp scaffold plugin) chỉ tạo skeleton tối thiểu, boilerplate full bao gồm cả OOP architecture, dependency injection, build pipeline và CI workflow chạy được ngay.

3 lợi ích đo đếm được khi dùng boilerplate

Lợi ích boilerplate không chỉ là tiết kiệm thời gian. Ba giá trị bền vững giúp team dev quy mô nhỏ tới trung bình duy trì chất lượng code dài hạn.

• Consistency cross-plugin: 5 plugin team viết có cùng folder structure, naming convention, hook pattern — dev mới onboard chỉ học 1 boilerplate là nắm cả bộ codebase.
• Best practice baked-in: security check (ABSPATH guard), i18n setup, autoload PSR-4, sanitize và escape pattern đã setup sẵn — không phải nhớ list mỗi project.
• Test và CI/CD sẵn sàng: PHPUnit config, GitHub Actions workflow, deploy script đã có — push code lên repo trong 5 phút thay vì 5 ngày setup môi trường.

Khi nào KHÔNG cần boilerplate

Boilerplate có overhead về learning curve và file size. Một số trường hợp dùng plugin skeleton minimal hợp lý hơn.

• Plugin one-off dưới 200 dòng: snippet small như “disable XML-RPC” hay “remove emoji script” không cần class hay autoload — file đơn 50 dòng đủ dùng.
• Demo hoặc proof-of-concept: code throwaway test 1 idea — overhead Composer và PHPUnit không cần thiết.
• Dev solo không submit Directory: không có team onboard, không cần consistency cross-project — boilerplate over-engineer.

So sánh WPPB, Underscores Plugin và custom inhouse build

Ba boilerplate phổ biến nhất 2026 cho plugin WordPress là WordPress Plugin Boilerplate (WPPB) của Devin Vinson, Underscores Plugin của cộng đồng và custom inhouse build cho team từ 3 dev trở lên. Lựa chọn dựa trên scale plugin, kinh nghiệm OOP và workflow build asset.

WordPress Plugin Boilerplate (WPPB)

Repository chính ở github.com/DevinVinson/WordPress-Plugin-Boilerplate, maintain từ 2014, hơn 8.500 stars. OOP class-based, chia rõ Activator, Deactivator, Loader, i18n, Admin và Public.

Composer optional, PHPUnit có sẵn. Phù hợp plugin commercial scale 1.000-10.000 dòng — đủ structure để bán trên marketplace nhưng không quá nặng cho dev mới WordPress.

Underscores Plugin

Inspired bởi underscores starter theme, lighter hơn WPPB và mix procedural với class. Không Composer, không test config — phù hợp plugin nhỏ dưới 500 dòng với single feature.

Maintain bởi cộng đồng nhỏ, không phải dự án chính thức của Automattic. Phù hợp khi cần khởi động nhanh, không muốn học OOP pattern phức tạp ngay từ đầu.

Custom inhouse build

Team scale 3+ dev viết hơn 3 plugin mỗi năm: ROI cao khi build boilerplate riêng theo convention team. Investment ban đầu 8-16 giờ setup, tiết kiệm 6-10 giờ cho mỗi plugin sau.

Pattern thường bao gồm Composer PSR-4, webpack build asset, GitHub Actions CI và custom CLI generator (vd lệnh w22 plugin:new my-plugin) — onboarding dev mới mất 1-2 ngày là nắm cả workflow.

PSR-4 autoload và Composer cho dependency plugin

PSR-4 là chuẩn autoload PHP do PHP-FIG đề xuất — map namespace sang folder structure. Thay vì require_once hàng chục class, Composer tự load khi class được khởi tạo lần đầu.

File composer.json cho plugin

{
  "name": "web22dev/w22-forms",
  "description": "AJAX contact form plugin với tích hợp HubSpot và ZaloPay",
  "type": "wordpress-plugin",
  "license": "GPL-2.0-or-later",
  "require": {
    "php": ">=8.0"
  },
  "require-dev": {
    "wp-coding-standards/wpcs": "^3.0",
    "phpunit/phpunit": "^9.0",
    "brain/monkey": "^2.6"
  },
  "autoload": {
    "psr-4": {
      "Web22Forms": "includes/"
    }
  },
  "scripts": {
    "test": "phpunit",
    "lint": "phpcs --standard=WordPress includes/"
  }
}

Bootstrap autoload trong main file

// w22-forms.php (main file)
require_once __DIR__ . '/đơn vị cung cấp/autoload.php';

use Web22FormsPlugin;
use Web22FormsForm_Handler;

$plugin = Plugin::get_instance();
$plugin->register_handler(new Form_Handler());
$plugin->run();

Class Web22FormsForm_Handler auto-load từ file includes/Form_Handler.php — không cần require_once thủ công cho từng class.

3 pitfall khi dùng Composer trong plugin Directory

Composer mang lại dependency management mạnh nhưng cũng tạo rủi ro xung đột khi plugin chạy chung site với plugin khác cũng dùng Composer. Ba điểm cần xử lý trước khi release.

• Xung đột version đơn vị cung cấp: 2 plugin cùng dùng Guzzle version khác nhau sẽ xung đột — phải phạm vi namespace bằng PHP-Scoper trước khi build production.
• Đơn vị cung cấp folder không commit Git: add /đơn vị cung cấp/ vào .gitignore, build pipeline tự composer install --no-dev trước khi đóng zip release.
• Autoload optimize bắt buộc: chạy composer dump-autoload -o trong production để chuyển PSR-4 lookup sang classmap nhanh hơn 2-3 lần.

Khi nào chọn OOP còn khi nào dùng procedural

Procedural (function thuần) đơn giản và đủ cho plugin nhỏ. OOP cần thiết khi plugin có state phức tạp, dependency rõ ràng hoặc multiple instance cùng tồn tại.

Procedural đủ trong trường hợp nào

• Plugin dưới 500 dòng, 1-2 feature độc lập: snippet kiểu “disable comments” hay “remove dashboard widget” viết function thuần là rõ nhất.
• Không có state nội bộ: mọi function pure, input-output rõ ràng — không cần object để giữ context.
• Team 1-2 dev, không onboarding nhiều: không có gánh nặng “đọc class hierarchy mới hiểu code” — procedural dễ scan hơn.

OOP cần khi nào

• Plugin scale trên 1.000 dòng hoặc 5 feature trở lên: tách module thành class giúp navigate codebase nhanh — IDE jump-to-definition hoạt động tốt hơn với class.
• Có state cần track: cache layer, session manager, queue worker đều cần object giữ context giữa các call.
• Cần dependency injection để unit test: mock dependency dễ hơn khi inject qua constructor — function thuần global khó isolate.
• Multiple plugin share base class: boilerplate inhouse có abstract class chung — tận dụng inheritance để reuse logic.

Modular feature toggle cho plugin scale

Plugin scale có nhiều feature optional, người dùng không cần tất cả. Pattern feature toggle cho phép bật tắt từng module qua admin Settings — không phải comment code hay deploy version khác nhau.

Pattern register feature qua array

// includes/Plugin.php
public function register_features() {
    $features = get_option('w22_forms_features', [
        'ajax_form'    => true,
        'hubspot'      => false,
        'mailchimp'    => false,
        'recaptcha'    => true,
    ]);
    foreach ($features as $key => $enabled) {
        if (!$enabled) continue;
        $class = 'Web22FormsFeatures' . str_replace('_', '', ucwords($key, '_'));
        if (class_exists($class)) (new $class())->register();
    }
}

3 lợi ích của feature toggle

Feature toggle không chỉ là tiện nghi UX. Ba giá trị kỹ thuật làm plugin dễ bảo trì hơn rõ rệt khi codebase phình ra.

• Bật tắt không deploy: user toggle qua admin, không cần dev push code mới — phù hợp SaaS plugin có tier feature khác nhau.
• A/B test feature mới: ship feature flag default off, bật cho 10% user qua remote config — bắt bug sớm trước khi rollout 100%.
• Reduce attack surface: feature off không load class, không enqueue script — giảm bề mặt tấn công cho user không dùng tính năng đó.

Testing setup với PHPUnit, WP_Mock và Brain Monkey

Test plugin WordPress có 3 stack chính 2026: PHPUnit cho unit test cơ bản, WP_Mock cho mock WordPress function, Brain Monkey cho mock chain action filter phức tạp.

Bootstrap PHPUnit cho plugin

// tests/bootstrap.php
require_once dirname(__DIR__) . '/đơn vị cung cấp/autoload.php';

WP_Mock::bootstrap();

// Define WP constant nếu code reference
if (!defined('ABSPATH')) define('ABSPATH', '/var/www/');
if (!defined('WPINC')) define('WPINC', 'wp-includes');

Sample test case cho Form_Handler

// tests/Form_Handler_Test.php
use PHPUnitFrameworkTestCase;
use Web22FormsForm_Handler;

class Form_Handler_Test extends TestCase {
    public function test_validates_email() {
        WP_Mock::userFunction('sanitize_email', [
            'args' => ['[email protected]'],
            'return' => '[email protected]',
        ]);
        $handler = new Form_Handler();
        $this->assertTrue($handler->is_valid_email('[email protected]'));
        $this->assertFalse($handler->is_valid_email('invalid'));
    }
}

4 loại test cần cover trong plugin production

Coverage 100% không khả thi và không cần thiết. Bốn loại test ưu tiên sẽ catch khoảng 80% bug trong plugin scale trung bình.

• Unit test cho helper function: validate, sanitize, transform data — function pure dễ test, ROI cao nhất.
• Integration test cho hook chain: kiểm tra hook gọi đúng thứ tự, callback nhận đúng argument — bắt regression khi refactor.
• REST endpoint smoke test: gọi endpoint qua WP_REST_Request giả lập, check response status và schema — đảm bảo không vỡ contract với client.
• Activation và uninstall test: chạy activate, verify table tạo đúng, chạy uninstall, verify dọn sạch — bắt data orphan sớm.

Build pipeline và deploy với GitHub Actions

Plugin có frontend asset (React block, SCSS) cần build pipeline tự động. Workflow chuẩn 2026 dùng GitHub Actions chạy lint, test, build, đóng zip rồi deploy lên release.

GitHub Actions workflow đầy đủ

# .github/workflows/build.yml
name: Build và Deploy
on:
  push:
    tags: ['v*']
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
      - name: Composer install
        run: composer install --no-dev --optimize-autoloader
      - name: Setup Node
        uses: actions/setup-node@v4
        with: { node-version: '20' }
      - name: Build assets
        run: npm ci && npm run build
      - name: Run tests
        run: composer test
      - name: Create zip
        run: |
          mkdir release
          rsync -av --exclude='.git' --exclude='node_modules' --exclude='tests' . release/w22-forms/
          cd release && zip -r w22-forms-${{ github.ref_name }}.zip w22-forms/
      - name: Upload release
        uses: softprops/action-gh-release@v1
        with:
          files: release/*.zip

File và folder phải exclude khi đóng zip production

Zip release không nên chứa file dev chỉ phục vụ build. Loại trừ đúng giảm size zip 30-60% và tránh leak thông tin nội bộ.

• node_modules và đơn vị cung cấp test: chỉ giữ đơn vị cung cấp production (composer install –no-dev), bỏ test folder của đơn vị cung cấp — tiết kiệm 20-40MB tuỳ dependency.
• Mã nguồn build: src/, scss/, jsx/ chỉ cần trong dev — production chỉ ship file build đã minify.
• Config dev: .git/, .github/, tests/, phpunit.xml, .phpcs.xml — không liên quan runtime plugin, loại sạch.
• Lock file tuỳ workflow: composer.lock và package-lock.json giữ nếu deploy qua Composer trên server, bỏ nếu zip-and-upload thuần.

Câu hỏi thường gặp

Tài nguyên và bước tiếp theo

Boilerplate là nền — sau khi pick được template phù hợp, các topic chuyên sâu khác giúp plugin production-grade về cả kỹ thuật lẫn quy trình maintain.

• Tạo plugin WordPress từ đầu — 7 bước build chuẩn 2026 — hiểu fundamental trước khi fork boilerplate có sẵn.
• Hook, action và filter WordPress — concept fundamental 2026 — boilerplate hook đúng cách cần nắm chain action filter.
• register_post_type WordPress — 25 tham số + show_in_rest 2026 — register CPT trong plugin với capability custom.
• register_taxonomy WordPress — hierarchical vs flat + term meta 2026 — phân loại CPT qua taxonomy có term meta.
• Dịch vụ thiết kế website WordPress chuyên nghiệp — tham khảo gói thi công plugin custom theo trao đổi yêu cầu.

Cần Web22 setup boilerplate plugin sẵn sàng cho team từ Composer đến CI/CD? Thi công WordPress theo yêu cầu — block theme 2026 — bàn giao kèm PSR-4 autoload, PHPUnit, GitHub Actions và CLI generator riêng cho team.