Composer library for WordPress plugins · v0.1.3
Install, upgrade and uninstall, handled.
WP Foundation takes care of the lifecycle work every WordPress plugin needs: requirement checks, activation, upgrades with migrations, uninstall cleanup and multisite. It can also ask people why they're deactivating.
composer require bignall/wp-foundation
Plugin::create( __FILE__ )
->requires( php: '8.1', wp: '6.4' )
->options( [ 'acme_settings' => [ 'slots' => 30 ] ] )
->role( 'acme_manager', 'Booking Manager' )
->cron( 'acme_send_reminders', 'hourly' )
->tables( new BookingsTable() )
->migration( '1.1.0', [ Migrations::class, 'addStatus' ] )
->flushRewriteRules()
->deactivationSurvey()
->deleteDataOnUninstall()
->onReady( fn () => App::run() )
->boot();One definition covers every stage
Describe what your plugin needs once. WP Foundation sets it up, keeps it current, and removes it when asked.
-
Activation
Checks requirements first and refuses to activate with a clear message if they aren't met. Then creates tables, default options, roles, capabilities and cron events.
-
Every request
Checks requirements again, in case a plugin you depend on was switched off. If something is missing, admins see a notice, and your code doesn't run.
-
Upgrade
Spots a new version, including automatic updates, and runs your migrations in order. Then it syncs table schemas and adds new options and capabilities.
-
Deactivation
Unschedules cron events and removes rewrite rules, but keeps the site's data. It can optionally ask why the plugin is being deactivated.
-
Uninstall
Drops tables and removes options, roles and cron events, but only if you opt in or the site owner chooses to.
-
Multisite
Network activation and uninstall reach every site. New sites are set up automatically, and deleted sites take their tables with them.
The details plugins usually get wrong
These are the edge cases that cause white screens, missing tables and broken permalinks. WP Foundation handles them for you.
- Automatic updates skip the activation hook
- Upgrades run when a page loads, not only on activation. A lock stops two requests from running the same migration.
- Activation runs before your post types exist
- Flushing rewrite rules there misses your post types. The flush is put off to the end of the next
init, after they're registered. - A failed migration shouldn't break the site
- The stored version only advances past migrations that finished. Admins see the error, and the next page load resumes where it stopped.
- Old PHP versions shouldn't white-screen the site
- A version guard in your main file and Composer's platform check switched off mean old hosts get a notice, not a fatal error.
- Uninstall shouldn't surprise anyone
- Data is kept unless you opt in, or let the site owner decide with a setting. A filter has the final say.
- Two plugins can bundle different versions
- The library is designed to be prefixed with Strauss, and its survey script and styles are inlined, so each plugin keeps its own copy.
Ask why they're leaving
When someone clicks Deactivate, a short survey asks why. The answer goes to your handler: stored on the site, sent to your server, or both.
- Skippable, and deactivation always goes ahead, even if sending fails.
- Add, remove or replace reasons, and ask for details where they help.
- Says when answers leave the site, and only includes the site address if the user agrees.
- Protected by a nonce and a capability check, with input sanitized and length-limited.
Try it: this is the plugin's own survey script
Plugins
| Plugin | Description |
|---|---|
| Acme Bookings | Example plugin built on WP Foundation. Version 1.1.0 |
What your feedback handler receives
Click Deactivate to try the survey.Get started in three steps
-
Require the library
composer require bignall/wp-foundation -
Describe your plugin
use Bignall\WPFoundation\Plugin; Plugin::create( __FILE__ ) ->requires( wp: '6.4' ) ->options( [ 'acme_settings' => [] ] ) ->onReady( fn () => Acme\App::run() ) ->boot(); -
Bump the version and ship
Change the
Version:header in your plugin file. Next time a site loads a page, the upgrade runs. Prefix the library with Strauss before you release.
Guides
- Getting startedRequire the library, describe your plugin in its main file, and start your code once requirements pass.
- Lifecycle and upgradesWhat runs on activation, on every request, on upgrade, on deactivation and on uninstall.
- RequirementsCheck PHP and WordPress versions, extensions and other plugins, and add your own checks.
- TasksOptions, roles, cron and rewrite rules out of the box, and how to write your own tasks.
- Database tables and migrationsCustom tables kept in sync with dbDelta, and versioned migrations that resume after a failure.
- Deactivation surveyAsk why people deactivate, customise the reasons, and send answers where you want.
- MultisiteNetwork activation, new sites, deleted sites, and how to handle very large networks.
- Flash noticesShow a notice on the next admin page after a form redirects, without writing it yourself.
- Prefixing with StraussBundle the library safely alongside other plugins by prefixing it with Strauss.
- Release buildsBuild a small release zip that leaves out Composer's dev tools, and check the prefixing.
- Hooks referenceEvery action, filter and option the framework adds, with their arguments.
Tested in CI on PHP 8.1 to 8.4 and WordPress 6.4 to latest, single site and multisite.