dbxapp Wissen dbxapp Modulhandbuch – Router, Service und Transaktion
Anwender Entwickler

dbxapp Modulhandbuch – Router, Service und Transaktion

Modulhandbuch · Kapitel 4 von 8

Router, Service und Transaktion

Kleiner Modulrouter, Servicefunktionen, Callbacks und sichere Transaktionsgrenzen.

Kapitel 4 des verbindlichen Modulhandbuchs für das Referenzmodul myInvoices.

6. Kleiner Router

Datei myInvoices.class.php:

<?php
namespace dbx\myInvoices;
class myInvoices
{
public function run()
{
$run = (string)dbx()->get_modul_var(
'dbx_run1',
'report',
'parameter|max=32'
);
$service = dbx()->get_include_obj(
'myInvoicesService',
'myInvoices'
);
switch ($run) {
case 'positions':
return $service->positions();
case 'form':
case 'edit':
return $service->form();
case 'delete':
return $service->delete();
case 'report':
case 'list':
default:
return $service->report();
}
}
}
?>
dbx\myInvoices\myInvoices\run
run()
Verteilt ausschließlich validierte Modulrouten.
Definition myInvoices.class.php:17
$service
$service
Definition dbxDashboard_update_status_contract_test.php:23
dbx
DBX schema administration.

Der Router validiert nur die Route und delegiert. Besonders wichtig: Auch der eingebettete [modul=myInvoices]-Aufruf geht durch dieselbe run()-Methode. Es existiert kein Sonderzugriff auf die Positions-DD.

7. Service: zwei Reports, Callbacks und Transaktion

Datei include/myInvoicesService.class.php:

Der vollständige Quelltext wird direkt eingebunden. Er ist damit die verbindliche Referenz für aktive FD-Meldungen, Spaltenlabels, Confirmtexte, Callback-Defaults, Summen und Transaktionen:

<?php
namespace dbx\myInvoices;
class myInvoicesService
{
private const INVOICE_DD = 'myInvoices|invoice';
private const ITEM_DD = 'myInvoices|invoiceItem';
private const FORM_FD = 'myInvoices|invoice-form';
private const REPORT_FD = 'myInvoices|rpt-invoice-selection';
private int $invoicePageTotalCents = 0;
private int $itemTotalCents = 0;
private function euro(int $cents): string
{
return number_format($cents / 100, 2, ',', '.') . ' EUR';
}
private function url(string $run, array $params = array()): string
{
$url = '?dbx_modul=myInvoices&dbx_run1=' . rawurlencode($run);
foreach ($params as $key => $value) {
$url .= '&' . rawurlencode((string)$key)
. '=' . rawurlencode((string)$value);
}
return $url;
}
public function form(): string
{
$ridValue = dbx()->get_modul_var(
'rid',
'new',
'parameter|max=24'
);
$rid = $ridValue === 'new' ? 0 : (int)$ridValue;
$isNew = $rid <= 0;
$form = dbx()->get_system_obj('dbxForm');
$form->init('invoice-form', 'myInvoices|invoice-form');
$form->_dd = self::INVOICE_DD;
$form->_fd = self::FORM_FD;
$form->load_fd_messages();
$data = $isNew
? array('status' => 'draft')
: dbx()->get_system_obj('dbxDB')->select1(
self::INVOICE_DD,
array('id' => $rid)
);
if (!$isNew && (int)($data['id'] ?? 0) <= 0) {
return dbx()->get_system_obj('dbxTPL')->get_tpl(
'dbx|alert-warning',
array('msg' => $form->get_fd_message('not_found'))
);
}
$form->_data = is_array($data) ? $data : array();
$form->_rid = $rid;
$form->_action = $this->url('form', array(
'rid' => $isNew ? 'new' : $rid,
));
$form->_msg_info = $form->get_fd_message('form_info');
$form->add_rep(
'form_title',
$form->get_fd_message(
$isNew ? 'form_title_new' : 'form_title_edit'
)
);
$form->add_rep(
'bar_title',
$form->get_fd_message('help_title')
);
$form->add_rep('list_url', $this->url('report'));
$form->add_flds();
if ($form->submit()) {
if (!$form->errors()) {
$ok = $form->save_post(
self::INVOICE_DD,
$isNew ? 'new' : $rid
);
$savedRid = (int)$form->_rid;
if ($ok && $isNew && $savedRid > 0) {
$form->_action = $this->url(
'form',
array('rid' => $savedRid)
);
$form->add_rep(
'form_title',
$form->get_fd_message('form_title_edit')
);
}
} else {
$form->_msg_error = $form->get_fd_message(
'validation_error'
);
}
}
return $form->run();
}
public function invoice_report_next_record($report, $record)
{
if (!is_array($record)) {
return $record;
}
$id = (int)($record['id'] ?? 0);
$totalCents = (int)round(
(float)($record['total_gross'] ?? 0) * 100
);
$this->invoicePageTotalCents += $totalCents;
$report->add_rep(
'invoice_report_total',
$this->euro($this->invoicePageTotalCents)
);
$record['action'] = dbx()->get_system_obj('dbxTPL')->get_tpl(
'myInvoices|invoice-row-action',
array(
'edit_url' => $this->url('form', array('rid' => $id)),
'delete_url' => dbx()->action_url(
$this->url('delete', array('rid' => $id))
),
'delete_title' => $report->get_fd_message(
'delete_title'
),
'delete_question' => $report->format_fd_message(
'delete_question',
array('id' => $id)
),
'delete_hint' => $report->get_fd_message(
'delete_hint'
),
)
);
$status = (string)($record['status'] ?? '');
if ($status !== '') {
$record['status'] = $report->get_fd_message(
'status_' . $status,
$status
);
}
$record['total_gross'] = $this->euro($totalCents);
$record['positions_call'] =
'[modul=myInvoices]dbx_run1=positions&invoice_id='
. $id
. '[/modul]';
return $record;
}
public function report(
string $success = '',
string $error = ''
): string {
$db = dbx()->get_system_obj('dbxDB');
$report = dbx()->get_system_obj('dbxReport');
$report->init(
'invoice-report',
'myInvoices|invoice-report'
);
$report->_dd = self::INVOICE_DD;
$report->_mode = 'table';
$report->_action = $this->url('report');
$report->_pages = true;
$report->_but_pagination = 7;
$report->_create_row_select = false;
$report->_create_row_edit = false;
$report->_create_row_delete = false;
$report->add_rep('install_url', $this->url('install'));
$report->create_selection_fields(self::REPORT_FD);
$report->add_rep(
'bar_title',
$report->get_fd_message('report_title')
);
$report->_msg_success = $success === ''
? ''
: $report->get_fd_message($success, $success);
$report->_msg_error = $error === ''
? ''
: $report->get_fd_message($error, $error);
$this->invoicePageTotalCents = 0;
if ($report->submit() && $report->errors()) {
$report->_msg_error = $report->get_fd_message('filter_error');
}
$search = trim((string)$report->get_fld_val(
'dbx_rwhere',
'',
'sqlsearch|max=64'
));
$status = (string)$report->get_fld_val(
'dbx_rstatus',
'all',
'parameter|max=24'
);
$pageSize = max(10, min(50, (int)$report->get_fld_val(
'dbx_rrows',
20,
'int'
)));
$position = max(0, (int)$report->get_fld_val(
'dbx_rpos',
0,
'int'
));
$sort = (string)$report->get_fld_val(
'dbx_rsort',
'invoice_date',
'parameter'
);
$direction = strtoupper((string)$report->get_fld_val(
'dbx_rdesc',
'DESC',
'parameter'
));
$allowedSort = array(
'invoice_no',
'invoice_date',
'customer',
'status',
'total_gross',
);
if (!in_array($sort, $allowedSort, true)) {
$sort = 'invoice_date';
}
if (!in_array($direction, array('ASC', 'DESC'), true)) {
$direction = 'DESC';
}
$where = array();
if (in_array($status, array('draft', 'open', 'paid'), true)) {
$where['status'] = $status;
}
if ($search !== '') {
$where['search'] = array(
'value' => $search,
'like' => array('invoice_no', 'customer'),
'mode' => 'contains',
);
}
$columns = array(
'id',
'invoice_no',
'invoice_date',
'customer',
'status',
'total_gross',
);
$rows = $db->select(
self::INVOICE_DD,
$where,
$columns,
$sort,
$direction,
'',
$pageSize,
$position
);
if (!is_array($rows)) {
return dbx()->get_system_obj('dbxTPL')->get_tpl(
'myInvoices|install-required',
array('install_url' => $this->url('install'))
);
}
$report->_rflds = array(
'invoice_no' => $report->get_fd_message('column_invoice_no'),
'invoice_date' => $report->get_fd_message(
'column_invoice_date'
),
'customer' => $report->get_fd_message('column_customer'),
'status' => $report->get_fd_message('column_status'),
'action' => $report->get_fd_message('column_action'),
'total_gross' => $report->get_fd_message('column_total'),
);
$report->_rpt_format = array(
'invoice_date' => 'php-date-usr',
'action' => 'html',
);
$report->_rrows = $pageSize;
$report->_rpos = $position;
$report->_count_all = $db->count(self::INVOICE_DD);
$report->_rcount = $db->count(self::INVOICE_DD, $where);
$report->_rdata = $rows;
return $report->run();
}
public function invoice_items_report_next_record($report, $record)
{
if (!is_array($record)) {
return $record;
}
$quantity = (float)($record['quantity'] ?? 0);
$unitPrice = (float)($record['unit_price'] ?? 0);
$sumCents = (int)round($quantity * $unitPrice * 100);
$this->itemTotalCents += $sumCents;
$report->add_rep(
'report_total',
$this->euro($this->itemTotalCents)
);
$record['quantity'] = number_format($quantity, 2, ',', '.');
$record['unit_price'] = $this->euro(
(int)round($unitPrice * 100)
);
$record['sum'] = $this->euro($sumCents);
return $record;
}
public function positions(): string
{
$invoiceId = (int)dbx()->get_modul_var(
'invoice_id',
0,
'int'
);
if ($invoiceId <= 0) {
return '';
}
$db = dbx()->get_system_obj('dbxDB');
$invoice = $db->select1(
self::INVOICE_DD,
array('id' => $invoiceId),
array('id', 'invoice_no')
);
if ((int)($invoice['id'] ?? 0) <= 0) {
return '';
}
$rows = $db->select(
self::ITEM_DD,
array('invoice_id' => $invoiceId),
array(
'position_no',
'article_no',
'description',
'quantity',
'unit_price',
),
'position_no',
'ASC'
);
$report = dbx()->get_system_obj('dbxReport');
$report->init(
'invoice-items-report',
'myInvoices|invoice-items-report'
);
$report->_dd = self::ITEM_DD;
$report->_fd = self::REPORT_FD;
$report->load_fd_messages();
$report->_mode = 'table';
$report->_pages = false;
$report->_create_row_select = false;
$report->_create_row_edit = false;
$report->_create_row_delete = false;
$report->add_rep(
'invoice_no',
(string)$invoice['invoice_no']
);
$this->itemTotalCents = 0;
$report->_rflds = array(
'position_no' => $report->get_fd_message(
'column_position_no'
),
'article_no' => $report->get_fd_message(
'column_article_no'
),
'description' => $report->get_fd_message('column_article'),
'quantity' => $report->get_fd_message('column_quantity'),
'unit_price' => $report->get_fd_message(
'column_unit_price'
),
'sum' => $report->get_fd_message('column_total'),
);
$report->_rrows = is_array($rows) ? count($rows) : 0;
$report->_rpos = 0;
$report->_count_all = $report->_rrows;
$report->_rcount = $report->_rrows;
$report->_rdata = is_array($rows) ? $rows : array();
return $report->run();
}
public function delete(): string
{
$rid = (int)dbx()->get_modul_var('rid', 0, 'int');
if ($rid <= 0) {
return $this->report(
'',
'delete_invalid'
);
}
$db = dbx()->get_system_obj('dbxDB');
if ($db->begin(self::INVOICE_DD) !== 1) {
return $this->report(
'',
'transaction_error'
);
}
$itemsDeleted = $db->delete(
self::ITEM_DD,
array('invoice_id' => $rid)
);
$invoiceDeleted = in_array($itemsDeleted, array(0, 1), true)
? $db->delete(self::INVOICE_DD, array('id' => $rid))
: -2;
if ($invoiceDeleted !== 1
|| $db->commit(self::INVOICE_DD) !== 1
) {
$db->rollback(self::INVOICE_DD);
return $this->report(
'',
'delete_error'
);
}
return $this->report('delete_success');
}
public function installation(): string
{
$form = dbx()->get_system_obj('dbxForm');
$form->init(
'myInvoices-install',
'myInvoices|invoice-install'
);
$form->_fd = 'myInvoices|invoice-install';
$form->load_fd_messages();
$form->add_rep(
'bar_title',
$form->get_fd_message('bar_title')
);
if (!dbx()->can('admin')) {
return dbx()->get_system_obj('dbxTPL')->get_tpl(
'dbx|alert-warning',
array('msg' => $form->get_fd_message('admin_required'))
);
}
$form->_action = $this->url('install');
$form->_msg_info = $form->get_fd_message('install_info');
$form->_data = array_merge(
$form->_data,
array('install_demo' => 1)
);
$form->add_rep('report_url', $this->url('report'));
$form->add_fld(
'install_demo',
'dbx|hidden',
rules: 'int',
dd: ''
);
if ($form->submit()) {
if ($form->errors()) {
$form->_msg_error = $form->get_fd_message(
'install_invalid'
);
} else {
$fixtures = dbx()->get_include_obj(
'myInvoicesFixtures',
'myInvoices'
);
$result = $fixtures->install(true);
if ((int)($result['ok'] ?? 0) === 1) {
$form->_msg_success = $form->format_fd_message(
'install_success',
array(
'invoices' => (int)$result['created_invoices'],
'items' => (int)$result['created_items'],
'existing' => (int)$result['existing_invoices'],
)
);
} else {
dbx()->sys_msg(
'error',
'myInvoices',
'install',
'Installation failed',
(string)($result['message'] ?? '')
);
$form->_msg_error = $form->get_fd_message(
'install_failed'
);
}
}
}
return $form->run();
}
}
?>
dbx\myInvoices\myInvoicesService\invoice_report_next_record
invoice_report_next_record($report, $record)
Bereitet eine Rechnungszeile unmittelbar vor dem Rendern auf.
Definition myInvoicesService.class.php:143
dbx\myInvoices\myInvoicesService\report
report(string $success='', string $error='')
Rendert den paginierten Rechnungsreport.
Definition myInvoicesService.class.php:205
dbx\myInvoices\myInvoicesService\form
form()
Rendert und verarbeitet das Rechnungskopfformular.
Definition myInvoicesService.class.php:54
$form
$form
Definition dbxActionTokenAutomation_test.php:260
$report
if((string)($formActionPolicy['action'] ?? '') !=='dbxAction.save'||!dbx() ->check_action_token((string)($formActionPolicy['scope'] ?? ''),(string)($formActionRoute['params']['dbx_token'] ?? ''))) $report
Definition dbxActionTokenAutomation_test.php:275
action_url
action_url(string $url, string $action='', array $bindings=array())
Tokenisiert eine automatisch erkannte zustandsaendernde Route.
Definition dbxApi.php:1252
dbx
dbx()
Liefert die zentrale dbxapp-API als Singleton.
Definition dbxApi.php:2765
can
can($access_groups='', $user_groups='')
Prueft Gruppenrechte gegen den aktuellen oder uebergebenen Benutzer.
Definition dbxApi.php:1363
$rows
$rows
Definition dbxContentMarketingDeMigration_test.php:38
$db
$db
Definition dbxDB_dd_server_binding_test.php:52
$value
$value
Definition dbxForm_validation_result_test.php:28
$result
$result
Definition dbxForm_validation_result_test.php:29
$url
$url
Definition dbxKiBundleService_cms_url_test.php:9
$fixtures
$fixtures
Definition myInvoices_integration_test.php:37

Was die Servicefunktionen bewirken

Funktion Aufgabe und Wirkung
euro() Formatiert die im Modul bewusst als Integer-Cent geführten Summen einheitlich für die Ausgabe.
url() Baut eine Modulroute und kodiert ausschließlich Querybestandteile. Sie ist Fachlogik für konsistente Routen, kein Alias auf dbx().
form() Liest über die Kopf-DD, lässt dbxForm FD, Validierung und Submit ausführen und speichert über save_post().
invoice_report_next_record() Ist der automatische {fid}_next_record-Callback: formatiert den Snapshot, signiert die Delete-Route, sammelt die Seitensumme per spätem add_rep() und setzt den [modul=...]-Aufruf für Stufe zwei.
report() Führt Selection-FD, Allowlist, Count, paginiertes Select und den äußeren table-Report zusammen.
invoice_items_report_next_record() Ist der automatische Positions-Callback: berechnet quantity * unit_price, setzt die virtuelle Spalte sum und aktualisiert die Endsumme per add_rep().
positions() Prüft die geschützte invoice_id, liest Kopf und Positionen über DDs und rendert eine eigenständige, nicht paginierte Reportinstanz.
delete() Wird erst nach zentraler Policy-Prüfung aufgerufen, validiert die RID und löscht Positionen plus Kopf unter DD-Rechten atomar über begin(), commit() und rollback().

Die Callbackmethoden sind echte Aufbereitungslogik. Sie sind ausdrücklich keine Modulmethoden, die nur dbx()-Funktionen weiterreichen.

Nach einem erfolgreichen Insert übernimmt form() die von dbxForm gesetzte _rid in Action und Titel. Ein weiterer Submit aktualisiert deshalb denselben Datensatz, statt unbeabsichtigt einen zweiten Insert zu versuchen.

Callback-Lebenszyklus

  1. dbxForm::init() übernimmt den direkten Modul-/Service-Aufrufer als Callback-Owner. set_callback_owner($this) ist im Normalfall unnötig.
  2. Die Formular-ID wird zur Callback-ID: invoice-report sucht automatisch invoice_report_next_record(), invoice-items-report entsprechend invoice_items_report_next_record().
  3. Ein expliziter Callback-Setter ist nur nötig, wenn bewusst von dieser Namenskonvention abgewichen wird.
  4. add_rep() darf auch während des Record-Laufs Werte setzen. Die von dbxForm bereitgestellte replaces()-Pipeline wendet sie im Footer mit dem zuletzt akkumulierten Wert an.
  5. {rpt:col_count} umfasst alle Reportspalten. {rpt:colspan} umfasst automatisch alle Spalten außer der letzten Wertespalte.