Forem: Kyle Niemiec

How the WPPF Update Helper Connects Private Plugins to Native WordPress Updates

Kyle Niemiec — Tue, 24 Mar 2026 14:41:29 +0000

Introduction

In the previous article, I wrote about the WP Plugin Update Server, a plugin that allows a WordPress site to act as a self-hosted update server for privately distributed plugins.

But the server is only one half of the system.

A private plugin still needs a way to participate in WordPress’ native update workflow. It needs to:

check whether a new version exists
show update notices in the admin

populate the “View Details” modal for plugins download protected packages when needed install correctly even when GitHub ZIP archives use inconsistent folder names

That’s the role of the WPPF Update Helper.

It is the client-side package that lives inside the plugin being distributed and connects that plugin to a configured update server.

Why the Helper Exists

The update server exposes metadata, but WordPress does not automatically know how to use that metadata for a privately hosted plugin.

By default, WordPress expects plugin update information to come from the official WordPress.org infrastructure.

The Update Helper bridges that gap by hooking into WordPress’ normal update lifecycle and translating remote update responses into the structures WordPress already expects.

In other words, it makes a privately hosted plugin behave like a normal updatable plugin inside the WordPress admin.

How the Pieces Fit Together

The overall flow looks like this:

More specifically:

A WordPress plugin includes the WPPF Update Helper.
The plugin registers with the helper.
During WordPress update checks, the helper requests update metadata from the server.
If a newer version exists, the helper injects that response into the normal plugin update transient.
WordPress displays the private plugin update in the admin as if it were part of the standard update system.

The helper also supports the plugin details modal and the package download/install process.

Registering a Plugin With the Helper

A host plugin registers itself with the helper by providing:

the plugin slug
the update server URL

From there, the helper can determine which plugins it should manage during update checks.

One implementation detail I like here is that the helper uses a WP filter-based registry rather than relying on a single mutable global store. That makes it easy for plugins to opt in while keeping the registration flow simple.

The implementation assumes the primary plugin file follows the standard naming pattern of:

slug/slug.php

This assumption is important because it affects both version lookup and post-install folder normalization.

Hooking Into WordPress Update Checks

The core of the update flow happens through the normal WordPress plugin update transient.

The helper hooks into:

pre_set_site_transient_update_plugins

When WordPress prepares the plugin update transient, the helper inspects the registered plugins, groups them by domain, and requests remote update metadata from the configured server.

The server endpoint used for that flow is:

/wp-json/wppf/api/plugin-updates/transients

If the response indicates that a remote version is newer than the installed version, the helper writes that response into:

$transient->response[...]

At that point, WordPress takes over and displays the update through the normal admin interface.

This is one of the most useful aspects of the design: the helper doesn’t create a parallel update UI. It plugs into the existing one.

Supporting the “View Details” Modal

WordPress also expects plugin metadata when a user clicks View details in the admin.

To support that, the helper hooks into:

plugins_api

When WordPress requests plugin information for a registered plugin, the helper calls the update server’s plugin information endpoint:

/wp-json/wppf/api/plugin-updates/plugins-api

It then returns that response in the shape WordPress expects for the plugin details modal.

This means privately distributed plugins can provide a more complete native experience, including things like descriptions, changelogs, icons, and other plugin metadata.

Handling Private Package Downloads

One of the more interesting parts of the helper is how it handles protected package downloads.

If an update response includes a token, the helper intercepts the package download step using:

upgrader_pre_download

At that point it:

reads the update response from the update transient
checks whether a token is present
retrieves the configured SSL key from WPPF settings
decrypts the token
performs an authenticated request for the package
writes the ZIP to a temporary file
returns the local temp path to the WordPress upgrader

This allows the plugin update flow to work even when the package is protected behind authentication.

A nice implementation detail here is that the token is decrypted only at install time rather than being stored in a persistently usable form inside the plugin.

Fixing GitHub ZIP Folder Name Problems

If you have ever installed a package generated from a GitHub ZIP archive, you’ve probably run into the folder naming problem.

GitHub-generated ZIP files often extract into a directory name that does not match the canonical plugin folder WordPress expects, appending the primary branch name to the end of the plugin directory name.

The helper works around this by hooking into:

upgrader_post_install

After installation, it renames the extracted directory to the expected plugin slug folder inside wp-content/plugins.

That makes GitHub-based releases much easier to use in a normal WordPress plugin workflow.

Interesting Implementation Details

As a side note, some of the additional details surrounding the functionality can be found below:

it batches update checks by domain, which reduces duplicate remote requests when multiple plugins use the same host
it falls back to plugin header inspection if the transient does not already contain the local version
it will first use project releases for versioning before falling back to commit versioning

Why This Part of the Ecosystem Matters

The update server gets most of the attention because it exposes the metadata and distribution endpoints.

But the helper is what makes the full experience possible inside an actual plugin.

Without it, the server is just an API.

With it, a private plugin can:

appear in normal WordPress update checks
show version updates in the admin
support the details modal
download protected packages
install more cleanly from GitHub-based sources

That is what turns the system into a usable private plugin distribution workflow rather than just a backend service.

Explore the Project

If you want to inspect the implementation, you can explore the helper here:

Repository:
https://github.com/kyle-niemiec/wppf-update-helper

And the update server it connects to is here:

Update Server:
https://github.com/kyle-niemiec/wp-plugin-update-server

Part of the WPPF ecosystem:

Documentation:
https://wp-plugin-framework.codeflower.io

Running Your Own WordPress Plugin Update Server Using GitHub

Kyle Niemiec — Tue, 17 Mar 2026 14:45:39 +0000

WordPress plugins typically receive automatic updates through the official WordPress plugin repository.

But many developers build plugins that aren’t meant for the public directory. These might be:

internal company plugins
premium plugins
client-specific functionality
plugins distributed privately through GitHub

In these cases, developers still want the convenience of the native WordPress update system.

The challenge is that WordPress expects updates to come from the WordPress.org infrastructure.

To solve this problem, I built a plugin that allows a WordPress site to act as its own plugin update server, using GitHub repositories as the source of truth.

The Problem With Private Plugin Updates

When WordPress checks for plugin updates, it builds a site transient called:

update_plugins

This transient contains information about available plugin versions.

WordPress also calls the plugins_api() endpoint to populate the plugin details modal that appears when you click View Details in the admin.

If you're distributing plugins outside the official repository, you need to replicate this behavior yourself.

That usually means building:

an API that serves update metadata
a way to serve plugin ZIP packages
a system for generating plugin information (description, changelog, icons, etc.)

Turning WordPress Into an Update Server

The WP Plugin Update Server plugin allows a WordPress site to act as a lightweight update server.

Instead of building a separate service, the plugin uses WordPress itself to:

store hosted plugin metadata
manage update information through the admin interface
expose update data through REST endpoints

Hosted plugins are managed as a custom post type:

Plugins → Hosted Plugins

Each entry represents a plugin that the server manages.

How The Update Flow Works

The system involves two parts:

the update server plugin
a client helper library installed in the plugin receiving updates

When a WordPress site checks for updates:

The helper library intercepts the update_plugins transient.
It queries the configured update server.
The server returns update metadata if a newer version exists.
WordPress adds the update to the normal plugin update list.

When a user clicks View Details, the helper calls another endpoint that returns the plugin metadata normally provided by WordPress.org.

REST Endpoints

The update server exposes two REST endpoints:

/wp-json/wppf/api/plugin-updates/transients

/wp-json/wppf/api/plugin-updates/plugins-api

These endpoints return the data WordPress expects when checking for updates or displaying plugin details.

This allows the WordPress admin experience to remain completely native.

GitHub Integration

The plugin integrates directly with GitHub repositories.

When a hosted plugin is requested, the server:

Looks for the latest GitHub release.
Falls back to the latest tag if no release exists.
Retrieves the plugin’s main file from GitHub.
Parses the plugin headers to extract metadata.

The resulting response includes:

the latest version number
the download package URL
plugin metadata
icons and banners
changelog and description sections

This allows developers to manage updates simply by publishing new releases on GitHub.

Supporting Private Repositories

For private repositories, the server can use a GitHub access token.

The token is encrypted before being sent to client plugins and is used during the download process to authenticate the request.

This makes it possible to distribute private plugins securely without exposing credentials.

Why This Approach Is Interesting

Most custom update systems rely on a separate API service or a static manifest file.

This project takes a different approach:

It uses WordPress itself as the update server.

That means:

plugin metadata can be managed through the admin UI
update endpoints are automatically available
GitHub repositories become the source of truth for releases

For developers already comfortable with WordPress, this makes the system easy to manage.

Try It Out

If you're interested in running your own update server, you can explore the project here:

Repository:

https://github.com/kyle-niemiec/wp-plugin-update-server

You can install it like a normal WordPress plugin and begin hosting updates for your own projects.

Part of the WPPF ecosystem:

WordPress Plugin Framework
WPPF Test Plugin
Plugin Update Server
WPPF Update Helper

Documentation:
https://wp-plugin-framework.codeflower.io

Exploring the WPPF Test Plugin: A Working Example of the WordPress Plugin Framework

Kyle Niemiec — Tue, 10 Mar 2026 14:47:51 +0000

Introduction

If you've ever explored a framework and wondered “What does a real project built with this actually look like?”, you're not alone.

Example projects are often the fastest way to understand how a framework works in practice.

When I released the WordPress Plugin Framework (WPPF), one of the most important supporting pieces was a companion repository: a working demonstration plugin that shows how the framework is meant to be used.

The WPPF Test Plugin acts as a reference implementation for building real WordPress plugins with the framework.

What the Test Plugin Demonstrates

The test plugin demonstrates several real-world plugin patterns, including:

plugin bootstrapping and module discovery
admin module separation
custom post types
typed meta with validation
WooCommerce email integration
upgrade routines that run on version updates

The goal is to show how a typical plugin can be structured when built using WPPF conventions.

Convention Over Configuration

One of the central ideas behind WPPF is filesystem-driven discovery.

Instead of manually requiring files and wiring components together, the framework automatically discovers classes placed in specific directories.

A typical plugin installation might have a folder structure like this:

my-plugin/
├─ admin/
│  ├─ includes/
│  │  ├─ meta-boxes/
│  │  └─ screens/
│  ├─ templates/
│  └─ my-plugin-admin.php
│
├─ assets/
│  ├─ css/
│  └─ js/
│
├─ includes/
│  ├─ classes/
│  ├─ modules/
│  └─ post-types/
│
├─ vendor/
└─ my-plugin.php

When the plugin boots, WPPF scans these directories and automatically constructs the relevant components.

This allows plugin developers to focus on implementing functionality instead of wiring everything together manually.

Example Feature: Custom Post Type With Typed Meta

The test plugin includes a custom post type called Test Posts, which demonstrates a full feature slice.

This includes:

The custom post type definition
A meta box UI in the admin
Typed meta validation
Persistence logic

The post type is defined here:

includes/post-types/class-wppf-test-post-type.php

The meta box UI lives in:

admin/includes/meta-boxes/class-wppf-test-post-meta-box.php

And the data model is represented by a typed meta object:

includes/classes/class-designink-test-post-meta.php

This structure helps separate concerns between:

UI
Data validation
Domain logic

WooCommerce Integration Example

The plugin also demonstrates an early example of how WPPF can integrate with WooCommerce.

It includes a custom email class:

includes/emails/class-wppf-test-email.php

Along with a corresponding email template:

woocommerce/emails/wppf-test-email.php

This pattern allows plugin developers to extend WooCommerce functionality while keeping email logic and templates organized.

Running the Plugin Locally

To experiment with the test plugin:

Install the plugin ZIP file in your WordPress installation.
Activate the plugin in the WordPress admin panel.

Once activated, you'll see the Test Posts custom post type where you can experiment with the plugin's features.

Exploring the Framework in Practice

Documentation can explain how a framework works, but seeing it applied in a real project is often the easiest way to understand its structure.

The WPPF Test Plugin exists as a reference implementation that demonstrates how the framework’s conventions come together in a functioning plugin.

If you're curious about how WPPF organizes plugin components, this repository is a good place to explore the architecture in practice.

Repository:
https://github.com/kyle-niemiec/wppf-test-plugin

Framework:
https://github.com/kyle-niemiec/wp-plugin-framework

Part of the WPPF ecosystem:

WordPress Plugin Framework (WPPF) – Core plugin architecture framework
WPPF Test Plugin – Example project demonstrating an implementation of a plugin using WPPF.
WP Plugin Update Server – Self-hosted WordPress plugin update infrastructure with GUI management.
WPPF Update Helper – Simple integration layer for the WP Plugin Update Server.

Documentation:
https://wp-plugin-framework.codeflower.io

After Building So Many WordPress Plugins, I Made WPPF

Kyle Niemiec — Thu, 05 Mar 2026 15:31:01 +0000

The problem and introducing WPPF

If you've built more than a few WordPress plugins, you've probably run into the same pattern.

A plugin starts clean, but as features grow it slowly becomes a mix of

scattered add_action calls,
copied boilerplate code,
and an includes/ folder full of dissimilar items.

After dealing with this enough times while building client plugins, I decided to standardize how I structure my projects.

That eventually became the WordPress Plugin Framework (WPPF).

Why this happens
My solution
The core idea: Modules
CLI scaffolding
Versioned namespaces
Who this framework is for
Try it out

Why this happens

One of the strengths of WordPress plugin development is also one of its biggest challenges: flexibility.

WordPress doesn’t impose a strict project structure on plugin developers. In many ways that’s a good thing, since it lowers the barrier to entry and lets developers solve problems however they want.

But along with that freedom has come little guidance around how plugins should be organized.

WordPress gives you incredible flexibility, but large plugins benefit from a little structure.

As plugins grow, it can be common to see things like

hooks scattered across files top to bottom,
features implemented wherever it was convenient at the time,
utility functions copied between projects,
or folders like includes/ slowly becoming a "stuff drawer".

None of this is necessarily wrong, but over time it can make a plugin harder to understand and maintain.

After running into this pattern repeatedly, I started wondering:

"What would a consistent, feature-oriented structure for WordPress plugins look like?"

That question eventually led to the framework described in the rest of this article.

My solution

After running into these problems repeatedly, I started standardizing how I structured my own plugins.

Instead of organizing code primarily by what it is (classes, templates, utilities, etc.), I started organizing plugins by what they do.

In other words, a feature-based architecture.

A plugin might contain things like

a REST API,
admin UI screens,
custom post types,
scheduled tasks,
or integrations with other platforms/plugins.

Each of these areas can be treated as a feature module that owns its own hooks, logic, and supporting code.

That approach turned out to make plugins significantly easier to reason about.

Instead of asking,

"Where is the code that registers this feature?",

you can usually find it directly inside the module responsible for that behavior.

Over time, this approach evolved into a small framework while working at DesignInk Digital that I now call the WordPress Plugin Framework.

The framework focuses on a few practical goals:

Organizing plugin code around feature modules.
Keeping WordPress hooks close to the feature they belong to.
Using a custom PSR-4 autoloader for predictable project structure.
Providing CLI scaffolding for common plugin components.

The result is a structure that still feels very “WordPress”, but scales better as plugins grow.

The core idea: Modules

The central concept in WPPF is the module.

A module represents a single feature area within a plugin and acts as the place where that feature connects to WordPress.

Instead of scattering hooks across multiple files, a module becomes the entry point for a feature's behavior.

For example, if a plugin exposes a REST API, the module responsible for that feature might look like this:

class My_API extends Module {
    public static function construct(): void {
        add_action('rest_api_init', [__CLASS__, 'init']);
    }

    public static function init(): void {
        // Register routes, controllers, permissions, etc.
    }
}

When the plugin loads, the framework automatically calls each module's construct() method and registers the hooks needed for that feature.

This approach keeps the WordPress wiring close to the feature itself.

Instead of searching through multiple files for where a hook is registered, you can usually find it directly inside the module responsible for that functionality.

As plugins grow, this makes it much easier to reason about how different parts of the plugin interact with WordPress.

Modules help keep plugins organized around behavior instead of file types.

Scaffolding common plugin components

One of the most repetitive parts of plugin development is creating the same structural pieces over and over.

Things like

bootstrapping plugin files,
registering custom post types,
creating meta boxes,
and configuring admin screens.

Even with a good architecture in place, these components still require a fair amount of setup.

To reduce that friction, WPPF includes a CLI tool that can scaffold common plugin components.

For example, creating a new plugin can be done with:

vendor/bin/wppf make:plugin

The CLI generates the basic structure needed to start building a plugin using the framework.

The other commands can generate other components such as

custom post types,
meta boxes,
admin modules,
and other common plugin scaffolding.

This helps eliminate a lot of the repetitive setup work that tends to happen when starting a new plugin or adding a new feature.

Instead of copying code from previous projects, you can generate a consistent starting point and focus on the actual functionality you want to build.

The goal is to remove as much boilerplate as possible while keeping plugin code predictable and organized.

Versioned namespaces

One of the challenges of building reusable libraries in the WordPress ecosystem is that multiple plugins can exist in the same runtime environment.

Unlike many modern PHP applications where dependencies are centrally managed, WordPress sites often load many independent plugins at once. If two plugins include different versions of the same framework or library, conflicts can occur.

To help avoid this problem, WPPF uses versioned namespaces.

Instead of a static namespace like

WPPF\Plugin,

each framework release is namespaced with its version. For example,

WPPF\v1_2_2\Plugin.

This means different plugins can safely ship with different versions of the framework without creating conflicts.

In practice, this allows plugin developers to

upgrade framework versions gradually,
avoid dependency conflicts across plugins,
and maintain stability on sites running multiple custom plugins.

The goal is to make the framework easier to adopt without forcing every plugin on a site to upgrade at the same time.

This design helps keep plugins isolated from each other while still allowing developers to benefit from shared framework improvements.

Versioned namespaces

One of the challenges of building reusable libraries in the WordPress ecosystem is that multiple plugins can exist in the same runtime environment.

To help avoid this problem, WPPF uses versioned namespaces.

Instead of a static namespace like

WPPF\Plugin,

each framework release is namespaced with its version. For example,

WPPF\v1_2_2\Plugin.

This means different plugins can safely ship with different versions of the framework without creating conflicts.

In practice, this allows plugin developers to

upgrade framework versions gradually,
avoid dependency conflicts across plugins,
and maintain stability on sites running multiple custom plugins.

The goal is to make the framework easier to adopt without forcing every plugin on a site to upgrade at the same time.

This design helps keep plugins isolated from each other while still allowing developers to benefit from shared framework improvements.

Try it out

If you're interested in exploring the framework or trying it in your own projects, you can find the documentation and source code here:

Documentation
https://wp-plugin-framework.codeflower.io/

GitHub Repository
https://github.com/kyle-niemiec/wp-plugin-framework/

The project is open source, and feedback from other plugin developers is always welcome.

I'm particularly interested in hearing how other developers structure larger plugins and what kinds of tooling would make plugin development easier.

If you end up trying the framework or have ideas for improving it, feel free to open an issue or start a discussion on GitHub.

WordPress plugin development is incredibly flexible and this framework is simply an attempt to add a little more structure where it helps.

Forem: Kyle Niemiec

How the WPPF Update Helper Connects Private Plugins to Native WordPress Updates

Introduction

Why the Helper Exists

How the Pieces Fit Together

Registering a Plugin With the Helper

Hooking Into WordPress Update Checks

Supporting the “View Details” Modal

Handling Private Package Downloads

Fixing GitHub ZIP Folder Name Problems

Interesting Implementation Details

Why This Part of the Ecosystem Matters

Explore the Project

Running Your Own WordPress Plugin Update Server Using GitHub

The Problem With Private Plugin Updates

Turning WordPress Into an Update Server

How The Update Flow Works

REST Endpoints

GitHub Integration

Supporting Private Repositories

Why This Approach Is Interesting

Try It Out

Exploring the WPPF Test Plugin: A Working Example of the WordPress Plugin Framework

Introduction

What the Test Plugin Demonstrates

Convention Over Configuration

Example Feature: Custom Post Type With Typed Meta

WooCommerce Integration Example

Running the Plugin Locally

Exploring the Framework in Practice

After Building So Many WordPress Plugins, I Made WPPF

The problem and introducing WPPF

Table of contents

Why this happens

My solution

The core idea: Modules

Scaffolding common plugin components

Versioned namespaces

Versioned namespaces

Try it out