Developers
Building, testing and releasing
For the people who work on the plugin itself: the source layout, build commands, test suites, database migrations and the release procedure.
This page is about working on Flavonto Forms itself, from its source repository. Site builders who extend the plugin need the other developer pages instead.
Source layout
| Folder | What is in it |
|---|---|
| plugin/flavonto-forms | The plugin as shipped: PHP in includes/ (namespace Flavonto\Forms), built assets in assets/, templates/, data/, languages/ |
| src/frontend | The visitor runtime (one core script and modules loaded only when a form needs them) and forms.css |
| src/admin | The admin application (React through WordPress's wp.element) and admin.css |
| src/block | The block editor script |
| src/shared and tests/fixtures | The logic, calculation and validation engines shared by JavaScript and PHP, and the JSON fixtures both must pass |
| tests | PHP suites in WordPress Playground, JavaScript unit tests, browser suites, the quick start check and the lab scripts |
| tools | Build, documentation, release, parity matrix, media and check scripts |
Build
Node 24 and the packages in package.json (npm install). No PHP build step.
| Command | Does |
|---|---|
npm run build |
Builds the visitor modules, admin application, block script and stylesheets into plugin/flavonto-forms/assets with a manifest |
npm run watch |
The same, rebuilding on change |
node tools/build-docs.mjs |
Builds docs-site from docs/ and the generated reference |
node tools/build-quick-start.mjs |
Builds the quick start PDF |
python3 tools/make-pot.py |
Writes languages/flavonto-forms.pot |
Built assets are committed, and the release fails if building changes them, so what is committed is what ships.
Tests
| Command | Runs |
|---|---|
npm run test:js |
The shared engines and builder tree logic with node --test |
sh tests/playground/run-all.sh 7.4 8.3 |
Every PHP suite in a fresh WordPress Playground on each PHP version (the first suite prints the versions used) |
sh tests/playground/run.sh <suite> [php] [wordpress] |
One suite, for example sh tests/playground/run.sh pipeline 7.4 6.5 |
sh tests/e2e/server.sh 9411 8.3 then npm run test:e2e -- --grep-invert "admin|perf" |
Visitor browser tests in Chromium, WebKit and a phone profile, with axe scans |
LOGIN=1 sh tests/e2e/server.sh 9412 8.3 then the admin suite with FLVF_E2E_URL=http://127.0.0.1:9412 |
Admin browser tests |
THEME=classic sh tests/e2e/server.sh 9415 8.3 |
The visitor tests under a classic theme |
sh tests/quickstart/server.sh then npx playwright test -c tests/quickstart/playwright.config.mjs |
The quick start guide followed on a fresh site with the release ZIP |
python3 tools/parity/build.py |
Rebuilds feature-parity.csv and checks that every file, test and docs page it names exists |
Test only code (tests/e2e/mu, tests/quickstart/mu, tools/media/mu) is mounted into Playground and never shipped. Email is always captured in tests; outside services are answered by recorded replies.
Database migrations
The schema version is FLVF_DB_VERSION in flavonto-forms.php and flvf_db_version in the options table. On the first request after an update, Install\Installer::upgrade() takes a short lock, creates or updates the tables with dbDelta, runs Install\Migrations::run( $from ) for each version step after the stored one, and stores the new version. Each step is a method to_<n>() that must be safe to run twice (add a column only when missing, for example), and fires flvf_migrated. On dashboard pages, Installer::verify() recreates missing tables and columns at most every 12 hours.
To change the schema: change the table definition in Install\Schema, add a to_<n>() step for columns dbDelta may not add, raise FLVF_DB_VERSION, and add a test that drops the column and checks the step brings it back (see tests/playground/builder.php).
Release procedure
- Update the version in flavonto-forms.php (header and
FLVF_VERSION), readme.txt (Stable tag and changelog) and package.json; add the changes to sales/changelog.md. - Build, commit, and run the suites above.
node tools/release.mjs: checks the versions agree, rebuilds assets and fails if they differ from the commit, scans for forbidden characters and missing class references, checks front end size budgets, writes the translation template, builds the ZIP with fixed file order and dates, writes checksums, installs the ZIP on fresh WordPress with PHP 7.4 and 8.3 and runs a smoke test, builds the documentation ZIP and the PDF, and lists checksums for every deliverable.- Run the quick start check against the new ZIP.
- Record the results in reports/ and project-status.md.