Loving Heart Retreats Plugin

WordPress plugin for the Loving Heart Retreats website. It provides:

• Gutenberg blocks — activities-map (interactive map), activities-archive, and activity (see assets/js/gutenberg/blocks/)
• Elementor widgets — app/inc/elementor/widgets/
• Custom post types, taxonomies, REST endpoints and shortcodes — app/inc/

Requirements

• Docker Desktop (for the local WordPress environment)

• Node.js 16 (pinned in .node-version). Any version manager that reads .node-version works — Vite+ (vp), nvm or fnm. The examples below use Vite+:

  curl -fsSL https://vite.plus | bash   # install vp (once)
  vp env on                             # let vp's node/npm shims pick the project's Node version

• Composer 2.x with PHP 8.x on the host

Local development setup

1. Clone the repo and the theme

The dev environment mounts the kamperen theme from a sibling directory (../kamperen/kamperen/, see .wp-env.json), so check both out next to each other:

workspace/
├── loving-heart-plugin/   ← this repo
└── kamperen/
    └── kamperen/          ← the theme

2. Install dependencies

vp env install     # installs Node 16.20.2 from .node-version (no-op if already present)
npm install
composer install

With vp env on, node / npm / npx inside this directory resolve to Node 16 automatically. Check with vp env current or vp env doctor.

Using nvm or fnm instead? nvm use / fnm use reads the same .node-version, then run npm install.

3. Build the assets

npm run build      # one-off production build into dist/

dist/ is git-ignored, so the plugin will not load any JS/CSS until this has run at least once.

4. Start the WordPress environment

npm run env:start

This runs wp-env start --xdebug, which spins up Docker containers with WordPress, this plugin, the kamperen theme, Query Monitor and Elementor (configured in .wp-env.json).

WP_DEBUG, SCRIPT_DEBUG, WP_DEBUG_DISPLAY and WP_DEBUG_LOG are all enabled.

5. Develop

npm start          # mix watch — rebuilds on change, serves BrowserSync

BrowserSync watches assets/js/**/*.{js,jsx,scss} and reloads the page for you. Regenerate the Composer autoloader after adding a new PHP class under app/:

npm run compile    # composer dump-autoload -o

Stopping / resetting

npm run env:stop            # stop containers (data is kept)
npx wp-env clean all        # reset the database
npx wp-env destroy          # remove containers, volumes and images

Useful wp-env commands

npx wp-env run cli wp plugin list        # run WP-CLI against the site
npx wp-env logs                          # tail PHP / Apache logs

Xdebug is enabled by env:start; point your IDE at port 9003 and map the project root to /var/www/html/wp-content/plugins/loving-heart-plugin.

PHP upload limits

The stock wordpress Docker image caps uploads at 2 MB. .wp-env/.htaccess is mounted into the site root (via mappings in .wp-env.json) and raises upload_max_filesize / post_max_size to 128 MB, memory_limit to 256 MB and execution/input time to 300 s. Edit that file to change the values — Apache picks up .htaccess changes on the next request, no restart needed. The mapping applies to the development site.

Project layout

loving-heart-plugin.php   plugin bootstrap (requires vendor/autoload.php, loads app/)
app/                      PHP source — PSR-4 namespace `app\`
  bootstrap.php           wires everything up
  inc/                    PostTypes, Taxonomies, REST, Scripts, Shortcodes, gutenberg/, elementor/
assets/
  js/gutenberg/blocks/    one folder per block: index.js (editor), view.js / script.js (frontend), style.scss, block.json, render.php
  js/elementor/           Elementor widget scripts
  images/                 copied to dist/images on build
dist/                     compiled assets (git-ignored, generated by `npm run build`)
webpack.mix.js            Laravel Mix build config (Tailwind, Sass, React, WP dependency extraction)
.wp-env.json              local WordPress environment definition
.wp-env/.htaccess         PHP ini overrides for the dev container
.github/workflows/        release.yml — builds the installable zip

Releasing

Releases are built by GitHub Actions (.github/workflows/release.yml) whenever a v* tag is pushed:

1. Bump Version: in loving-heart-plugin.php and add a ## x.y.z section to CHANGELOG.md.
2. git tag vx.y.z && git push origin vx.y.z

The workflow verifies the tag matches the plugin header, builds vendor/ and dist/, and publishes a GitHub Release with a loving-heart-plugin-x.y.z.zip that can be uploaded via Plugins → Add New → Upload Plugin. Run the workflow manually (workflow_dispatch) to get the zip as an artifact without publishing a release.