Statamic Variable Number Fieldtype Laravel Package

Getting Started

This is a single-purpose Statamic addon: it registers a variable_number fieldtype so a content editor can enter a number whose digit count (or segment layout) isn't fixed — order references, serials, SKUs, invoice numbers — instead of forcing a padded or fixed-width integer.

1. Check your Statamic version first. 3.0.0 exists solely to add Statamic 6 support (PR #2). That makes it a major bump by dependency policy, not by feature change:
   • Statamic 6 → composer require mitydigital/statamic-variable-number-fieldtype:^3.0
   • Statamic 5 / 4 / 3 → stay on ^2.1 (composer require mitydigital/statamic-variable-number-fieldtype:^2.1)
2. No publish step. Addons of this shape auto-register their fieldtype through the service provider; there is no config file, migration, or asset build to run. Install, then php artisan statamic:stache:clear.
3. Where to look first: the package README (the authoritative list of config keys), then src/ — the fieldtype class and its Vue component are small enough to read end-to-end in ten minutes. That is genuinely the fastest way to learn the exact options, because the addon's surface area is one field.
4. First use case: add the field to a blueprint and use it for an order/reference number on an Eloquent-backed or file-backed collection, then render it in Antlers. That single loop validates the whole integration.

# resources/blueprints/collections/orders/order.yaml
title: Order Number
fields:
  -
    handle: order_number
    field:
      type: variable_number
      display: 'Order Number'
      # addon-specific options (segment/digit config) per the README
      instructions: 'Enter the reference exactly as issued.'

Implementation Patterns

Blueprint-first, then content. Configure the field in the blueprint and create one entry before wiring up any templates. The fieldtype's behaviour on save is easier to observe than to infer from docs, and it tells you immediately whether values are persisted as strings (usually yes) or coerced to integers.

Store and render as a string. Treat the value as an opaque reference in Antlers/Blade rather than a number:

{{ if order_number }}
  <span class="font-mono">{{ order_number }}</span>
{{ /if }}

Avoid arithmetic, {{ order_number | multiply }}, or numeric casts anywhere downstream. A reference number that happens to contain leading zeros or separators is text, and it should never round-trip through an int.

Use it where editors were previously fighting a text field. The highest-value migration is replacing free-text text fields that hold reference numbers. Editors get input constraints; you get cleaner data. Do this per-blueprint, one field at a time, with a content backup — see Gotchas.

Pairs well with conditional/revealer fields. A variable number commonly belongs in a "generate or enter manually" flow: a toggle field plus this field, with if/unless visibility on the blueprint so the manual input only appears when auto-generation is off.

Programmatic access. If you generate values in a controller, command, or import, set the field through the entry API and let Statamic's fieldtype handle normalisation rather than mutating the raw YAML:

$entry->set('order_number', $reference);
$entry->save();

Testing. Assert against the stored value after save rather than against the Vue component; the fieldtype is a UI layer over content storage, so a Pest/PHPUnit test that saves an entry and re-reads $entry->get('order_number') covers the part that can actually break in production.

Sorting and querying. If you need "highest reference number", don't lean on collection sort: order_number — string sorting on variable-length values is where you get 1000 before 999. Where ordering matters, pair this field with a separate integer field (or a timestamp) as the sort key and keep the variable number purely as a human-facing label.

Gotchas and Tips

• The 3.0.0 bump is a dependency gate, not a feature drop. The only change is Statamic 6 support. If you're on Statamic 5, ^3.0 will not install, and there is no reason to chase it. Conversely, if you're upgrading to Statamic 6, budget for this major bump plus whatever else your Statamic 6 upgrade requires (Laravel and PHP floors move with it) — pin the addon alongside statamic/cms in the same PR so the constraint matrix resolves in one go.
• Treat 3.0.0 as untested against your content until you've run it. A one-PR major release that exists to track a CMS major is exactly the kind of update that ships without behavioural changes to the fieldtype itself — but "should be fine" isn't a test. Load an entry with a variable number in the control panel, edit, save, and diff the file before rolling to staging data.
• Reconfiguring the field can rewrite existing values. Changing segment or digit settings after content exists may re-format what's already stored when an entry is next saved. Snapshot content/ (or your database) before changing a live blueprint, and prefer adding a new field over mutating one that already holds production references.
• Watch for leading-zero loss. If anything in your pipeline casts the value to int — a resource, an API transformer, a Blade (int) cast — 000123 becomes 123 and the reference no longer matches your ERP. Keep it a string end to end.
• Ordering is lexical. As above: variable-length strings sort lexically. sort: order_number will surprise you. Use a numeric companion field for ordering.
• Stache caching. After adding the fieldtype or editing the blueprint, run php artisan statamic:stache:clear. A missing fieldtype in the picker or a stale blueprint is almost always cache, not a broken install.
• Debugging the field itself. The addon is small and single-maintainer (mitydigital). When something behaves unexpectedly, read the fieldtype class and its Vue component directly rather than searching for docs — and check the validation rules it declares in rules/validate before adding your own blueprint validate: entry, so you don't double up or conflict.
• Validation lives in the blueprint. Supplement the fieldtype's own constraints with blueprint-level validate rules for anything business-critical (uniqueness of an order number, for example) — the fieldtype constrains input format, not your application's invariants.
• Pin the version. This is a small package with a low release cadence; a ^3.0 constraint is fine, but avoid dev-main on anything content-facing. Read the changelog on each bump — future majors will likely follow Statamic majors again, so the version number tracks the CMS, not the feature set.
• Upgrade checklist for Statamic 6 projects: bump statamic/cms, bump this addon to ^3.0, clear Stache, then re-save one entry of each blueprint that uses the field and diff the content file. If the diff is empty, you're done.