Develop

.github/workflows/cs.yml

@@ -30,24 +30,15 @@ jobs:
           tools: cs2pr
           coverage: none
 
-      - name: 'Composer: set up PHPCS dependencies'
-        run: |
-          composer require --no-update squizlabs/php_codesniffer wp-coding-standards/wpcs phpcompatibility/phpcompatibility-wp dealerdirect/phpcodesniffer-composer-installer
-          composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
-
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-composer-dependencies
       - name: Install Composer dependencies
         uses: "ramsey/composer-install@v3"
 
-      - name: 'Run Composer Update'
-        run: |
-          composer update
-
       # Check the code-style consistency of the PHP files.
       - name: Check PHP code style
         continue-on-error: true
         run: vendor/bin/phpcs --report-full --report-checkstyle=./phpcs-report.xml
 
       - name: Show PHPCS results in PR
-        run: cs2pr --graceful-warnings ./phpcs-report.xml
+        run: cs2pr --graceful-warnings ./phpcs-report.xml

.github/workflows/phpcompat.yml

@@ -0,0 +1,54 @@
+name: PHP Compatibility
+
+on:
+  push:
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+  pull_request:
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+  workflow_dispatch: {}
+
+jobs:
+  phpcompat:
+    name: 'PHP Compatibility Check'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.0'
+          coverage: none
+
+      # Create isolated environment for PHPCompatibility with PHPCS 4.x
+      - name: Setup PHPCompatibility
+        run: |
+          mkdir phpcompat-tools
+          cd phpcompat-tools
+          composer init --name="temp/phpcompat" --type=project --no-interaction
+          composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
+          composer require --dev \
+            squizlabs/php_codesniffer:"^4.0" \
+            phpcompatibility/php-compatibility:"dev-develop" \
+            dealerdirect/phpcodesniffer-composer-installer:"^1.0" \
+            --no-interaction
+
+      # Check PHP 7.4 through 8.5 compatibility
+      - name: Check PHP Compatibility (7.4-8.5)
+        run: |
+          cd phpcompat-tools
+          ./vendor/bin/phpcs -p \
+            --standard=PHPCompatibility \
+            --runtime-set testVersion 7.4-8.5 \
+            --extensions=php \
+            --ignore=*/vendor/*,*/node_modules/*,*/tests/*,*/phpunit/*,*/freemius/* \
+            ../ || exit_code=$?
+
+          # Exit with the phpcs exit code (if set)
+          exit ${exit_code:-0}

.github/workflows/unit-tests.yml

@@ -1,8 +1,6 @@
 name: Unit Tests
 
 on:
-  # Run on all pushes and on all pull requests.
-  # Prevent the build from running when there are only irrelevant changes.
   push:
     paths-ignore:
       - '**.md'
@@ -11,7 +9,6 @@ on:
     paths-ignore:
       - '**.md'
       - '**.txt'
-  # Allow manually triggering the workflow.
   workflow_dispatch:
 
 jobs:
@@ -21,105 +18,72 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Notes regarding supported versions in WP:
-        # The base matrix only contains the PHP versions which are supported on all supported WP versions.
-        php: ['8.0', '8.1', '7.4']
+        php: ['7.4', '8.1', '8.2', '8.3']
         wp: ['latest']
-        experimental: [false]
+        mysql: ['8.0']
 
         include:
-          # Complement the builds run via the matrix with high/low WP builds for PHP 7.4 and 8.0.
-          # PHP 8.0 is sort of supported since WP 5.6.
-          # PHP 7.4 is supported since WP 5.3.
           - php: '8.3'
+            wp: '6.6'
+            mysql: '8.0'
+          - php: '8.4'
             wp: 'latest'
+            mysql: '8.0'
             experimental: true
-          - php: '8.2'
+          - php: '8.5'
             wp: 'latest'
+            mysql: '8.0'
             experimental: true
-          - php: '8.2'
-            wp: '6.3'
-            experimental: true
-          - php: '8.0'
-            wp: '5.9'
-            experimental: true
-
-    name: "PHP ${{ matrix.php }} - WP ${{ matrix.wp }}"
 
-    continue-on-error: ${{ matrix.experimental }}
-
-    services:
-      mysql:
-        # WP 5.4 is the first WP version which largely supports MySQL 8.0.
-        # See: https://core.trac.wordpress.org/ticket/49344
-        # During the setting up of these tests, it became clear that MySQL 8.0
-        # in combination with PHP < 7.4 is not properly/sufficiently supported
-        # within WP Core.
-        # See: https://core.trac.wordpress.org/ticket/52496
-        image: mysql:${{ ( matrix.wp == 5.3 && '5.6' ) || ( (matrix.wp < 5.4 || matrix.php < 7.4) && '5.7' ) || '8.0' }}
-        env:
-          MYSQL_ALLOW_EMPTY_PASSWORD: false
-        ports:
-          - 3306:3306
-        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=10s --health-retries=10
+    name: "PHP ${{ matrix.php }} - WP ${{ matrix.wp }} - MySQL ${{ matrix.mysql }}"
+    continue-on-error: ${{ matrix.experimental == true }}
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Setup MySQL
+        uses: ankane/setup-mysql@v1
+        with:
+          mysql-version: ${{ matrix.mysql }}
+
       - name: Install PHP
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
-          extensions: mysqli, mysql
+          extensions: mysqli
           coverage: none
 
-      # On WP 5.2, PHPUnit 5.x, 6.x and 7.x are supported.
-      # On PHP >= 8.0, PHPUnit 7.5+ is needed, no matter what.
-      - name: Determine supported PHPUnit version
-        id: set_phpunit
+      - name: Set PHPUnit version
         run: |
           if [[ "${{ matrix.php }}" > "8.0" ]]; then
             echo "PHPUNIT=9.*" >> $GITHUB_ENV
           else
             echo "PHPUNIT=5.7.*||6.*||7.5.*||8.5.*" >> $GITHUB_ENV
           fi
 
-      - name: 'Composer: set up PHPUnit'
-        env:
-          PHPUNIT: ${{ env.PHPUNIT }}
-        run: composer require --no-update phpunit/phpunit:"${{ env.PHPUNIT }}"
+      - name: Set up PHPUnit
+        run: composer require --no-update phpunit/phpunit:"$PHPUNIT"
 
-      # Install dependencies and handle caching in one go.
-      # @link https://github.com/marketplace/actions/install-composer-dependencies
-      - name: Install Composer dependencies for PHP < 8.0
+      - name: Install dependencies for PHP < 8.0
         if: ${{ matrix.php < 8.0 }}
-        uses: "ramsey/composer-install@v2"
+        uses: ramsey/composer-install@v3
 
-      # For the PHP 8.0 and above, we need to install with ignore platform reqs as not all dependencies allow it yet.
-      - name: Install Composer dependencies for PHP >= 8.0
+      - name: Install dependencies for PHP >= 8.0
         if: ${{ matrix.php >= 8.0 }}
-        uses: "ramsey/composer-install@v2"
+        uses: ramsey/composer-install@v3
         with:
           composer-options: --ignore-platform-reqs
 
-      - name: Install Subversion
-        run: sudo apt-get install subversion
-
-      - name: Set up WordPress
-        run: phpunit/install.sh wordpress_test root '' 127.0.0.1:3306 ${{ matrix.wp }}
-
-      - name: Tool versions
+      - name: Set up WordPress test environment
         run: |
-          php --version
-          composer --version
-          ./vendor/bin/phpunit --version
-          which ./vendor/bin/phpunit
+          sudo apt-get install -y subversion
+          bash phpunit/install.sh wordpress_test root '' 127.0.0.1:3306 ${{ matrix.wp }}
 
-      - name: Run the unit tests - single site
-        run: ./vendor/bin/phpunit
+      - name: Run tests (single site)
+        run: vendor/bin/phpunit
 
-      - name: Run the unit tests - multisite
+      - name: Run tests (multisite)
         env:
           WP_MULTISITE: 1
-        run: ./vendor/bin/phpunit
+        run: vendor/bin/phpunit

.github/workflows/zipitup.yml

@@ -23,13 +23,16 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+
       - name: Build project
         run: |
           mkdir build
+
       - name: Create artifact
         uses: montudor/action-zip@v1
         with:
-          args: zip -X -r build/${{ github.event.repository.name }}.zip . -x *.git* node_modules/\* .* "*/\.*" CODE_OF_CONDUCT.md CONTRIBUTING.md ISSUE_TEMPLATE.md PULL_REQUEST_TEMPLATE.md *.dist *.yml *.neon composer.* package.json dev-helpers** build** wporg-assets** phpunit**
+          args: zip -X -r build/${{ github.event.repository.name }}.zip . -x *.git* node_modules/\* .* "*/\.*" "*/.git*" "*/.DS_Store" CODE_OF_CONDUCT.md CONTRIBUTING.md ISSUE_TEMPLATE.md PULL_REQUEST_TEMPLATE.md CLAUDE.md *.dist *.yml *.neon composer.* package.json package-lock.json "dev-helpers/*" "build/*" "wporg-assets/*" "docs/*" "phpunit/*" phpstan-bootstrap.php build-assets.js
+
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
@@ -40,4 +43,4 @@ jobs:
         with:
           args: build/${{ github.event.repository.name }}.zip application/zip
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,14 @@
+# Ignore entire vendor except Freemius
+/vendor/*
+!/vendor/freemius/
+
+# Tooling
+/phpcompat-tools/
+/node_modules/
+
+# Lock files
+package-lock.json
+composer.lock
+
+# Claude AI
+.claude/

CLAUDE.md

@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Plugin Overview
+
+WebberZone Knowledge Base is a free WordPress plugin (namespace `WebberZone\Knowledge_Base`) that creates a multi-product knowledge base system. This is the standalone free version — there is no `includes/pro/` directory here. The companion premium plugin (knowledgebase-pro) is a separate repository that extends this codebase with pro features.
+
+- **Plugin entry**: `knowledgebase.php` (defines constants, loads Freemius, triggers autoloader)
+- **PHP**: 7.4+ | **WordPress**: 6.7+
+- **Custom post type**: `wz_knowledgebase` | **Taxonomies**: `wzkb_category`, `wzkb_product`, `wzkb_tag`
+- **Constants**: `WZKB_VERSION`, `WZKB_PLUGIN_DIR`, `WZKB_PLUGIN_URL`, `WZKB_PLUGIN_FILE`, `WZKB_DEFAULT_THUMBNAIL_URL`
+
+## Build & Development Commands
+
+### PHP
+
+```bash
+composer install                         # Install dependencies
+composer test                            # Run phpcs + phpcompat + phpstan
+composer phpcs                           # WordPress coding standards check
+composer phpcbf                          # Auto-fix coding standards
+composer phpstan                         # Static analysis (Level 5)
+composer phpcompat                       # PHP 7.4–8.5 compatibility check
+vendor/bin/phpunit                       # Run unit tests
+vendor/bin/phpunit --filter TestName    # Run a single test by name
+WP_MULTISITE=1 vendor/bin/phpunit       # Run multisite unit tests
+```
+
+### JavaScript / Blocks
+
+```bash
+npm run build                            # Build all blocks (runs build:free + build:pro)
+npm run build:free                       # Build all free blocks
+npm run build:assets                     # Minify CSS/JS and generate RTL
+npm run start                            # Watch mode for free blocks
+npm run lint:js                          # Lint JavaScript
+npm run lint:css                         # Lint CSS
+npm run format                           # Auto-format JS and CSS
+```
+
+Individual block builds: `npm run build:[kb|articles|sections|products|search|breadcrumb|related|alerts]`
+
+Note: `package.json` also contains `build:pro` and `build:rating` scripts that reference `includes/pro/` — these are irrelevant in this repository and will fail if run here.
+
+### Distribution
+
+```bash
+composer zip                             # Create PHP distribution zip
+npm run zip                              # Create full plugin zip (wp-scripts plugin-zip)
+```
+
+## Architecture
+
+### Main Bootstrap Flow
+
+1. `plugins_loaded` hook → `Main::get_instance()` (singleton)
+2. `Main::init()` instantiates all component handlers and registers their hooks
+3. Admin components only load on `is_admin()` (deferred to `init` action for translation readiness)
+4. `Main` has `$pro` and `$is_pro_enabled` properties defined but they are never set in this repository — those are only used by the pro plugin
+
+### Key Patterns
+
+**Autoloader** (`includes/autoloader.php`): PSR-4 style. Converts `WebberZone\Knowledge_Base\Admin\Settings` → `includes/admin/class-settings.php`.
+
+**Hook Registry** (`includes/util/class-hook-registry.php`): Custom wrapper around WordPress actions/filters with duplicate prevention and closure support. All components register hooks through this instead of calling `add_action()`/`add_filter()` directly.
+
+**Settings**: Global `$wzkb_settings` populated at plugin load. Read via `wzkb_get_option( $key )` or `wzkb_get_settings()`. Settings page in `includes/admin/class-settings.php`. Stored as a single serialized array under option key `wzkb_settings`. All settings filters use the prefix `wzkb_` (e.g. `wzkb_get_option_{$key}`).
+
+**Caching** (`includes/util/class-cache.php`): Term meta-based caching (not transients) with expiry timestamps. AJAX endpoint for admin cache clearing.
+
+**Free/Pro coexistence**: The plugin includes deactivation logic in `knowledgebase.php` — activating either the free or pro plugin automatically deactivates the other and shows an admin notice.
+
+### Component Map
+
+| Directory | Responsibility |
+|---|---|
+| `includes/admin/` | Settings UI, columns, wizard, notices, activation |
+| `includes/frontend/` | Templates, display, shortcodes, styles, search, breadcrumbs, related articles, feeds, patterns |
+| `includes/blocks/` | 8 free Gutenberg blocks (React in `src/`, compiled to `build/`) |
+| `includes/rest/` | REST API under `/wzkb/v1/` namespace |
+| `includes/widgets/` | 4 classic WordPress widgets (Articles, Sections, Breadcrumb, Products) |
+| `includes/util/` | Hook registry, caching utilities, helpers |
+
+### Block Development
+
+Blocks are in `includes/blocks/src/[block-name]/`. Each block has its own `block.json`, React `edit.js`, and server-side render via PHP. After editing block source, run `npm run build:[block-name]` — never edit files in `build/` directly.
+
+### Public Helper Functions
+
+`includes/functions.php` exposes the plugin's public API. Key functions:
+- `wzkb_knowledge()` — render the full KB output
+- `wzkb_get_option( $key )` / `wzkb_get_settings()` — read settings (prefer over `get_option()` directly)
+- `wzkb_get_breadcrumb()`, `wzkb_get_search_form()`, `wzkb_get_alert()`, `wzkb_related_articles()` — frontend rendering helpers
+- `wzkb_get_the_post_thumbnail()` — thumbnail retrieval (supports ACF image fields)
+- `wzkb_get_kb_url()`, `wzkb_get_product_sections_list()`, `wzkb_get_term_hierarchy_path()` — URL and taxonomy helpers
+
+### REST API
+
+Endpoints under `/wzkb/v1/`: `/sections` (product sections), `/knowledgebase` (list), `/knowledgebase/{id}` (single). Responses are object-cached under group `wzkb_rest` (300 s TTL); cache is invalidated on post save/delete and term changes.
+
+## Code Quality Configuration
+
+- **PHPCS**: `phpcs.xml.dist` — WordPress coding standards
+- **PHPStan**: `phpstan.neon.dist` — Level 5 strict analysis; baseline in `phpstan-baseline.neon`
+- **PHPUnit**: `phpunit.xml.dist` — test configuration, tests in `phpunit/tests/`