PHPackages                             joseffb/wp-developer-kit - 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. [Templating & Views](/categories/templating)
4. /
5. joseffb/wp-developer-kit

ActiveLibrary[Templating & Views](/categories/templating)

joseffb/wp-developer-kit
========================

A development library to make creating things in wordpress a lot easier.

61141PHPCI passing

Since Jun 19Pushed 2mo ago3 watchersCompare

[ Source](https://github.com/Joseffb/wp-development-kit)[ Packagist](https://packagist.org/packages/joseffb/wp-developer-kit)[ RSS](/packages/joseffb-wp-developer-kit/feed)WikiDiscussions main Synced today

READMEChangelog (1)DependenciesVersions (3)Used By (0)

WP Development Kit
==================

[](#wp-development-kit)

WP Development Kit, or WDK, is a WordPress development library for building content models, taxonomies, template flows, and admin tooling with a JSON-first setup layer.

Breaking Change Notice
----------------------

[](#breaking-change-notice)

WDK `0.5.0` makes `WDK\System::Start()` the default shared-runtime bootstrap path and keeps the stabilization compatibility shims in place.

Unavoidable breaking changes:

- PHP `8.1+` is now required.
- Payment providers now expect secure tokenized or hosted-flow payloads.
- Raw card-number / PAN / CVV server-side payloads are rejected.
- The repo now tracks Composer, PHPUnit, CI, and local wp-env tooling as part of the supported developer contract.

Compatibility shims included in `0.5.0`:

- Legacy short provider names such as `PayPal_Rest_API_Provider` and `WP_Local_Search_Provider` still work.
- Deprecated provider-constructor argument patterns are still normalized where they can be adapted safely.
- Legacy PayPal v1-style transaction payloads are normalized into Orders v2 request shapes.
- Legacy Stripe decimal `amount` values are normalized into `amount_cents`.

The shims emit deprecation notices so existing integrations keep moving while you upgrade.

What WDK Provides
-----------------

[](#what-wdk-provides)

- JSON-based configuration for post types, taxonomies, menus, posts, fields, shortcodes, sidebars, and widgets.
- Shadow taxonomies for linking posts through mirrored taxonomy terms.
- Twig and Timber-compatible template flows for themes, plugins, and admin pages.
- Post, taxonomy, media, meta, relationship, and comment helpers through `PostInterface`.
- Utility helpers for debugging and troubleshooting.

Supported Runtime Matrix
------------------------

[](#supported-runtime-matrix)

SurfaceSupportedPHP`8.1`, `8.2`, `8.3`, `8.4`, `8.5`WordPress install stylePlugin install or Composer installTwig integrationTimber `^1.24.1` or `^2.0`Local WordPress toolingNode `18+`, Docker, `@wordpress/env`Automated repo validationComposer smoke tests, PHPUnit, PHP lint, GitHub ActionsInstallation
------------

[](#installation)

### Plugin install

[](#plugin-install)

1. Clone or download this repository into `wp-content/plugins/wp-development-kit` or `wp-content/mu-plugins/wp-development-kit`.
2. Run `composer install`.
3. Activate the plugin.

If Composer dependencies are missing, the plugin now fails closed with an admin notice instead of fatalling at bootstrap.

### Composer install

[](#composer-install)

```
composer require joseffb/wp-development-kit
```

Then initialize WDK in your bootstrap file:

```
require_once __DIR__ . '/vendor/autoload.php';

WDK\System::Start();
```

### Shared runtime bootstrap for themes and plugins

[](#shared-runtime-bootstrap-for-themes-and-plugins)

If a WDK-based theme/template and one or more WDK-based plugins can be active in the same request, the normal bootstrap is still:

```
require_once __DIR__ . '/vendor/autoload.php';

WDK\System::Start();
```

WDK now supports one shared runtime per request:

- highest version wins
- equal-version tie goes to the first registered runtime
- older bundles attach to the winner and rely on compatibility shims
- `System::Start()` infers the bundle root, bundle type, standard `wdk/configs` and `wdk/views` paths, and optional `wdk/bootstrap.php`

Use `wdk_register_runtime_bundle()` only when a bundle has non-standard paths or you need explicit runtime control:

```
require_once __DIR__ . '/vendor/autoload.php';

wdk_register_runtime_bundle([
    'id' => 'my-bundle-runtime',
    'bundle_id' => 'my-bundle',
    'version' => '0.5.0',
    'autoloader' => __DIR__ . '/vendor/autoload.php',
    'root' => __DIR__,
], [
    'id' => 'my-bundle',
    'type' => 'plugin',
    'root' => __DIR__,
    'config_paths' => [__DIR__ . '/custom/config'],
    'template_paths' => [__DIR__ . '/custom/views'],
    'bootstrap_file' => __DIR__ . '/custom/bootstrap.php',
]);
```

Project Layout
--------------

[](#project-layout)

By default WDK looks for configuration and view files in:

```
project-root/
└── wdk/
    ├── bootstrap.php
    ├── configs/
    └── views/

```

You can override those locations with `WDK_CONFIG_BASE` and `WDK_TEMPLATE_LOCATIONS_BASE`.

Config Files
------------

[](#config-files)

WDK supports these JSON files:

- `Fields.json`
- `Menus.json`
- `Pages.json` / `Posts.json`
- `Post_types.json`
- `Shortcodes.json`
- `Sidebars.json`
- `Taxonomies.json`
- `Widgets.json`

Config must still be valid JSON. Invalid files stop setup processing.

Key Behaviors
-------------

[](#key-behaviors)

### Post Types and Taxonomies

[](#post-types-and-taxonomies)

- `Post_types.json` mirrors `register_post_type()` with extra WDK options such as `use_twig` and `shadow_in_cpt`.
- `Taxonomies.json` mirrors `register_taxonomy()` and supports admin filters, admin columns, defaults, and GraphQL naming helpers.
- Taxonomy defaults are now seeded once and stay stable across repeated boots.

### Shadow Taxonomies

[](#shadow-taxonomies)

Shadow taxonomies mirror posts into taxonomy terms and keep term metadata linked back to the source post. This is useful when a taxonomy should behave like a related record picker without building a full custom UI.

### Templates

[](#templates)

WDK works with Timber and Twig. When a template is processed through WDK, the corresponding `wdk_context_*` filter can extend the view context.

```
add_filter('wdk_context_templatename', function ($context) {
    $context['message'] = 'Hello from WDK';
    return $context;
});
```

Compatibility Shims
-------------------

[](#compatibility-shims)

`0.5.0` keeps older integrations moving where it is safe to do so.

### Search providers

[](#search-providers)

Recommended:

```
$search = new WDK\Search(WDK\WP_Local_Search_Provider::class);
```

Still supported with deprecation notice:

```
$search = new WDK\Search('WP_Local_Search_Provider');
```

### Payment providers

[](#payment-providers)

Recommended:

```
$payments = new WDK\Payments(WDK\PayPal_Rest_API_Provider::class, [
    'client-id',
    'client-secret',
]);
```

Still supported with deprecation notice:

```
$payments = new WDK\Payments('PayPal_Rest_API_Provider', [
    'client-id',
    'client-secret',
]);
```

Secure Payment Guidance
-----------------------

[](#secure-payment-guidance)

WDK still exposes `Payment_Provider::create_payment(array $payment_data)`, but the accepted payloads have changed.

### Normalized response shape

[](#normalized-response-shape)

All providers return a normalized array:

```
[
    'status' => 'succeeded|pending|requires_action|failed',
    'provider' => 'stripe|paypal|authorizenet',
    'object_id' => 'provider-specific-id-or-null',
    'next_action' => [
        'type' => 'redirect|client_secret',
        // provider-specific keys...
    ],
    'message' => 'optional human-readable message',
    'raw' => [ /* provider payload */ ],
]
```

### Stripe

[](#stripe)

Stripe now uses Payment Intents.

Recommended payload keys:

- `amount_cents`
- `currency`
- `payment_method_id`
- `confirm`
- `capture_method`
- `return_url`
- `customer`
- `receipt_email`
- `metadata`

Deprecated but normalized:

- decimal `amount`

Rejected:

- `card_number`
- `cvv`
- `expiration_date`
- nested raw card `source` payloads

### PayPal

[](#paypal)

PayPal now uses Orders v2.

Recommended payload keys:

- `intent`
- `purchase_units`
- `application_context`
- `return_url`
- `cancel_url`

Deprecated but normalized:

- v1-style `transactions`
- `redirect_urls`

### Authorize.Net

[](#authorizenet)

Authorize.Net now requires Accept.js opaque token data.

Recommended payload keys:

- `opaque_data`
- `opaque_data_descriptor`
- `opaque_data_value`
- `transaction_type`
- `amount`

Rejected:

- raw PAN / card-number payloads

Upgrade Guide From 0.2.x
------------------------

[](#upgrade-guide-from-02x)

1. Upgrade PHP to `8.1+`.
2. Run `composer install` or `composer update`.
3. If you use the tracked local environment, run `npm install`.
4. Move provider references toward fully qualified class names.
5. Replace raw card payloads with secure tokenized or hosted-flow inputs.
6. Update any payment consumers to read the normalized response shape.
7. Move multi-bundle themes/plugins to the shared runtime loader bootstrap.
8. Re-run the repo validation commands below.

Developer Tooling
-----------------

[](#developer-tooling)

### Composer and PHPUnit

[](#composer-and-phpunit)

```
composer validate --no-check-publish
composer lint
composer test
composer ci:php
composer ci:wp-env
composer ci:coexistence
composer ci:local
composer ci:github
composer ci:green
```

### Local WordPress via wp-env

[](#local-wordpress-via-wp-env)

```
npm ci
npm run wp-env:start
npm run wp-env:cli
npm run wp-env:test-cli
npm run wp-env:coexistence
npm run wp-env:stop
```

`wp-env` requires Docker.

### Local GitHub Actions parity

[](#local-github-actions-parity)

WDK now supports running the GitHub workflow locally before pushing.

Install `act` on macOS with Homebrew:

```
brew install act
```

Then run:

```
composer ci:green
```

This performs:

- host preflight (`composer`, PHPUnit, lint, wp-env, coexistence suite)
- local GitHub Actions execution through `act`

Examples
--------

[](#examples)

### Default search

[](#default-search)

```
$results = WDK\Search::find('conference');
```

### Secure Stripe payment intent

[](#secure-stripe-payment-intent)

```
$payment = WDK\Payments::create_payment([
    'amount_cents' => 1500,
    'currency' => 'usd',
    'payment_method_id' => 'pm_123',
    'confirm' => true,
    'return_url' => 'https://example.com/payments/return',
], ['sk_test_123'], WDK\Stripe_Rest_Api_Provider::class);
```

### Secure PayPal order

[](#secure-paypal-order)

```
$payment = WDK\Payments::create_payment([
    'intent' => 'CAPTURE',
    'purchase_units' => [[
        'amount' => [
            'currency_code' => 'USD',
            'value' => '25.00',
        ],
    ]],
    'return_url' => 'https://example.com/paypal/return',
    'cancel_url' => 'https://example.com/paypal/cancel',
], ['client-id', 'client-secret']);
```

### Secure Authorize.Net opaque token flow

[](#secure-authorizenet-opaque-token-flow)

```
$payment = WDK\Payments::create_payment([
    'amount' => 25.00,
    'opaque_data' => [
        'dataDescriptor' => 'COMMON.ACCEPT.INAPP.PAYMENT',
        'dataValue' => 'opaque-token-value',
    ],
], ['api-login-id', 'transaction-key'], WDK\AuthorizeNet_Rest_API_Provider::class);
```

Validation Status For 0.5.0
---------------------------

[](#validation-status-for-050)

This repository now ships with:

- tracked `composer.lock`
- tracked `package.json` and `.wp-env.json`
- tracked PHPUnit bootstrap and suite
- tracked GitHub Actions CI

The repo validation currently covers:

- PHP linting across `library/` and `tests/`
- standalone smoke tests
- PHPUnit regression coverage
- wp-env CLI/test-cli boot verification

###  Health Score

29

—

LowBetter than 57% of packages

Maintenance56

Moderate activity, may be stable

Popularity16

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity29

Early-stage or recently created project

 Bus Factor1

Top contributor holds 91.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/0574dbe1c66ded3cd63b510fd9a9b4a787048a6feb2a35eaef6b793d7cfa957e?d=identicon)[Joseffb](/maintainers/Joseffb)

---

Top Contributors

[![joseffb-mla](https://avatars.githubusercontent.com/u/44980627?v=4)](https://github.com/joseffb-mla "joseffb-mla (194 commits)")[![Joseffb](https://avatars.githubusercontent.com/u/1214364?v=4)](https://github.com/Joseffb "Joseffb (18 commits)")

---

Tags

shadow-taxonomytwigwordpresswordpress-ciwordpress-developmentwordpress-pluginwordpress-plugin-developmentwordpress-scaffoldingwordpress-theme-development

### Embed Badge

![Health badge](/badges/joseffb-wp-developer-kit/health.svg)

```
[![Health](https://phpackages.com/badges/joseffb-wp-developer-kit/health.svg)](https://phpackages.com/packages/joseffb-wp-developer-kit)
```

###  Alternatives

[limenius/react-bundle

Client and Server-side react rendering in a Symfony Bundle

3851.2M](/packages/limenius-react-bundle)[area17/laravel-auto-head-tags

Laravel Auto Head Tags helps you build the list of head elements for your app

4616.1k](/packages/area17-laravel-auto-head-tags)[jelix/wikirenderer

WikiRenderer is a library to generate HTML or anything else from wiki content.

1712.3k1](/packages/jelix-wikirenderer)[webkinder/sproutset

A Composer package for handling responsive images in Roots Bedrock + Sage + Blade projects.

282.2k](/packages/webkinder-sproutset)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)