Programmatically Managing Custom Fields in ProcessWire: A Practical Guide

The Problem

When building a ProcessWire site you often need to add new fields that weren’t defined in the admin UI. Whether you’re creating a plugin that adds a reusable field set or a script that migrates data, doing it programmatically can save time and keep your content model in sync across environments. The catch? If you don’t follow the API’s conventions, you can end up with invisible fields, duplicate names, or performance regressions.

Thesis

ProcessWire’s Field API is intentionally robust but requires a few best‑practice steps: validate uniqueness, persist changes with save(), bundle related fields in FieldGroup objects, and limit field loading in page queries. When you combine these with lifecycle hooks, you can maintain data integrity and keep page load times fast.

1. Using the Field API

Creating a new field at runtime is a three‑step process:

1. Instantiate a Field object and set its basic properties.
2. Call wire('fields')->add($field) to register it with the system.
3. Persist the field with $field->save().

Example (run in a module or CLI script with admin privileges):

$name = 'testimonial_author';
// 1. Ensure the name is unique
if(wire('fields')->get($name)) {
  throw new WireException("Field '{$name}' already exists");
}

// 2. Create the field
$field = new Field($name, 'text');
$field->label = 'Author Name';
$field->description = 'Name of the testimonial author';
$field->inputfield = 'InputfieldText';

// 3. Register and persist
wire('fields')->add($field);
$field->save();

Key points:

• Always check wire('fields')->get($name) first to avoid duplicates.
• Missing $field->save() means the field will exist only in memory and disappear after the request.
• Use the appropriate inputfield class for your field type.

2. Bundling with Fieldgroups

Fieldgroups let you package related fields and assign them to templates. This keeps your admin UI tidy and ensures consistent data structures across pages.

Creating a fieldgroup programmatically follows a similar pattern:

$groupName = 'testimonial_fields';
$group = new Fieldgroup($groupName);
$group->label = 'Testimonial Fields';
$group->description = 'Fields used for testimonial pages';

// Add fields to the group
$group->add($field); // from earlier example

// Register and persist
wire('fieldgroups')->add($group);
$group->save();

Assign the group to a template:

$template = wire('templates')->get('testimonial');
$template->add($group);
$template->save();

After these steps, any page using the testimonial template will automatically render the testimonial_author field.

3. Optimizing Page Queries

Loading every field on every page can be expensive, especially for large sites. ProcessWire lets you limit which fields are fetched in a query:

$pages = wire('pages')->find("template=testimonial", [
  'fields' => ['title', 'testimonial_author', 'testimonial_text']
]);

Alternatively, set fields to lazy so they’re only loaded when accessed:

$field => wire('fields')->get('testimonial_text');
$field->lazy = true;
$field->save();

Performance tip: use wire('session')->set('pageCache', true) when caching pages, and remember that cached pages still include all fields unless you explicitly exclude them.

4. Lifecycle Hooks for Data Integrity

ProcessWire fires hooks during field lifecycle events. Hooking into field_created or field_deleted lets you enforce rules or clean up related data:

class MyModule extends WireData implements Module {
  public static function getModuleInfo() {
    return [
      'title' => 'Field Integrity',
      'version' => 1,
    ];
  }

  public function init() {
    $this->wire('modules')->addHook('field_created', function(HookEvent $event) {
      $field = $event->object;
      // Example: auto-assign to a default group
      $group = wire('fieldgroups')->get('default');
      if($group) $group->add($field);
    });
  }
}

These hooks run in the same request that creates or deletes the field, so you can perform cleanup or logging without extra jobs.

Trade‑Offs & Limitations

• Version drift: The Field API changed in ProcessWire 4.x (namespaces, method signatures). Code written for 3.x may need updating. Always check the api.php documentation for your version.
• Duplicate names: Even with a uniqueness check, race conditions can occur if two scripts run concurrently. Use database locks or a central registry if you’re deploying in parallel.
• Large fieldgroups: A group with dozens of fields can slow down page rendering. Combine selective field loading with caching to mitigate.
• Admin UI lag: Adding many fields at once can cause the Fields page to become sluggish. Consider batching or deferring UI updates.

Actionable Checklist

1. Validate field name uniqueness before creation.
2. Persist each field and group with save().
3. Assign fieldgroups to the relevant templates.
4. Use the fields option or lazy attribute to limit field loading.
5. Implement lifecycle hooks for automated consistency checks.
6. Test performance on a staging copy before pushing to production.

Following these steps keeps your content model clean, prevents accidental data loss, and maintains acceptable page load times.