AurumPHP — Application Helpers Reference

Complete documentation of all helpers available in AurumPHP applications

Source files: core/helpers.php & core/event_helpers.php
Auto-load: All helpers are automatically available on every generated page/controller

1. URL & Navigation core/helpers.php

Helper	Signature	Description
`base_url()`	base_url(string $path = ''): string	Generate URL relative to project root. Automatically appends `?v=filemtime` for CSS/JS assets.
`redirect()`	redirect(string $path = ''): void	Redirect to a relative URL. Calls `exit` immediately after redirect.

2. Database — Legacy Style core/helpers.php

Helper	Signature	Description
`CustomQuery()`	CustomQuery(string $sql, array $params = []): PDOStatement	Execute raw SQL with a prepared statement. Returns PDOStatement.
`db_fetch_array()`	db_fetch_array(PDOStatement $stmt): array\|false	Fetch a single row from a query result. Equivalent to `fetch(PDO::FETCH_ASSOC)`.
`db_fetch_all()`	db_fetch_all(PDOStatement $stmt): array	Fetch all rows. Equivalent to `fetchAll(PDO::FETCH_ASSOC)`.
`db_num_rows()`	db_num_rows(PDOStatement $stmt): int	Count rows from a statement. Wraps `rowCount()`.
`db_insert_id()`	db_insert_id(): string	Get the last insert ID after an INSERT.
`db_escape()`	db_escape(string $value): string	Escape a string. Use prepared statements whenever possible.

3. Session & Flash core/helpers.php

Helper	Signature	Description
`page_set_var()`	page_set_var(string $key, mixed $value): void	Set a page-level variable (stored in `$_SESSION`). Useful for passing data between events/pages.
`page_get_var()`	page_get_var(string $key, mixed $default = null): mixed	Retrieve a page-level variable previously set with `page_set_var()`.
`flash()`	flash(string $message, string $type = 'success'): void	Set a flash message displayed once on the next page. Types: `success`, `error`, `warning`.

4. Event Error & State core/helpers.php

Helper	Signature	Description
`event_error()`	event_error(string $message): never	Stop execution with an error. AJAX → JSON error response; Normal → `$_SESSION['flash_error']`.
`event_set()`	event_set(string $key, mixed $value): void	Set an event state variable (`$GLOBALS`, valid for the current request only).
`event_get()`	event_get(string $key, mixed $default = null): mixed	Retrieve an event state variable set with `event_set()`.

5. HTML Injection core/helpers.php

Helper	Signature	Description
`add_html_top()`	add_html_top(string $html): void	Inject HTML at the top of the page (before main content).
`add_html_bottom()`	add_html_bottom(string $html): void	Inject HTML at the bottom of the page (after main content).

6. Field Control core/helpers.php

Helper	Signature	Description & Suitable Event
`set_default_value()`	set_default_value(string $field, mixed $value): void	Set a default field value in the Add form. Event: Add Page — Before Display
`hide_field()`	hide_field(string ...$fields): void	Hide fields from the view. Supports multiple fields. Event: Before Display (Add/Edit/View/List)
`show_field()`	show_field(string ...$fields): void	Show fields that were previously hidden. Event: Before Display
`set_readonly_field()`	set_readonly_field(string ...$fields): void	Make fields read-only (visible but not editable). Event: Edit Page — Before Display

7. Email & Formatting core/helpers.php

Helper	Signature	Description
`send_email()`	send_email(string $to, string $subject, string $body, string $from = ''): bool	Send an HTML email. For full features (CC/BCC/attachment) use `aurum_mail()`.
`format_currency()`	format_currency(float $amount, string $symbol = 'Rp', int $decimals = 0): string	Format a number as currency. Example: `format_currency(1500000)` → "Rp 1.500.000"
`format_date()`	format_date(string $date, string $format = 'd/m/Y'): string	Format a date. Returns `-` if empty/0000-00-00. Example: `format_date('2024-01-15')` → "15/01/2024"

8. Auth & User core/helpers.php

Helper	Signature	Description
`current_user()`	current_user(): string	Get the username of the logged-in user. Example: `'admin'`, `'john'`
`current_group_id()`	current_group_id(): int	Get the group_id of the logged-in user. Admin = 1, Manager = 2, etc.
`is_admin()`	is_admin(): bool	Check if the current user is admin (group_id === 1). Same as `current_group_id() === 1`.

9. Utility core/helpers.php

Helper	Signature	Description
`auto_number()`	auto_number(string $prefix, string $table, string $field, int $pad = 5): string	Generate an auto-increment number. Example: `auto_number('INV-', 'sales', 'invoice_no')` → "INV-00001"
`value_exists()`	value_exists(string $table, string $field, mixed $value, int $excludeId = 0): bool	Check for duplicate values in a table. `$excludeId` is useful on edit to exclude the current record.

10. Event Database Connection core/event_helpers.php

Helper	Signature	Description
`evt_db()`	evt_db(?PDO $pdo = null): PDO	Get/inject a PDO instance. If null, automatically creates a connection from config.
`SetConnection()`	SetConnection(?PDO $pdo = null): PDO	Set/get the active connection. Similar to `evt_db()` but can be overridden per-request.

11. Event Query Execution core/event_helpers.php

Helper	Signature	Description
`PrepareSQL()`	PrepareSQL(string $sql, array $params = []): array	Wrap SQL + params into an array. For passing to `Exec()` or `Query()`.
`Exec()`	Exec(string\|array $sql, array $params = []): int\|false	Execute a query, returns rowCount. On error → `LastError()`.
`Query()`	Query(string\|array $sql, array $params = []): PDOStatement\|false	Execute a query, returns PDOStatement. On error → returns `false`.
`LastId()`	LastId(): string\|false	Get the last insert ID after `Exec()` or `Query()`.
`LastError()`	LastError(): string	Get the last error message from `Exec()` or `Query()`.

12. Event Data Retrieval core/event_helpers.php

Helper	Signature	Description
`DBLookup()`	DBLookup(string\|array $sql, array $params = []): mixed	Get a single value (first column, first row). Returns `null` if not found.
`DBLookupRow()`	DBLookupRow(string\|array $sql, array $params = []): array\|null	Get a single full row. Returns `null` if not found.
`DBQueryRows()`	DBQueryRows(string\|array $sql, array $params = []): array\|false	Get all rows. Returns `false` on error.

13. Event Utility core/event_helpers.php

Helper	Signature	Description
`evt_identifier()`	evt_identifier(string $name): string	Sanitize a database identifier (backtick wrapper). Throws an exception if the name is invalid.
`evt_value()`	evt_value(array $values, string $field, mixed $default = null): mixed	Get a value from the `$values` array with a default. Safe for checking key existence.

14. Event Helpers — evt_* Series core/event_helpers.php

The evt_* helpers for concise and safe CRUD operations. All use prepared statements automatically.

Helper	Signature	Description
`evt_number()`	evt_number(array $values, string $field, float $default = 0): float	Get a field value as a number. Ideal for currency inputs (e.g. "Rp 1,500,000" → 1500000).
`evt_set_value()`	evt_set_value(array &$values, string $field, mixed $value): void	Modify a field value before saving. Used in Process Record Values.
`evt_now()`	evt_now(string $format = 'Y-m-d H:i:s'): string	Get the current datetime. Example: `evt_now('Y-m-d')` → "2024-01-15"
`evt_insert()`	evt_insert(?PDO $pdo, string $table, array $data): string	Insert a record into another table. Returns last insert ID. `$pdo` can be `null`.
`evt_update()`	evt_update(?PDO $pdo, string $table, array $data, array $where): int	Update records by condition. `$where` is required (cannot be empty).
`evt_delete()`	evt_delete(?PDO $pdo, string $table, array $where): int	Delete records by condition. `$where` is required (cannot be empty).
`evt_first()`	evt_first(?PDO $pdo, string $table, array $where = [], array $columns = ['*']): ?array	Get a single record. Returns `null` if not found.
`evt_all()`	evt_all(?PDO $pdo, string $table, array $where = [], array $columns = ['*'], string $orderBy = '', int $limit = 0): array	Get multiple records. Supports filters, column selection, ordering, and limit.
`evt_sum()`	evt_sum(?PDO $pdo, string $table, string $field, array $where = []): float	Sum a field's values. Example: total sales per employee.
`evt_count()`	evt_count(?PDO $pdo, string $table, array $where = []): int	Count records matching the given conditions.
`evt_raw()`	evt_raw(string $sql, array $params = []): array	Safe SQL expression for `evt_insert()`/`evt_update()`. Example: `evt_raw('qty - ?', [1])`
`evt_only()`	evt_only(array $values, array $fields): array	Pick only specific fields from `$values`.
`evt_except()`	evt_except(array $values, array $fields): array	Remove specific fields from `$values`.

Quick Reference — All Helpers Summary

Category	Helper	Source File
URL & Navigation	`base_url()` `redirect()`	`core/helpers.php`
Database Legacy	`CustomQuery()` `db_fetch_array()` `db_fetch_all()` `db_num_rows()` `db_insert_id()` `db_escape()`	`core/helpers.php`
Session & Flash	`page_set_var()` `page_get_var()` `flash()`	`core/helpers.php`
Event Error & State	`event_error()` `event_set()` `event_get()`	`core/helpers.php`
HTML Injection	`add_html_top()` `add_html_bottom()`	`core/helpers.php`
Field Control	`set_default_value()` `hide_field()` `show_field()` `set_readonly_field()`	`core/helpers.php`
Email & Formatting	`send_email()` `format_currency()` `format_date()`	`core/helpers.php`
Auth & User	`current_user()` `current_group_id()` `is_admin()`	`core/helpers.php`
Utility	`auto_number()` `value_exists()`	`core/helpers.php`
Event DB Connection	`evt_db()` `SetConnection()`	`core/event_helpers.php`
Event Query	`PrepareSQL()` `Exec()` `Query()` `LastId()` `LastError()`	`core/event_helpers.php`
Event Lookup	`DBLookup()` `DBLookupRow()` `DBQueryRows()`	`core/event_helpers.php`
Event Utility	`evt_identifier()` `evt_value()`	`core/event_helpers.php`
*Event CRUD (evt_)**	`evt_number()` `evt_set_value()` `evt_now()` `evt_insert()` `evt_update()` `evt_delete()` `evt_first()` `evt_all()` `evt_sum()` `evt_count()` `evt_raw()` `evt_only()` `evt_except()`	`core/event_helpers.php`

Popular Usage Examples

Calculate total before save

Event	Code
Add Page — Process Record Values	`$h = evt_number($values, 'price'); $d = evt_number($values, 'discount'); evt_set_value($values, 'total', $h - ($h * $d / 100));`

Validate before save

Event	Code
Add Page — Before Record Added	`if (evt_number($values, 'price') <= 0) event_error('Price must be > 0');`
Edit Page — Before Record Updated	`if (value_exists('employees', 'email', $values['email'], (int)$keys['id'])) event_error('Email already in use');`

Insert log / update another table after save

Event	Code
Add Page — After Record Added	`evt_insert($pdo ?? null, 'log', ['record_id' => $id, 'action' => 'add', 'created_at' => evt_now()]);`
Add Page — After Record Added	`evt_update($pdo ?? null, 'stock', ['qty' => evt_raw('qty - ?', [$qty])], ['id' => $itemId]);`

Hide/readonly fields based on user role

Event	Code
Edit Page — Before Display	`if (!is_admin()) { set_readonly_field('price', 'discount'); hide_field('margin'); }`
View Page — Before Display	`if (current_group_id() !== 1) hide_field('salary', 'contract_value');`

Auto-number invoice

Event	Code
Add Page — Process Record Values	`evt_set_value($values, 'invoice_no', auto_number('INV-', 'sales', 'invoice_no'));`

AurumPHP Application Helpers Reference — core/helpers.php & core/event_helpers.php