> For the complete documentation index, see [llms.txt](https://whoisandywhite.gitbook.io/porterwp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whoisandywhite.gitbook.io/porterwp/readme.md).

# Welcome

> **Version:** 1.4.95
>
> **License:** GPLv3 or later
>
> **Requires:** WordPress 6.4+, PHP 8.2+
>
> **Tested through:** WordPress 7.0.3

PorterWP is a developer-first toolkit for building schema-driven WordPress block themes. The plugin reads configuration and theme code from a `porter/` directory in the active theme, leaving the theme in control of its content model, blocks and assets.

* Register custom post types and taxonomies from JSON.
* Register ACF blocks, block styles, patterns and taxonomy-term variations.
* Load theme PHP safely from `porter/inc/`.
* Register public and block-editor assets from one configuration file.
* Cache theme discovery and configuration work in production.
* Add premium faceted filters to Query Loop blocks.

## Requirements

The plugin requires PHP 8.2 or later and WordPress 6.4 or later. PorterWP 1.4.95 is tested through WordPress 7.0.3.

[Advanced Custom Fields PRO](https://www.advancedcustomfields.com/pro/) is the supported requirement for Porter's complete ACF integration. Custom blocks and option pages require PRO APIs; standalone and post-type field groups can still register whenever `acf_add_local_field_group()` is available, including with ACF Free. PorterWP keeps its non-ACF features running, skips each integration whose API is unavailable and shows an administrator notice when the complete dependency is missing.

The plugin code is licensed under GPLv3 or later. Access to premium downloads, updates and premium code is managed by a PorterWP/Freemius licence.

## Quick start

1. Download the PorterWP Premium ZIP and obtain a licence from [porterwp.com](https://porterwp.com/).
2. Install and activate ACF PRO.
3. Install PorterWP through **Plugins > Add New > Upload Plugin**, or with WP-CLI:

   ```bash
   wp plugin install ~/Downloads/porterwp-premium.zip --activate
   ```
4. Complete the PorterWP licence prompt. Licence management remains available from the PorterWP entry on the Plugins screen.
5. Install or adapt the [PorterWP starter theme](https://github.com/whoisandywhite/porterwp-public/tree/main/resources/theme-skeleton). It is a complete theme, not a plugin template.
6. Update the starter theme's `style.css` header and `package.json` metadata for the project.
7. Configure the theme under `porter/config/` and add theme PHP under `porter/inc/`.

Continue with [Directory Structure](/porterwp/getting-started/directory-structure.md) and the [Configuration Files Index](/porterwp/getting-started/configuration-files.md).

## Environment type and caching

Set WordPress's environment type explicitly in non-production environments:

```php
if ( ! defined( 'WP_ENVIRONMENT_TYPE' ) ) {
    define( 'WP_ENVIRONMENT_TYPE', 'development' );
}
```

PorterWP reuses its persistent theme configuration, block-discovery and include-discovery caches only when `wp_get_environment_type()` returns `production`. Development, staging and local environments rebuild those values so theme changes appear immediately.

The short-lived Site Editor preview optimiser is separate from these production caches. It can cache authorised preview requests in any environment and can be disabled or tuned with its documented filters.

## Starter-theme build pipeline

The public starter theme includes a Gulp 5/ES modules toolchain. These build files are theme-development tools and are not included in the PorterWP Premium plugin ZIP.

| File           | Purpose                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------- |
| `gulpfile.js`  | Compiles Sass, minifies CSS and JavaScript, creates block-style stubs and creates post-type icon files. |
| `package.json` | Declares the starter's development dependencies.                                                        |

```bash
npm install
npx gulp build
npx gulp watch
```