← All plugins

Script

An event step that changes values with a few lines of script - e.g. the first name in capitals - and passes them to the next steps.

Download script.zip
Version
1.1.0
Activated
Per project
Size
31 KB

Install

  1. Download the ZIP.
  2. In the admin app: Administration › Plugins › Upload plugin (ZIP).
  3. Install (runs its migrations), then activate it in the projects that need it.

An event step Modify values (script.modify): a few lines of script compute values for the records of a run, and the next steps of the event get them - in e-mails, webhooks, records they create.

set record.short = record.name
	.split()
	.first()
	.uppercase()                                  // {{record.short}}: "JANE"
set names = record.name.split()                   // {{names[0]}}, {{names[1]}}

var total = record.price * record.quantity         // only for the script
if total > 100 and not record.vip and isset(record.email)
	set shipping = 0
else if total > 50
	set shipping = 2.5
else
	set shipping = 4.9
end

each tag in record.tags
	set labels = labels.append(tag.uppercase())
end
set authors = record.authors.map(it.name).filter(it.length() > 0)
set due = record.date.addDays(14).formatDate("d.m.Y")
set sum = total + shipping                        // {{sum}}

The language

  • Statements, one per line (or ;): set <name or path> = <value> (passed to the next steps), var <name> = <value> (only for the script), unset <name or path> (removes a value, a field of the record or an item of a list - also for the next steps), if … else if … else … end, each <name> in <list> … end, return [<value>] (ends the script, see below). A line that starts with . continues the one before. // starts a comment. Indent with tabs or spaces as you like.
  • Values: "text" or 'text', numbers, true, false, null, lists [1, 2], objects {"city": "Berlin"}, paths record.name, names[0], record.image.url.
  • Variables: the placeholders of the event (record, old, event, project, count), the values of earlier steps, now and today.
  • Operators: + (numbers add, lists join, everything else is joined as text), -, *, /, %, ==, !=, <, <=, >, >= (numbers as numbers, everything else as text, so dates 2026-10-20 compare right), and, or, not, brackets. Empty values, 0, false and null count as false.
  • Is it there? isset(record.email), record.email is null, record.email is not null - only null (and what does not exist) is missing; 0, "" and false are there. For "empty or missing": record.email.isEmpty().
  • map() and filter() work out their argument for every item, with the item as it: names.map(it.uppercase()), short names.map(uppercase()), prices.filter(it > 10).

Methods

For Methods
Text (string, text, Markdown, e-mail, slug, phone …) split(sep?) (without: at spaces), join(sep?), uppercase(), lowercase(), capitalize(), trim(), replace(a, b), before(x), after(x) (e.g. the domain of an e-mail: after("@")), startsWith(x), endsWith(x), padStart(n, char), padEnd(n, char), truncate(n, end?), slug(), stripTags(), lines()
Lists and objects (repeatable fields, JSON, groups, references with include) first(), last(), slice(start, length?), length(), contains(x), map(…), filter(…), sort(), reverse(), unique(), append(x, …), sum(), average(), min(), max(), keys(), values(), has(key), isEmpty()
Numbers (integer, decimal) round(decimals?), floor(), ceil(), abs(), min(x), max(x), formatNumber(decimals, ",", ".")
Dates and times (date, datetime, time) addDays(n), addWeeks(n), addMonths(n), addYears(n), addHours(n), addMinutes(n) (negative: back), year(), month(), day(), hour(), minute(), weekday() (1 = Monday), formatDate("d.m.Y"), daysUntil(date), date()
E-mail addresses emailName() (before the @), emailDomain(), isEmail(), maskEmail() (J***@example.com)
Addresses (url) urlScheme(), urlHost(), urlPath(), urlQuery(name?), withQuery(name, value), withoutQuery(name), urlEncode(), urlDecode()
Any value number() (also 12,50), text(), bool(), default(value) (for empty values)

A changed date keeps its form: "2026-10-20".addDays(1) is 2026-10-21, a date with time stays one.

Methods of other plugins

Other plugins add their own methods - one by one or a whole class. Every public method of the class is a method of the script: it gets the value it is called on, then the arguments.

use ExcellentPlugins\Script\Methods;
use ExcellentPlugins\Script\Values;

final class Plugin implements PluginInterface
{
  public function register(PluginRegistry $registry, PluginContext $context): void
  {
    // record.price.vat(7)
    Methods::add('vat', static fn(mixed $value, mixed $rate = 19): float => Values::number($value, 'vat') * Values::number($rate, 'vat') / 100);
    // record.sku.stock(), record.sku.warehouse() … - an object, so its methods can use the plugin's context
    Methods::addClass(new ShopMethods($context));
  }
}
  • plugin.json of that plugin: "requires": {"script": "^1.0"}, so this plugin is loaded first.
  • Values reads values the way the built-in methods do: text(), number(), numeric(), truthy(), listOf(), date(), dateLike().
  • A method that cannot work with a value throws a RuntimeException with a short message, which the run shows with the line of the script.
  • Names start with a-z (then letters and digits). The built-in methods cannot be replaced.
  • Scripts are checked when the event is saved: a method only exists while its plugin is active in the project.

Structure

src/Script.php (parser and interpreter), src/Values.php (how values are read), src/Methods.php (the registry), src/Methods/* (the built-in methods: TextMethods, ListMethods, NumberMethods, DateMethods, UrlMethods, EmailMethods, TypeMethods).

What happens with the values

  • Without return: the record with what the script changed in it, and every value set with set, reach the next steps ({{record.short}}, {{sum}}). Values of var, the item of each, now and today stay in the script. Values of earlier steps stay as they were.
  • With return <value>: that value is all the next steps get, as their record - return {name: …, total: …} makes {{record.name}}, a list {{record[0]}}. Values set with set are not passed on then. A bare return only stops the script.
  • The record itself is not saved - use an update step with {{record.short}} for that. To read other records, use the step Find records before the script ({{author.name}}, in the script author.name).
  • The script is checked when the event is saved (errors with the line). The test run shows what each record passes on.
  • There is no PHP, no file, network or database access. A run has a budget of 100,000 steps, so a loop cannot run for ever.

Self-check of the language: php tests/check.php. ZIP: make plugin-zip name=script (in the CMS).