Common Helpers

This document describes the common helper functions and utilities used throughout the Hotelaro codebase. These helpers provide shared functionality for database access, formatting, permissions, localization, form handling, and more. They are foundational to many modules, supporting both backend and frontend operations.

Scope:

This page covers general-purpose helper functions, primarily those found in app/Helpers/Common_helper.php.

For file upload and asset management helpers, see File Management.

For AJAX form handling and notification helpers, see Form Handling.

Purpose of Common Helpers

Common helpers are utility functions designed to:

Reduce code duplication by centralizing frequently used logic.
Provide consistent interfaces for common tasks (e.g., database lookups, permission checks, localization).
Support modularity and maintainability across the multi-tenant, multi-module Hotelaro system.

Typical Use Cases:

Fetching data by ID or UID from any table.
Formatting numbers, strings, or dates.
Checking user permissions.
Generating unique identifiers.
Handling localization and translations.
Building dynamic forms with CSRF protection.

System Context: Where Helpers Fit

Below is a diagram showing how the common helpers are used by various modules in the Hotelaro system.

Diagram: "Common Helpers" Usage Across Modules

Key Helper Functions

The following table summarizes the most important helper functions, their purpose, and typical usage.

Function Name	Purpose	Example Usage
getInfoById	Fetch a column value by id from a table	Get hotel name by ID
getInfoByUid	Fetch a column value by admin_uid from a table	Get property info for a tenant
getOrdinalSuffix	Get ordinal suffix for a number (e.g., 1st, 2nd, 3rd)	Display room numbers
_e, _ec	Echo text safely, with optional tag stripping and demo mode	Output user input in views
get_module_paths	List module directories with a Config.php	Dynamic module loading
getCurrency	Get current currency settings for the hotel	Show prices in correct currency
maxfindate	Get the end date of the current financial year	Financial reporting
display	Fetch a translation for a phrase from the language table	Multi-language support
hideEmailAddress	Obfuscate email addresses for privacy	Demo mode, privacy display
directory_map	Recursively map a directory structure	File management, plugin discovery
uri	Get URI segments	Routing, context-aware logic
form_open	Generate a form tag with CSRF protection	Secure form creation
permissionvaluecheck	Check if a user has a specific permission	Role-based access control
tz_list	List all timezones with UTC offsets	Timezone selection in setup
generateUnique20DigitNumber	Generate a unique 20-digit number	Booking/order IDs
idbyorder	Generate a new ID with prefix and increment	Invoice, booking, or order IDs
emailtemplate	Send templated emails with placeholders and attachments	Booking confirmations, notifications

Natural Language to Code Entity Mapping

Diagram: "Natural Language" to "Helper Function" Mapping

Detailed Function Descriptions

Database Access Helpers

getInfoById($table, $id, $value)

Fetches a single column value from a table by id. Returns the value or false if not found.

getInfoByUid($table, $uid, $value)

Fetches a single column value from a table by admin_uid (used for multi-tenant isolation).

Formatting and Output Helpers

getOrdinalSuffix($number)

Returns the ordinal suffix for a number (e.g., 1 → "st", 2 → "nd").

_e($text, $strip_tags = true)

Echoes text safely, optionally stripping HTML tags. In demo mode, obfuscates emails.

_ec($text, $strip_tags = true)

Similar to _e, but always echoes the text (used for including view sections).

Module and Directory Helpers

get_module_paths()

Scans predefined directories for modules containing a Config.php file, returning their paths.

directory_map($source_dir, $directory_depth = 0, $hidden = FALSE)

Recursively maps a directory structure, optionally including hidden files.

Localization and Currency Helpers

getCurrency()

Retrieves the current currency settings for the hotel from the database.

display($text)

Looks up a translation for a phrase in the language table, using the current language setting.

tz_list()

Returns a sorted list of all timezones with their UTC offsets, for use in setup forms.

Permission and Security Helpers

permissionvaluecheck($permissionname, $permissiontype)

Checks if the current user (by session role) has a specific permission type for a given permission name.

form_open($action, $attributes, $hidden)

Generates a form opening tag with CSRF protection and hidden fields.

Utility and Miscellaneous Helpers

generateUnique20DigitNumber()

Generates a unique 20-digit number using microtime and random padding.

idbyorder($table, $uid, $idfirstinitials, $column)

Generates a new ID with a prefix and increment, based on the last entry for a tenant.

emailtemplate($toemail, $mailbody, $mailsubject, $placeholders, $attachmentPath = null)

Sends an email using a template, replacing placeholders and optionally attaching a file.

hideEmailAddress($email)

Obfuscates an email address for privacy (e.g., in demo mode).

Example: Timezone Helper in Setup

The timezone helper (tz_list) is used in the setup forms to populate timezone dropdowns. For example, in the setup view:

The dropdown is filled with options from tz_list().
The selected timezone is stored in the setup table for the current tenant.

Example: Country/State/City Helper

The country, state, and city selection logic is implemented in a view script, which loads data from a JSON file and populates dropdowns dynamically.

Uses assets/countries_states_cities.json for data.
JavaScript in app/Views/common_script/allCountryStateCity.php handles the dynamic population.

Helper Function Interactions

Diagram: "Helper Function" Call Relationships

Summary

Common helpers are essential for code reuse and consistency across the Hotelaro system.

They provide database access, formatting, localization, permission checks, and utility functions.
Helpers are used by all major modules, supporting both backend and frontend operations.
Understanding these helpers is critical for extending or maintaining the Hotelaro codebase.