Schema, REST routes and extension points

Two plugins, one data model. The free plugin owns everything: the tables, the REST namespace, the admin React app, the renderer. Pro adds no tables and no screens of its own beyond one settings page.

A single PSR-4 autoloaded src/ tree, one React admin app built with Vite, and a front end that ships a small script per form.

The email tree

An email template stores one JSON tree in its tree column. Elements are flat objects with a type and a props bag, so a new block type is a registry entry rather than a schema change.

{
  "version": 1,
  "settings": { "addons": {} },
  "elements": [
    { "id": "el-1", "type": "logo",        "props": {} },
    { "id": "el-2", "type": "heading",     "props": { "text": "Thanks!" } },
    { "id": "el-3", "type": "fields_table","props": { "title": "What you sent" } },
    { "id": "el-4", "type": "footer_text", "props": {} }
  ],
  "origin": null
}

origin marks a template that is not a plain email: a WooCommerce design, a synced pattern fragment, or a language version. Those rows live in the same table but are filtered out of the Emails list.

Pro ships no React into the free admin bundle. Every Pro screen element is declared as data on a filter, and the free app renders it with its own controls.

The pattern is the same for each feature: a describe filter that returns a descriptor (label, icon, fields, defaults, a locked flag), and a run filter that handles the type at runtime. The workflow node below is the worked example; the field types, the email blocks and the integration cards all follow it.

add_filter( 'flexa_formflow.workflows.action_types', function ( array $types ): array {
    $types[] = [
        'type'    => 'my_action',
        'label'   => __( 'Send to my service', 'my-addon' ),
        'icon'    => 'send',
        'group'   => 'pro',
        'summary' => __( 'POST the entry to my endpoint.', 'my-addon' ),
        'fields'  => [ /* control descriptors */ ],
    ];

    return $types;
} );

add_filter( 'flexa_formflow.workflows.run_action', function ( $result, string $type, array $config, $form, $entry, $ctx ) {
    if ( 'my_action' !== $type ) {
        return $result;
    }

    // ... do the work, return a log array.
}, 10, 6 );

Seven tables, all prefixed {$wpdb->prefix}flexa_formflow_. They are created by dbDelta on activation and re-migrated on admin_init whenever Schema::DB_VERSION moves, so an update never needs a manual re-activation.

Pro adds no tables. Synced patterns, language versions and WooCommerce designs are all rows in flexa_formflow_email_templates with an origin set, which is why they copy, export and roll back with the same code as a plain email.

The admin app is a REST client. Every route below requires manage_options by default (see Capabilities) and a valid X-WP-Nonce. The one public route is the submission endpoint.

Forms and entries

Emails

WooCommerce emails

Workflows, library and settings

Pro namespace

/countdown is the only Pro route a mail client touches: it serves the animated GIF for the Countdown block, drawn on request so the timer is current each time the message is opened.

add_action( 'flexa_formflow.rest.register_routes', function ( string $namespace ): void {
    register_rest_route( $namespace, '/my-thing', [
        'methods'             => 'GET',
        'callback'            => 'my_callback',
        'permission_callback' => [ \Flexa\FormFlow\Support\Capabilities::class, 'can_manage' ],
    ] );
} );

One resolver handles every merge tag in an email. Field values use {field:ID}; everything else is a named token.

WooCommerce tokens

Registered only when WooCommerce is active. The order tokens need an order behind the email and resolve to an empty string without one, so a form email can safely share a template with an order email.

{order_number}        {order_date}           {order_total}
{order_status}        {order_url}            {payment_url}
{refund_amount}       {payment_method}       {shipping_method}
{customer_first_name} {customer_last_name}   {customer_full_name}
{customer_email}      {order_subtotal}       {order_discount}
{order_shipping_total} {order_tax_total}
{billing_address}     {shipping_address}     {customer_note}
{shop_url}            {my_account_url}

Ten more come from the email's own context rather than the order, which is how the account emails and the security alert get their links. Each is filled for the email named beside it and left empty elsewhere.

{reset_password_url}    Reset password email
{set_password_url}      New account email
{verify_email_url}      Confirm email address email
{gateway_title}         Payment gateway enabled email
{gateway_settings_url}  Payment gateway enabled email
{pos_store_name}        POS receipts (falls back to the site name)
{pos_store_email}       POS receipts
{pos_store_phone}       POS receipts
{pos_store_address}     POS receipts
{pos_refund_policy}     POS receipts

OrderTokens::catalog() merges the context list into its own, and that one array feeds both the editor's Dynamic data panel and the token strip on the WooCommerce tab. To add a token of your own, resolve it on flexa_formflow.emails.tokens and list it for the editor on flexa_formflow.emails.dynamic_data.

Tokens Pro adds

An editor preview shows an unknown token as-is, so a typo is easy to spot. A real send never prints a raw token: a token with no value becomes its registered fallback, which is an empty string unless something registers otherwise.

Two condition systems on node_visible

Both ship in the free plugin, both hang off flexa_formflow.emails.node_visible, and they read different keys on the same block node, so a block can carry both. Neither applies in the editor or the preview: a preview render shows every block so the design stays editable.

// visibility: operators is, is_not, contains,
// not_contains, is_empty, is_not_empty.
'visibility' => [
    'match' => 'all',          // or 'any'
    'rules' => [
        [ 'field' => 'enquiry_type', 'op' => 'is', 'value' => 'Support' ],
    ],
],

// conditions: subjects order_total, items_count, payment_method,
// shipping_country, billing_country. Operators eq, neq, gt, gte,
// lt, lte, contains.
'conditions' => [
    [ 'subject' => 'order_total', 'operator' => 'gte', 'value' => '100' ],
],

visibility has an editor UI (the Visibility panel at the bottom of the block inspector). conditions is a render-time seam with no UI of its own yet; the subject and operator lists are served on the WooCommerce emails endpoint as conditionSubjects and conditionOps, so an add-on can build the control against the same vocabulary the renderer uses. Numeric subjects compare as floats with a 0.0001 tolerance; the rest compare lowercased strings.

The license lives in one option and is refreshed against the hosted service on activation, then daily by WP-Cron.

key            string  the license key
instance_token string  per-site token minted by the service on activation
status         string  active|grace|expired|revoked|disabled|inactive
license        array   last server snapshot (tier, term, expires_at, over_limit, product)
validated_at   int     unix ts of the last successful server contact
checked_at     int     unix ts of the last attempt, successful or not
last_error     string  error code from the last failed attempt

License::is_active() is the single gate, and its result passes through flexa_formflow_pro.is_licensed so a site can take the final decision itself.

Two checks guard everything. Both default to manage_options and both are filterable, so a site can open the app to an editor role without touching the plugin.

add_filter( 'flexa_formflow.capabilities.manage', fn() => 'manage_woocommerce' );
add_filter( 'flexa_formflow.capabilities.settings', fn() => 'manage_options' );

A language pack in wp-content/languages/plugins/ takes precedence over the bundled files, so a site translation is never overwritten by an update. Both plugins load on init rather than earlier, which WordPress 6.7 requires.

Deleting the plugin removes nothing by default. Forms, entries, emails and workflows are content, and content survives a reinstall.

To opt in, turn on Delete all data on uninstall in the danger zone of the Settings screen. That writes delete_data_on_uninstall into flexa_formflow_settings, which uninstall.php reads. With it off, the file returns before touching anything.

The admin app is a Vite build. The PHP side needs Composer only for its dev tooling; the shipped plugin autoloads its own classes.

pnpm install          # pnpm is enforced by a preinstall guard
pnpm dev              # Vite dev server against a local WP install
pnpm build            # type-check, then build into assets/dist
pnpm type-check
pnpm test             # Vitest
pnpm format           # Prettier over apps/**

The docs site you are reading lives in docs-site/ inside the free plugin and builds separately with pnpm build into a static out/ folder. It is excluded from the distributed zip.