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"}, pathsrecord.name,names[0],record.image.url. - Variables: the placeholders of the event (
record,old,event,project,count), the values of earlier steps,nowandtoday. - Operators:
+(numbers add, lists join, everything else is joined as text),-,*,/,%,==,!=,<,<=,>,>=(numbers as numbers, everything else as text, so dates2026-10-20compare right),and,or,not, brackets. Empty values,0,falseandnullcount as false. - Is it there?
isset(record.email),record.email is null,record.email is not null- onlynull(and what does not exist) is missing;0,""andfalseare 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()), shortnames.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.jsonof that plugin:"requires": {"script": "^1.0"}, so this plugin is loaded first.Valuesreads 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
RuntimeExceptionwith 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 withset, reach the next steps ({{record.short}},{{sum}}). Values ofvar, the item ofeach,nowandtodaystay 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 withsetare not passed on then. A barereturnonly stops the script. - The record itself is not saved - use an
updatestep with{{record.short}}for that. To read other records, use the step Find records before the script ({{author.name}}, in the scriptauthor.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).