helpers

introduction

dframework exposes a set of global helper functions available in every controller, middleware, model, view, and job without requiring any imports. these helpers cover type checking, data manipulation, url generation, response shortcuts, validation, translation, and facade access to core services.

all helpers are registered on the global scope when the application initializes.

type checks

1isString('hello');     // true
2isNumber(42);          // true
3isNumber(NaN);         // false
4isObject({ a: 1 });    // true
5isObject([1, 2]);      // false
6isObject(null);        // false

value checks

isEmpty(value)

returns true if the value is considered empty. the following are considered empty: undefined, null, empty string '', empty array [], and empty plain object {}.

1isEmpty('');           // true
2isEmpty([]);           // true
3isEmpty({});           // true
4isEmpty(null);         // true
5isEmpty(0);            // false
6isEmpty('hello');      // false
7isEmpty([1]);          // false

string and array utilities

these helpers work polymorphically on both strings and arrays.

move(input, from, to)

moves an element from one index to another within a string or array. returns a new value without mutating the original.

1move([1, 2, 3, 4], 0, 2);   // [2, 3, 1, 4]
2move('abcd', 0, 2);          // "bcad"

remove(input, index)

removes the element at the specified index from a string or array.

1remove([1, 2, 3], 1);        // [1, 3]
2remove('hello', 1);           // "hllo"

replace(input, index, newItem)

replaces the element at the specified index with a new value.

1replace([1, 2, 3], 1, 9);    // [1, 9, 3]
2replace('hello', 0, 'H');    // "Hello"

limit(input, maxLength)

truncates a string or array to the specified maximum length.

1limit('hello world', 5);     // "hello"
2limit([1, 2, 3, 4, 5], 3);  // [1, 2, 3]

uniquify(input)

removes duplicate values from a string (by character) or array.

1uniquify([1, 2, 2, 3, 3]);  // [1, 2, 3]
2uniquify('aabbcc');           // "abc"

random and time

random(min, max)

generates a random integer between min and max (inclusive).

1random(1, 10);   // e.g. 7
2random(0, 1);    // 0 or 1

now()

returns the current date and time as an iso 8601 string.

1now();   // "2026-06-05T02:30:00.000Z"

html and security

escapeHtml(value)

escapes html special characters to prevent xss attacks. escapes ", &, ', <, and >. returns an empty string for null and undefined.

1escapeHtml('<script>alert("xss")</script>');
2// "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"
3 
4escapeHtml(null);   // ""

this function uses a single pass algorithm on large strings. the view engine's {{ }} syntax calls this function automatically.

emptyImage()

returns a data uri for a transparent 1x1 gif image. useful as a placeholder src attribute.

1emptyImage();
2// "data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs="

array helpers

arrayFirst(arr, callback)

returns the first array element that satisfies the callback function. returns undefined if no element matches.

1arrayFirst([1, 2, 3, 4], n => n > 2);   // 3

arrayLast(arr, callback)

returns the last array element that satisfies the callback function.

1arrayLast([1, 2, 3, 4], n => n < 4);    // 3

pluck(arr, key)

extracts a single property from each object in an array.

1pluck([{ name: 'tarou' }, { name: 'satou' }], 'name');
2// ['tarou', 'satou']

merge(...args)

deep merges multiple objects or arrays. arrays are concatenated. objects are recursively merged, with later values overriding earlier ones for conflicting keys.

1merge({ a: 1 }, { b: 2 });                    // { a: 1, b: 2 }
2merge({ a: { x: 1 } }, { a: { y: 2 } });      // { a: { x: 1, y: 2 } }
3merge([1, 2], [3, 4]);                        // [1, 2, 3, 4]

object helpers

old(key, fallback)

retrieves flashed old input from the previous request. this is useful for repopulating form fields after a validation failure.

1old('email');                    // the previously submitted email value
2old('name', 'default name');     // returns 'default name' if no old input exists

deep object access

these helpers provide safe access to deeply nested object properties using dot notation.

get(obj, path, defaultValue)

retrieves a nested value using a dot separated key path. returns defaultValue if the path does not exist.

1const config = { database: { host: 'localhost', port: 3306 } };
2 
3get(config, 'database.host');              // 'localhost'
4get(config, 'database.name', 'mydb');      // 'mydb'
5get(config, 'missing.key');                // undefined

set(obj, path, value)

sets a nested value using a dot separated key path. creates intermediate objects as needed. mutates and returns the original object.

1const config = {};
2set(config, 'database.host', 'localhost');
3// { database: { host: 'localhost' } }

has(obj, path)

returns true if the dot separated path exists in the object.

1has({ a: { b: 1 } }, 'a.b');    // true
2has({ a: { b: 1 } }, 'a.c');    // false

forget(obj, path)

deletes a nested property by dot separated path. if the parent is an array, the element is spliced out. mutates and returns the original object.

1const data = { user: { name: 'satou', age: 30 } };
2forget(data, 'user.age');
3// { user: { name: 'satou' } }

url and asset helpers

asset(path)

generates a url for a static asset in the public directory. strips leading slashes and prepends a single /.

1asset('css/app.css');     // '/css/app.css'
2asset('/js/main.js');     // '/js/main.js'

storage(path)

generates a url for a file in the storage directory. prepends /storage/.

1storage('avatars/user-1.jpg');     // '/storage/avatars/user-1.jpg'
2storage(null);                     // ''

url(path, params)

generates a url with parameter substitution. replaces :param placeholders with the corresponding values from the params object. values are url encoded.

1url('/users/:id', { id: 42 });
2// '/users/42'
3 
4url('/posts/:slug/comments/:commentId', { slug: 'hello-world', commentId: 7 });
5// '/posts/hello-world/comments/7'

response helpers

these helpers are shortcuts for calling methods on the current request context's response object. they can only be used inside a request context (controllers, middleware, etc.).

1export default class HomeController {
2  async index() {
3    return render('home', { title: 'welcome' });
4  }
5 
6  async store(req) {
7    await Item.create(req.body);
8    return redirect('/items');
9  }
10 
11  async api(req) {
12    const items = await Item.all();
13    return json({ items });
14  }
15}

routing helpers

route(name, params)

generates a url from a named route. substitutes :param placeholders with values from the params object.

1route('users.show', { id: 42 });
2// '/users/42'

the Route facade must be initialized before using this helper. it is automatically available in all request contexts.

routeIs(name)

checks if the current request's route matches the given name. supports wildcard patterns with *.

1routeIs('dashboard');       // exact match
2routeIs('admin.*');         // matches admin.users, admin.settings, etc.

validation

validate(dataOrReq, rules, messages)

validates data against a set of rules. accepts either a plain object or a request object (from which body and files are extracted).

1const v = validate(req, {
2  email: 'required|email',
3  password: 'required|string|min:8',
4  age: 'nullable|integer|min:18'
5});
6 
7if (v.fails()) {
8  return json({ errors: v.errors() });
9}

the validation result provides the following methods:

available rules

file validation rules

1const v = validate(req, {
2  avatar: 'file_required|file_size:5mb|file_mimes:jpg,png,webp',
3  documents: 'file|file_max_count:10|file_size:20mb'
4});

custom error messages

you can override the default error messages by passing a messages object keyed by field.rule.

1const v = validate(req, {
2  email: 'required|email'
3}, {
4  'email.required': 'please enter your email address',
5  'email.email': 'the email format is invalid'
6});

data sanitization

sanitizeBody(data, fields)

sanitizes and casts raw input data based on field type definitions. this is useful for ensuring form data is cast to the correct types before processing.

1const cleaned = sanitizeBody(req.body, [
2  { name: 'age', type: 'integer' },
3  { name: 'score', type: 'number' },
4  { name: 'active', type: 'boolean' },
5  { name: 'tags', type: 'array' },
6  { name: 'metadata', type: 'json' }
7]);

fields with null or undefined values are omitted from the result.

translation

t(req, key, fallback)

retrieves a translated string for the current locale. see the localization documentation for full details.

1const welcome = await t(req, 'common.welcome');
2const missing = await t(req, 'common.unknown', 'fallback text');

facades

dframework provides global facades for core services. these facades are available in the global scope and resolve to the current application instance's service.

session

the Session facade provides access to the current request's session store.

1await Session.set('theme', 'dark');
2const theme = await Session.get('theme', 'light');
3await Session.flash('status', 'saved successfully');

auth

the Auth facade provides access to the current user and authentication actions.

1if (Auth.check()) {
2  const user = Auth.user();
3}
4 
5await Auth.login(user, { role: 'admin' });
6await Auth.logout();

Auth.login() accepts an optional third argument. when set to true, the session uses a long-lived cookie instead of a browser session cookie.

db

the DB facade provides direct access to the database instance. it delegates all calls to the application's database connection.

1const users = await DB.table('users').where('active', true).get();
2const count = await DB.table('orders').count();
3await DB.raw('SELECT * FROM users WHERE id = ?', [1]);

job

the Job facade dispatches background jobs to the worker pool. see the jobs and queues documentation for full details.

1Job.dispatch('SendEmailJob', { to: 'user@example.com', template: 'welcome' });

log

the Log facade provides global access to the application logger. see the logging and errors documentation for full details.

1Log.debug('processing started');
2Log.info('user registered:', user.email);
3Log.warn('rate limit approaching');
4Log.error('payment failed:', err);
5Log.table(rows, 'query results');