Download the PHP package larsgowebdev/wp-battery without Composer

WP-Battery

WP-Battery is a WordPress MU-Plugin that makes WordPress theme development easier. It combines Advanced Custom Fields Pro, Timber, and WordPress Block Editor into one simple setup tool. The plugin handles common theme tasks through file-based configuration and a simple API, reducing boilerplate code and speeding up development.

Blocks, pages, menus and options can be added following simple conventions. Adding them is even easier and fastest with our recommended companion Plugin: WP-Battery CLI

Features

• Twig Templates:
  • Leverage the power and beauty of Twig in your WordPress, thanks to the amazing Timber!
  • Templates can be used for blocks and pages
• ACF Pro Blocks:
  • Create your own ACF Pro Blocks easily
  • optionally: disable core-blocks and limit yourself to your own ACF Pro Blocks
• Supercharging ACF:
  • Automatically synchronize all ACF Pro field groups you create into your theme directory
• Menus and Option Pages:
  • Automatic registration of WP menus and ACF Pro Options Pages
  • Simple file-based configuration
• Enable Vite.js for your WordPress frontend:
  • WP-Battery is ready for Vite-Asset-Collector-WP
• Asset Management:
  • Separate frontend and admin CSS/JS inclusion
  • Option to include block specific CSS/JS
• Theme Support Management: Easily enable WordPress theme features
• WordPress Cleanup: Don't copy-paste the same snippets into your functions.php over and over. WP-Battery can:
  • Add theme support
  • Remove comments
  • Enable SVG uploads
  • ... and much more in the future
• Contact Form 7 Integration:
  • Custom file-based template support

Requirements

• WordPress >= 6.5
• PHP 8.0+
• Timber >= 2.0
• Advanced Custom Fields PRO >= 6.3

Additional support for:

• Contact Form 7

Installation

In a WordPress composer based setup with Bedrock, this plugin will be automatically symlinked into your web/app/mu-plugins directory, and become available in your WP.

Create a new instance of WP-Battery in your theme's functions.php

Usage

Initialize the plugin in your theme's functions.php:

Setting up your own blocks, pages & more

💡 Development Tip
Consider using WP-Battery CLI to automate the creation of components and folder structure:

Start by creating a wpb folder in your theme directory. This folder will contain all your templates, blocks, and configurations.

Directory Structure

💡 Quick Start (recommended)
Initialize this entire structure automatically:

Creating Blocks

💡 Quick Start (recommended)
Create blocks quickly using WP-Battery CLI:

Create WPB blocks manually

If you need to add or modify blocks manually or just want to dig deeper:

1. Create a folder blocks in your wpb directory
2. For each block, create a new folder (e.g., project-info)
3. Add required files:

block.json

block-template.twig

Create project-info-block-template.twig:

block-renderer.php (Optional)

Create project-info-block-renderer.php if you need additional data processing:

$context will be made available in your block's twig template

Creating Page Templates

💡 Quick Start (recommended)
Create page templates easily using WP-Battery CLI:

In-Depth: Create WPB pages manually

If you need to add or modify pages manually or just want to dig deeper:

1. Create a folder pages in your wpb directory
2. For each template type, create a new folder (e.g., standard)
3. Add required files:

page-template.twig

Create standard-page-template.twig:

page-renderer.php (Optional)

Create standard-page-renderer.php if you need additional data processing:

$context will be made available in your page's twig template

Registering Menus

💡 Quick Start (recommended)
Create menu configurations quickly using WP-Battery CLI:

In-Depth: Register menus manually

If you need to add or modify menus manually or just want to dig deeper:

1. Create a folder menus in your wpb directory
2. Add PHP files for each menu configuration:

Registering ACF Options Pages

💡 Quick Start (recommended)
Create options pages easily using WP-Battery CLI:

In-Depth: Register option pages manually

If you need to add or modify menus manually or just want to dig deeper:

1. Create a folder options in your wpb directory
2. Add PHP files for each options page:

Additional Features explained

Managing Template Partials

1. Create a folder template-parts in your wpb directory
2. Organize partials in subfolders (e.g., blocks/, pages/)
3. Reference partials in your templates:

ACF Sync

When enableACFSync is enabled in your configuration:

• ACF field group changes are synchronized to JSON files in the acf-sync directory
• One JSON file per field group
• Important: In production environments, changes deployed via code must be synchronized manually

Contact Form 7 Templates

This enables you to keep your CF7 templates in files.

1. Create a folder cf7-templates in your wpb directory
2. Add your Contact Form 7 template files here
3. Reference them in your configuration using the form hash:

Configuration Reference

Full Configuration Example

Here's a comprehensive example showing all available options:

Settings explained

Theme Support (themeSupport)

Array of WordPress theme features to enable. Common options include:

Block Registration (registerBlocks)

When enabled, automatically registers all block.json files found in your theme's blocks directory.

Menu Registration (registerMenus)

When enabled, processes menu configuration files from your theme's menu directory.

ACF Options Pages (registerOptions)

Automatically registers ACF options pages from configuration files.

ACF Sync (enableACFSync)

Enables ACF field synchronization using PHP files.

SVG Upload Support (allowSVGUploads)

Enables SVG file uploads in the WordPress media library.

ACF-Only Blocks (disallowNonACFBlocks)

Restricts the block editor to only show ACF blocks.

Comment System (disableComments)

Completely removes WordPress comment functionality.

Vite.js Integration (enableViteAssets, viteBuildDir, viteEntryPoint)

Configure Vite.js asset building:

Frontend Asset Inclusion

Include CSS and JavaScript files in the frontend:

Admin Asset Inclusion

Include CSS and JavaScript files in the admin area:

Contact Form 7 Templates (contactForm7Templates)

Map Contact Form 7 forms to Twig templates:

Cache Management

The plugin includes a caching system for better performance. You can manage it using:

License

This project is licensed under the GPL-2.0 License - see the LICENSE file for details.