WPKit

A standalone WordPress toolkit providing DataLayer, Migration, Cache, and Admin Notification components for plugin development — without requiring WooCommerce.

Requirements

• PHP 7.4+
• WordPress 5.9+

Installation

Step 1: Add to Your Project

Add the package to your composer.json dependencies:

Option A: Via GitHub (Recommended)

{
  "repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/getdokan/wp-kit.git"
    }
  ]
}

Option B: Local Development If you are developing locally and want to link the package:

{
  "repositories": [
    {
        "type": "path",
        "url": "file:../path/to/wp-kit"
    }
  ]
}

Now run the following command

composer require wedevs/wp-kit

Components

Component	Namespace	Description
Cache	WeDevs\WPKit\Cache	Object caching with group invalidation, built on wp_cache_*
DataLayer	WeDevs\WPKit\DataLayer	Model + DataStore CRUD pattern with SQL builder and type casting
Migration	WeDevs\WPKit\Migration	Version-based migration registry, schema helpers, background processing
AdminNotification	WeDevs\WPKit\AdminNotification	Notice management with providers, dismissal, and REST API

Quick Start

use WeDevs\WPKit\DataLayer\DataLayerFactory;
use WeDevs\WPKit\Migration\{MigrationRegistry, MigrationManager, MigrationHooks};
use WeDevs\WPKit\AdminNotification\{NoticeManager, DismissalHandler};

// DataLayer
DataLayerFactory::init( 'myplugin' );
DataLayerFactory::register_store( MyModel::class, MyDataStore::class );

// Migration
$registry = new MigrationRegistry( 'myplugin_db_version', MYPLUGIN_VERSION );
$registry->register_many( [ '1.0.0' => V_1_0_0::class ] );
$manager = new MigrationManager( $registry, 'myplugin' );
( new MigrationHooks( $manager, 'myplugin' ) )->register();

// Admin Notifications
$notices = new NoticeManager( 'myplugin' );
( new DismissalHandler( 'myplugin' ) )->register();

See docs/developer-guide.md for full documentation.

Contributing

Setting Up the Development Environment

1. Clone the repository:

git clone git@github.com:wedevs/wp-kit.git
cd wp-kit

2. Install dependencies:

composer install

Project Structure

wp-kit/
├── src/
│   ├── Cache/                  # Caching layer (WPCacheEngine, ObjectCache)
│   │   └── Contracts/          # CacheEngineInterface
│   ├── DataLayer/              # Model + DataStore CRUD
│   │   ├── Bridge/             # Optional WooCommerce adapters
│   │   ├── Contracts/          # ModelInterface, DataStoreInterface
│   │   ├── DataStore/          # BaseDataStore, SqlQuery
│   │   └── Model/              # BaseModel
│   ├── Migration/              # Version-based migrations
│   │   └── Contracts/          # MigrationInterface
│   └── AdminNotification/      # Admin notice system
│       └── Contracts/          # NoticeProviderInterface
├── tests/
│   ├── bootstrap.php
│   └── phpunit/
│       └── tests/              # Test files mirror src/ structure
├── docs/
│   └── developer-guide.md
├── composer.json
└── phpunit.xml.dist

Coding Standards

• Follow WordPress Coding Standards for PHP.
• Use tabs for indentation.
• All classes must be under the WeDevs\WPKit namespace with PSR-4 autoloading.
• Interfaces go in Contracts/ subdirectories and are suffixed with Interface.
• Abstract base classes are prefixed with Base (e.g., BaseModel, BaseDataStore).
• All hook names and option keys must use the consumer-provided prefix — never hardcode a package-level prefix.

Running Tests

The test suite uses PHPUnit with Brain Monkey for WordPress function mocking and Mockery for class mocking.

# Run the full test suite
composer test

# Run a specific test file
vendor/bin/phpunit --filter BaseModelTest

# Run tests with coverage (requires Xdebug or PCOV)
vendor/bin/phpunit --coverage-text

Writing Tests

Tests live in tests/phpunit/tests/ and mirror the src/ directory structure:

src/Cache/WPCacheEngine.php       → tests/phpunit/tests/Cache/WPCacheEngineTest.php
src/DataLayer/Model/BaseModel.php → tests/phpunit/tests/DataLayer/BaseModelTest.php

All test classes extend WeDevs\WPKit\Tests\TestCase, which sets up Brain Monkey automatically.

Key conventions:

• One test class per source class, suffixed with Test.
• Test method names follow test_<behavior_being_tested> format.
• Use Brain Monkey's Functions\when() for stubs, Functions\expect() for verifiable expectations.
• For WordPress hooks, prefer Brain\Monkey\Actions\expectDone() and Brain\Monkey\Filters\expectApplied() over Functions\expect('do_action').
• Use Mockery for class mocks (interfaces, data stores).

Example:

<?php

namespace WeDevs\WPKit\Tests\MyComponent;

use WeDevs\WPKit\Tests\TestCase;
use Brain\Monkey\Functions;

class MyClassTest extends TestCase {

    protected function setUp(): void {
        parent::setUp();
        // Stub WordPress functions as needed.
        Functions\when( 'absint' )->alias( fn( $val ) => abs( (int) $val ) );
    }

    public function test_it_does_something(): void {
        Functions\expect( 'get_option' )
            ->with( 'my_option', [] )
            ->once()
            ->andReturn( [ 'value' ] );

        // ... test logic and assertions
    }
}

Submitting Changes

1. Create a feature branch from main:

git checkout -b feature/my-change

2. Make your changes following the coding standards above.

3. Add or update tests for any new or changed functionality. All new code must have corresponding tests.

4. Run the test suite and ensure all tests pass:

vendor/bin/phpunit

5. Commit your changes with a clear, descriptive message:

git commit -m "Add support for batch model creation in BaseDataStore"

6. Push and open a pull request against main:

git push origin feature/my-change

Pull Request Guidelines

• Keep PRs focused — one feature or fix per PR.
• Include a description of what changed and why.
• Reference any related issues.
• Ensure the test suite passes with no errors or failures.
• New public APIs must include PHPDoc blocks.
• Breaking changes must be clearly documented in the PR description.

Reporting Issues

Open an issue on GitHub with:

• A clear title and description.
• Steps to reproduce (if applicable).
• Expected vs actual behavior.
• PHP and WordPress versions.

License

GPL-2.0-or-later