Codex work instructions

dbxapp Work Instructions for Codex

This file describes how Codex should work on dbxapp. She is as Work instructions intended for new sessions.

Basic direction

dbxapp is further developed as a Borland-inspired PHP web RAD runtime. dbxapp is not intended to replicate Laravel, WordPress or React-SPA, but a remain its own component-oriented application environment.

Modules are designed to assemble applications from clear DBX components. The Complexity belongs in system classes and runtime, not in every module.

Application Runtime
 -> Module
 -> Komponenten
    -> Forms
    -> Reports
    -> Grids
    -> Dialoge / OpenWin
    -> Editor
 -> DD/FD Metadaten
 -> Templates
 -> Client-Libs
 -> State / Remember
 -> Services ueber dbx()

Quality objective

Gold is the goal, diamond is the goal. Works-somehow is not enough. Responsibilities must be right, names must be clear, and the Use in modules must remain simple.

Important architectural rules

• HTML belongs in templates, not in PHP code.
• Modules remain thin and easy to read.
• Complexity belongs in system classes.
• DD/FD are metadata and designer layer.
• Templates create the visual structure.
• dbxReport renders reports, but is not firmly tied to DB.
• dbxDB is responsible for DB data and DB actions.
• dbxForm is responsible for forms, field values and state.
• dbxApi / dbx() is the central, clear system-API.
• Callbacks serve for simple individualization without a global event system.
• Own classes such as myReport extends dbxReport remain possible.
• No incompatible concept changes without consultation.

Names and API

Names must be speaking, short enough and clear. The cryptic names are be avoided.

Preferably:

dbx()->get_modul_var('record_count')
dbx()->set_modul_var('record_count', $count)
dbx()->get_remember_var(...)
dbx()->set_remember_var(...)
dbx()->get_system_obj('dbxReport')

Not preferred:

dbx()->mod(...)
dbx()->rem(...)
dbx()->sys(...)

Modules

Modules should follow the principle write less, get more Built will become. The simple standard case should work with little code. In Nevertheless, clean enlargement must be possible.

$oReport = dbx()->get_system_obj('dbxReport');
$oReport->init('report-sessions');
$oReport->_dd = 'dbxSession';

After that, as many things as possible are automatically taken from DD/FD, templates, Report state and system conventions.

Reports and Forms

• Reports and forms are conditionable components.
• If possible, you know your DD/FD.
• They store and restore their condition.
• Reload/F5 should receive the state.
• Field values come from Form, Request or Remember-State.
• Pagination, selection, filters and buttons should work uniformly.
• Date values remain DB-compliant internally and are formatted in the display in a user-friendly manner.

Date formatting in reports should happen centrally:

• _rpt_format[$field] has priority.
• Thereafter: $field['convert'] from DD/FD.
• Thereafter: $field['type'] from DD/FD.

$field['type']='date';
$field['type']='datetime';
$field['convert']='date';
$field['convert']='date_time';

German notification:

2026-05-01              -> 01.05.2026
2026-05-01 16:12:26     -> 01.05.2026 16:12:26
2026-05-01 16:12:26.439 -> 01.05.2026 16:12:26.439

Callbacks

Callbacks should be optional and simple. No global event system, no Listener registration, no priorities, no external modules.

A DBX object calls optional methods on the current module object if they exist. If they are missing, nothing happens.

private function report_sessions_body($oObj, $content) {
    return $content;
}

private function report_sessions_next_record($oObj, $record) {
    return $record;
}

The first parameter is always the calling DBX object. The second parameter is the value to filter. The return replaces the second parameter.

Data source and responsibility

Therefore, DB actions are not allowed in dbxReport lie. Example: Table empty belongs to dbxDB, not to dbxReport.

$ok = $db->delete_tab($dd);

dbxReport may render a button or placeholder for this, but Do not empty the DB table yourself.

Templates

• HTML is generated via templates.
• PHP code is not intended to assemble long HTML fragments.
• Exceptions only for very small, clearly justified special cases.
• Bootstrap classes should be used if it fits for standard UI.
• Component-related styling is in matching CSS files.

Working principle for Codex

1. Before making changes, read the affected files.
2. Observe existing DBX conventions.
3. Make small, targeted patches.
4. No major refactorings without consultation.
5. No incompatible concept changes without consultation.
6. Run PHP-Lint after changes.
7. If useful, run HTTP smoke test for affected route.
8. Old contaminated sites may be removed if the new concept is cleaner.

Current focus

The modernized admin reports are:

• Sessions
• Missing
• SysMsg
• Trace

These reports serve as a reference for new unified DBX report structure.