PHPackages                             larsgowebdev/wp-battery - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. larsgowebdev/wp-battery

ActiveWordpress-muplugin[Framework](/categories/framework)

larsgowebdev/wp-battery
=======================

WordPress theme development framework, uniting ACF Pro, Timber and Vite

0.7.3(1y ago)01491GPL-2.0-or-laterPHPPHP >=8.1

Since Oct 31Pushed 1y ago1 watchersCompare

[ Source](https://github.com/larsgowebdev/wp-battery)[ Packagist](https://packagist.org/packages/larsgowebdev/wp-battery)[ RSS](/packages/larsgowebdev-wp-battery/feed)WikiDiscussions production Synced 1mo ago

READMEChangelogDependencies (3)Versions (7)Used By (1)

WP-Battery
==========

[](#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](https://github.com/larsgowebdev/wp-battery-cli)

Features
--------

[](#features)

- **Twig Templates**:
    - Leverage the power and beauty of [Twig](https://twig.symfony.com/) in your WordPress, thanks to the amazing [Timber](https://github.com/timber/timber)!
    - Templates can be used for blocks and pages
- **ACF Pro Blocks**:
    - Create your own [ACF Pro Blocks](https://www.advancedcustomfields.com/resources/blocks/) easily
    - optionally: disable core-blocks and limit yourself to your own ACF Pro Blocks
- **Supercharging ACF**:
    - Automatically synchronize all [ACF Pro](https://www.advancedcustomfields.com/pro/) field groups you create into your theme directory
- **Menus and Option Pages**:
    - Automatic registration of WP menus and [ACF Pro Options Pages](https://www.advancedcustomfields.com/resources/options-page/)
    - Simple file-based configuration
- **Custom Post Type and Taxonomy Registration**:
    - Register your custom post types and taxonomies from separate configuration files
    - Simplified registration based on structure and convention
- **Enable [Vite.js](https://vite.dev/) for your WordPress frontend**:
    - WP-Battery is ready for [Vite-Asset-Collector-WP](https://github.com/larsgowebdev/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
------------

[](#requirements)

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

### Additional support for:

[](#additional-support-for)

- Contact Form 7

Installation
------------

[](#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.

```
composer require larsgowebdev/wp-battery
```

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

Usage
-----

[](#usage)

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

```
$wpBattery = new WPBattery(
    themeNamespace: 'your-theme-name',
    settings: [
        // Your configuration here
    ]
);
```

Setting up your own blocks, pages & more
--------------------------------------------

[](#setting-up-your-own-blocks-pages--more)

> 💡 **Development Tip**
> Consider using [WP-Battery CLI](https://github.com/larsgowebdev/wp-battery-cli) to automate the creation of components and folder structure:
>
> ```
> wp init-wpb              # Creates the full directory structure
> wp create-wpb-block      # Creates new blocks
> wp create-wpb-page       # Creates page templates
> wp create-wpb-menu       # Creates menu configurations
> wp create-wpb-options    # Creates options pages
> ```

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

### Directory Structure

[](#directory-structure)

```
wpb/
├── acf-sync/              # ACF field group JSON files
├── blocks/               # Block templates and renderers
├── cf7-templates/        # Contact Form 7 templates
├── menus/                # Menu configurations
├── options/              # ACF options pages
├── pages/                # Page templates
└── template-parts/       # Reusable template parts

```

> 💡 **Quick Start (recommended)**
> Initialize this entire structure automatically:
>
> ```
> wp init-wpb
> ```

### Creating Blocks

[](#creating-blocks)

> 💡 **Quick Start (recommended)**
> Create blocks quickly using [WP-Battery CLI](https://github.com/larsgowebdev/wp-battery-cli):
>
> ```
> wp create-wpb-block --name=project-info --title="Project Info"
> ```

#### Create WPB blocks manually

[](#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

[](#blockjson)

```
{
  "name": "acf/project-info",
  "title": "Project Info",
  "description": "Project Info",
  "category": "common",
  "icon": "visibility",
  "keywords": ["project-info"],
  "acf": {
    "mode": "preview",
    "renderCallback": ["Larsgowebdev\\WPBattery\\Renderer\\BlockRenderer", "renderACFBlock"]
  }
}
```

##### block-template.twig

[](#block-templatetwig)

Create `project-info-block-template.twig`:

```
{% block content %}

{% endblock %}
```

##### block-renderer.php (Optional)

[](#block-rendererphp-optional)

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

```