# MOSAIC PayPal Modul

## Uebersicht

Der PayPal-Baustein besteht aus drei Teilen:

- `_pgm/admin/create_paypal.php`
  Erzeugt im Projekt eine Konfigurationsdatei mit dem Suffix `_paypal.cfg`.
- `<name>_paypal.cfg`
  Modulbezogene Laufzeitkonfiguration fuer Checkout, Request-Parameter und UI.
- `<name>_paypal_function.php`
  Automatisch erzeugte Hook-Datei im MOSAIC-Stil.
- `_pgm/show_paypal.php`
  Runner fuer Checkout, Success, Cancel und Webhook.

## Globale Systemdaten

`show_paypal.php` liest die Systemdaten zuerst aus:

- `<projekt>/mosaic_config.lic`
- Fallback: `<projekt>/config.php`

Relevant ist dort nur noch der schlanke Block `paypal`:

```php
'paypal' => [
    'enabled' => true,
    'environment' => 'sandbox',
    'client_id' => '',
    'client_secret' => '',
    'webhook_id' => '',
    'currency' => 'EUR',
    'locale' => 'de-DE',
    'brand_name' => '',
    'timeout' => 30,
    'debug' => false,
    'log_file' => '_logs/paypal.log',
],
```

Legacy-Felder aus alten PayPal-Konfigurationen werden in `config_edit.php` beim Laden auf diese Struktur migriert.

## Moduldatei

Beispiel fuer eine Moduldatei:

```php
return [
    'app' => [
        'type' => 'paypal',
        'version' => 1,
        'title' => 'PayPal Checkout',
    ],
    'hooks_file' => 'checkout_paypal_function.php',
    'payment' => [
        'amount' => '49.90',
        'currency' => 'EUR',
        'capture_on_return' => true,
        'item_name' => 'Seminargebuehr',
        'description' => 'Anmeldung Seminar 2026',
    ],
    'request' => [
        'allow_amount_override' => false,
        'allow_reference_override' => true,
        'invoice_param' => 'invoice_id',
        'custom_param' => 'custom_id',
    ],
    'urls' => [
        'action_param' => 'paypal_action',
        'success_action' => 'success',
        'cancel_action' => 'cancel',
        'webhook_action' => 'webhook',
    ],
    'ui' => [
        'headline' => 'Jetzt sicher mit PayPal bezahlen',
        'button_label' => 'Mit PayPal bezahlen',
        'auto_redirect' => false,
    ],
    'webhook' => [
        'enabled' => true,
        'validate_signature' => true,
    ],
];
```

## Aufruf

Direkter Aufruf:

```text
_pgm/show_paypal.php?project=<projekt>&modul=<name>&modul_path=<ordner>
```

Beispiel:

```text
_pgm/show_paypal.php?project=svsb&modul=checkout&modul_path=shop
```

Die zugehoerige Datei muss dann hier liegen:

```text
svsb/shop/checkout_paypal.cfg
```

## Hooks

`show_paypal.php` erkennt diese optionalen Hooks:

- `onApplicationInit(array &$context, array &$paypalConfig, array &$systemConfig)`
- `onCheckSecurity(array &$context, array &$paypalConfig, array &$systemConfig)`
- `onResolvePayment(array &$context, array &$payment, array &$paypalConfig, array &$systemConfig)`
- `onBeforeCreateOrder(array &$context, array &$orderPayload, array &$payment, array &$paypalConfig, array &$systemConfig)`
- `onAfterCreateOrder(array &$context, array &$paypalOrder, array &$payment, array &$paypalConfig, array &$systemConfig)`
- `onBeforeCapture(array &$context, string &$orderId, array &$paypalConfig, array &$systemConfig)`
- `onAfterCapture(array &$context, array &$capturePayload, array &$paypalConfig, array &$systemConfig)`
- `onWebhook(array &$context, array &$webhookEvent, array &$paypalConfig, array &$systemConfig)`
- `onBeforeRender(array &$context, array &$renderPayload, array &$paypalConfig, array &$systemConfig)`
- `onAfterRender(array &$context, array &$renderPayload, array &$paypalConfig, array &$systemConfig)`

## Verhalten von `show_paypal.php`

Der Runner unterstuetzt vier Modi:

- Standardansicht: zeigt Checkout-Seite und Zusammenfassung
- `paypal_action=checkout`: legt eine PayPal-Order an und leitet zur Freigabe weiter
- `paypal_action=success`: fuehrt optional direkt den Capture aus
- `paypal_action=cancel`: zeigt Abbruchseite
- `paypal_action=webhook`: verarbeitet Webhooks und prueft optional die Signatur gegen `paypal.webhook_id`

## Menu und Dashboard

Folgende Integrationen sind vorbereitet:

- `create_menu.php` erkennt `_paypal.cfg` und setzt den Runner auf `show_paypal.php`
- `show_menu.php` folgt im Kern dem einheitlichen `show_*`-Konzept; PayPal-Module laufen dort ueber `show_paypal.php`
- `show_dashboard.php` erkennt `_paypal.cfg` und laedt das Modul ueber `show_paypal.php`

## Generator

`create_paypal.php` schreibt immer beides:

- `<name>_paypal.cfg`
- `<name>_paypal_function.php`

Die Hook-Datei wird passend zum Modulnamen erzeugt und enthaelt bereits alle Standard-Hooks als Geruest.
## Runner-Stand im Kern

Stand April 2026 gilt im MOSAIC-Kern ein einheitliches Runner-Schema:

- `grid.php`, `form.php` und `show_egrid.php` bilden die kanonischen CRUD-Einstiege; `show_egrid.php` delegiert intern an `egrid.php`
- alle anderen fachlichen Runner verwenden konsequent das Praefix `show_`
- typische Beispiele sind `show_menu.php`, `show_dashboard.php`, `show_report.php`, `show_chart.php`, `show_login.php` und `show_v_menu.php`
- fruehere Alt-Namen sind nicht mehr Bestandteil des aktiven Kernbereichs