Markdown (Eisvogel)

25now-theme-entwicklerdokumentation.md

---
title: "Itk25nowTheme"
subtitle: "Entwicklerdokumentation"
author: ["André Fischer"]
date: "02-04-2026"
lang: de
titlepage: true
titlepage-color: "1E3A5F"
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "4A90D9"
titlepage-rule-height: 4
toc: true
toc-own-page: true
numbersections: true
header-left: "Itk25nowTheme"
header-right: "Entwicklerdokumentation"
footer-left: "André Fischer"
---

# Einordnung

- **Shopware-Plugin-Klasse:** `ItkComputerGmbh\Itk25NowTheme\Itk25NowTheme`
- **PSR-4:** `ItkComputerGmbh\Itk25NowTheme\` → `custom/plugins/Itk25nowTheme/src/`
- **Theme:** implementiert `Shopware\Storefront\Framework\ThemeInterface`; technischer Theme-Name laut `theme.json`: **25now**
- **Child-Theme:** [Itk25NowChildTheme](itk25nowchildtheme-entwicklerdokumentation.md) (UltraForce) erbt von diesem Theme (`parentTheme`: `Itk25NowTheme`).

Diese Doku beschreibt **PHP, DI, Konfiguration, Events, Import/Export, CMS-Resolver, Storefront-Controller, Twig-Extension (PHP-API), Migrationen, CLI und Logging**. **Inhalte von `.twig`-Dateien** werden nicht wiedergegeben; bei E-Mail-/View-Verwendung nur Bundle-Pfade genannt.

**Wichtig**: Die Doku bezieht sich auf den Staging Stand - nicht alles, was hier Dokumentiert ist, ist auch im Live deployed. Ist natürlich trotzdem Sinnvoll einen überblick zu haben, auch über Sachen die nicht deployed sind.

---

::: {.pdf-landscape}
# Architekturüberblick

```mermaid
flowchart TB
  subgraph lifecycle [Plugin Lifecycle]
    P[Itk25NowTheme]
    TCFS[ThemeCustomFieldService]
    P -->|install activate update| TCFS
  end
  subgraph storefront [Storefront]
    EC[EasterEggController]
    ADC[AccountDeleteController]
    TW[ItkTwigExtension]
  end
  subgraph events [Events]
    PCF[ProductCustomFieldSubscriber]
    PCE[ProductCustomFieldExcludeSubscriber]
    WISH[WishlistProductIdsPageSubscriber]
    ACC[AccountTypeChangeSubscriber]
    ECIE[EasyCouponImportExportSubscriber]
  end
  subgraph infra [Cross-Cutting]
    RFS[RobustFieldSerializer decorates FieldSerializer]
    PIC[ProductInfoCardCmsElementResolver]
  end
  TCFS --> DAL[(custom_field_set)]
  EC --> DB[(DBAL Custom Tables)]
  TW --> HS[HolidayService]
  TW --> CAT[category.repository]
```

:::

# Plugin-Hauptklasse

Datei: `custom/plugins/Itk25nowTheme/src/Itk25NowTheme.php`

| Methode | Verhalten |
|---------|-----------|
| **install** | Ruft `installCustomFields()` auf. |
| **activate** | Ruft `installCustomFields()` auf (Anlegen/Aktualisieren der Produktbox-Custom Fields). |
| **update** | Ruft `installCustomFields()` auf. |
| **deactivate** | Leer (Custom Fields bleiben). |
| **uninstall** | `parent::uninstall`; wenn **kein** `keepUserData`, dann `uninstallCustomFields('product_box_settings', …)` via `ThemeCustomFieldService`. |

**installCustomFields:** Liest aus dem Container `ThemeCustomFieldService` und ruft `installProductBoxCustomFields($context->getContext())` auf. Fehler → `logger` mit Meldung „Fehler bei der Installation der Custom Fields …“.

---

# `theme.json` (Parent-Theme)

Pfad: `custom/plugins/Itk25nowTheme/src/Resources/theme.json`

| Schlüssel | Inhalt (Kurz) |
|-----------|----------------|
| **name** | `25now` |
| **script** | `@Storefront`, `@Plugins`, `@Itk25NowTheme` – Theme-JS nach Storefront/Plugins. |
| **views** | `@Storefront`, `@Itk25NowTheme`, `@Plugins` – Theme-Templates **vor** `@Plugins`, damit Plugin-Overrides nach dem Theme greifen können. |
| **style** | `@Storefront`, `@Plugins`, dann `app/storefront/src/scss/main.scss`. |
| **asset** | Eigene Assets + Fonts + `@Storefront`. |

\newPage{}

# Custom Fields

Wichtig anzumerken ist, dass das Theme nicht alle Custom Fields installiert. Eine Doku, welche Custom Fields vom Theme gebraucht werden wird noch benötigt.

## `ThemeCustomFieldService`

Datei: `custom/plugins/Itk25nowTheme/src/Service/ThemeCustomFieldService.php`

- **`installProductBoxCustomFields(Context)`**  
  Lädt `getProductBoxCustomFieldSetData()`, sucht per `EqualsFilter` auf Set-**name** `product_box_settings`.  
  - **Existiert:** `update` mit bestehender `id`; **relations** werden entfernt (`unset`), um Integritätskonflikte zu vermeiden; bestehende Felder erhalten ihre **id** für Update statt Duplicate-Create.  
  - **Neu:** `create` des kompletten Sets.

- **`installCustomerCustomFields(Context)`**  
  Analog für Set **`customer_trusted_shops_settings`** (Relation **customer**), Feld u. a. **`trustedShopConsent`**.

- **`uninstallCustomFields(string $setName, Context)`**  
  Löscht das Set per Name, falls vorhanden.

### Set `product_box_settings` (Relation: **category**)

| Feldname (Custom Field) | Typ | Zweck (Kurz) |
|-------------------------|-----|----------------|
| `custom_product_box_show_description` | bool | Kurzbeschreibung in der Box |
| `custom_product_box_show_advantages` | bool | Produktvorteile |
| `custom_product_box_horizontal_layout` | bool | Horizontales Layout |
| `custom_product_box_show_delivery_time` | bool | Lieferzeit |
| `custom_product_box_show_advantages_icons` | bool | Label: Icons bei Vorteilen **verstecken** |

**Hinweis:** `ItkTwigExtension::getBoxSettings()` liefert zusätzlich den Schlüssel **`showDeliveryInAdvantages`** aus `custom_product_box_show_delivery_in_advantages` – dieses Feld ist in `getProductBoxCustomFieldSetData()` **nicht** definiert; ohne manuelles Feld bleibt der Default `false`.

## `CustomFieldInstaller`

Datei: `custom/plugins/Itk25nowTheme/src/Service/CustomFieldInstaller.php`

- **`installCustomFields(string $xmlFilePath, Context)`** – parst XML, legt/aktualisiert ein Custom-Field-Set (Pfad muss existieren).
- **`installAdditionalHolidaysField(Context)`** – Set **`itk25_additional_holidays`**, Relation **sales_channel**, Feld **`custom_additional_holidays`** (Text; Format laut CLI-Hilfe: `YYYY-MM-DD` semikolongetrennt). Wird von **`itk:custom-fields:install`** aufgerufen.

---

# System-Konfiguration (`config.xml`)

Pfad: `custom/plugins/Itk25nowTheme/src/Resources/config/config.xml`

| Key | Typ | Pflicht | Verwendung |
|-----|-----|---------|------------|
| **Itk25NowTheme.config.companyEmail** | text | ja | Support-Mail bei Kontolöschung (`AccountDeleteController`) |
| **Itk25NowTheme.config.companyName** | text | ja | Absendername |

Fallbacks im Code: `info@25now.de` / `25NOW`, wenn Config leer.

---

# Dependency Injection (`services.xml`)

Pfad: `custom/plugins/Itk25nowTheme/src/Resources/config/services.xml`

Auszug der wichtigsten Services (vollständige Definition im XML):

| Service / ID | Klasse | Tag / Besonderheit |
|----------------|--------|---------------------|
| `ItkComputerGmbh\Itk25NowTheme\Twig\ItkTwigExtension` | ItkTwigExtension | `twig.extension` |
| `ItkComputerGmbh\Itk25NowTheme\Core\Content\Cms\ProductInfoCardCmsElementResolver` | ProductInfoCardCmsElementResolver | `shopware.cms.data_resolver` |
| `ThemeCustomFieldService` / `CustomFieldInstaller` | – | normale Services |
| `CustomFieldInstallCommand` | – | `console.command`; Argument: `%kernel.project_dir%/custom/plugins/Itk25nowTheme` |
| `ProductCustomFieldSubscriber` | – | `kernel.event_subscriber` |
| `ProductCustomFieldExcludeSubscriber` | – | `kernel.event_subscriber` |
| `WishlistProductIdsPageSubscriber` | – | `kernel.event_subscriber` |
| `AccountTypeChangeSubscriber` | – | `kernel.event_subscriber` |
| `EasyCouponImportExportSubscriber` | – | `kernel.event_subscriber` |
| `EasterEggController` | – | `public="true"`, `setContainer` |
| `AccountDeleteController` | – | `public="true"`, `setContainer`, `setTwig` |
| `RegistrationIpLogService` | – | DBAL `Connection` (siehe Abschnitt *Bekannte Inkonsistenzen*) |
| `HolidayService` | – | optional `cache.app`, Logger |
| `RobustFieldSerializer` | – | **decorates** `FieldSerializer`, `decoration-priority="100"` |

**Logger (Monolog, Level 100 = DEBUG):**

| Logger-ID | Datei unter `var/log/` |
|-----------|-------------------------|
| `itk_cms_ajax_modal_twig` | `itk_cms_ajax_modal_twig.log` |
| `itk_product_cf_edit_logger` | `itk_product_cf_edit_logger.log` |
| `itk_product_exclude` | `itk_product_exclude.log` |
| `itk_holiday_service` | `itk_holiday_service.log` |
| `itk_easy_coupon_import` | `itk_easy_coupon_import.log` |

---

# Storefront-Controller

## `EasterEggController`

- **Klasse:** `ItkComputerGmbh\Itk25NowTheme\Controller\EasterEggController`
- **Abhängigkeiten:** `Doctrine\DBAL\Connection`, `NetInventors\NetiNextEasyCoupon\Service\CustomerAssignmentService`, `neti_easy_coupon_customer_assignment.repository`
- **Voraussetzung:** Plugin **NetiNextEasyCoupon** muss verfügbar sein.

| Route-Name | Methode | Pfad | Verhalten (Kurz) |
|------------|---------|------|------------------|
| `frontend.itk.easter-egg.claim` | POST | `/itk/easter-egg/claim` | Body: `egg_id`. Nur eingeloggte Kunden. Tageslimit: max. **3** Zuweisungen pro Tag (Zählung über `_itk_easter_eggs.customer_assigned` = numerischer Wert aus **Kundennummer**). Prüfung Sichtbarkeit `visible_from`/`visible_to`, `live`/Session. Bei Gutschein: UUID in `coupon` → Code aus `neti_easy_coupon`, ggf. Assignment + `triggerCustomerAssignmentEvent`. JSON: `success`, `message`, `coupon_code`. |
| `frontend.itk.easter-egg.add-voucher-to-cart` | POST | `/itk/easter-egg/add-voucher-to-cart` | Body: `code` → `CustomerAssignmentService::addVoucherToCartByCode`. |

**Tabellen (Custom, nicht DAL):** `_itk_easter_eggs`, `_itk_easter_eggs_log` (Nutzung u. a. in Controller und `ItkTwigExtension`).

## `AccountDeleteController`

- **Route:** `POST` **`/account/delete-request`**, Name **`frontend.account.delete.request`**
- Eingeloggt erforderlich; sonst Redirect Login + Flash.
- Versendet zwei Mails via `MailService` (Kontext `Context::createDefaultContext()`), Inhalte gerendert über:
  - `@Itk25NowTheme/storefront/emails/account-delete-support.html.twig` Mail an den Support
  - `@Itk25NowTheme/storefront/emails/account-delete-customer.html.twig`  Mail an den Kunden

---

# Twig-Extension: `ItkTwigExtension` (PHP-API)

Datei: `custom/plugins/Itk25nowTheme/src/Twig/ItkTwigExtension.php`  
Tag: `twig.extension`  
Injections: `category.repository`, `HolidayService`, `request_stack`, `Doctrine\DBAL\Connection`, `router`, Logger `itk_cms_ajax_modal_twig`.

Alle registrierten **TwigFunction**-Namen:

| Funktion | Rückgabe / Wirkung |
|----------|--------------------|
| **get_theme_version** | `string`: Version aus `composer.json` neben `src/` (`unknown` bei Fehlen). |
| **is_darkmode_enabled** | `bool`: prüft `custom_theme_settings_use_darkmode` in Produkt-, Kategorie-, Landingpage-, Hersteller-Übersetzungen, Sales Channel, ggf. Kategorie-Hierarchie / SEO-Kategorie. |
| **is_black_week_blue_enabled** | `bool`: läuft Kategorie-Hierarchie hoch, Feld `custom_black_week_is_black_week_blue`. |
| **is_black_week_enabled** | `bool`: wie Darkmode, aber Black-Week-Feld auf Produkt/Kategorie/Landing/SalesChannel/Hersteller + Hierarchie. |
| **get_box_settings** | `array`: Keys `showDescription`, `showAdvantages`, `horizontalLayout`, `showDeliveryTime`, `showDeliveryInAdvantages`, `hideAdvantagesIcons` aus Kategorie-Custom-Fields (Defaults siehe Code). |
| **get_category_from_id** | `CategoryEntity|null` |
| **adjust_workdays** | `DateTimeInterface`: Delegation an `HolidayService::adjustToWorkday`; Sales-Channel-ID ggf. aus Request-Attribut `sw-sales-channel-id`. |
| **get_recommended_properties** | `array`: Zeilen aus `_itk_sw6_recommended_product_properties`, UUIDs als Hex. |
| **get_itk_easter_eggs** | `array`: Osterei-Logik mit DB `_itk_easter_eggs` / `_itk_easter_eggs_log`, Zufall/`random_factor`, Reservierung über `live`/`live_at`. |
| **get_itk_easter_eggs_user_limit** | **Deklariert `int`**, bei `$customer === null` liefert der Code fälschlich **`[]`** (Typinkonsistenz im Quellcode). Sonst `0` oder `1` je nach Limits (Tag / 30 Min). |
| **dd** | `dump` + `die` (nur für Debugging). |
| **itk_cms_ajax_modal** | HTML+Inline-JS: Bootstrap-Modal, lädt per `fetch` die URL `frontend.cms.page` (+ optional `navigationId`). **Options:** `id`, `closable`, `title`, `autoOpen`, `timer` (Schließen verzögern), `onlyOncePerSession` (sessionStorage), `openInTimer` (Öffnen verzögern). Logger bei Bedarf. |

---

# Weitere Subscriber und Services

## `ProductCustomFieldSubscriber`

- **Event:** `product.written` → `onProductWritten`
- Loggt bei gesetztem Produkt-Custom-Field **`onco_sfc_load_configuration_id`** (INFO), sonst DEBUG, inkl. Admin-User aus Context → `itk_product_cf_edit_logger.log`.

## `ProductCustomFieldExcludeSubscriber`

- **Custom Field (DAL-Pfad):** `customFields.custom_product_infos_important_hide_product` (Multi-Select, als JSON-Liste gespeichert).
- **Events** (alle mit Priorität **-100**, nach Doofinder o. Ä.): `ProductSearchCriteriaEvent`, `ProductSuggestCriteriaEvent`, `ProductCrossSellingCriteriaEvent`, `ProductCompareCriteriaEvent`, `ProductQuickViewCriteriaEvent`, `ProductListingCriteriaEvent`, `WishListPageProductCriteriaEvent`, `GuestWishListPageletProductCriteriaEvent`.
- Mappt Event-Klassen auf Werte (`search`, `listing`, …); bei Listing wird bei Such-Route/Parametern **`search`** statt `listing` verwendet.
- Filter: Produkt sichtbar, wenn Feld **null** oder **not contains** Event-Wert im JSON-String.

## `WishlistProductIdsPageSubscriber`

- **Events:** `GenericPageLoadedEvent`, `NavigationPageLoadedEvent`, `SearchPageLoadedEvent`, `ProductPageLoadedEvent`
- **Extension:** `itkWishlistProductIds` auf der Page als `ArrayStruct` mit `ids` (Hex-Product-IDs), nur für eingeloggte Kunden; liest `customer_wishlist` / `customer_wishlist_product` per DBAL.

## `AccountTypeChangeSubscriber`

- **Events:** `CustomerEvents::CUSTOMER_WRITTEN_EVENT`, `checkout.customer.profile.update`
- Hält **`accountType`** bei Schreibvorgängen/Profil-Update an den **persistierten** Wert (Änderungsversuche werden überschrieben bzw. Request angepasst).

## `HolidayService`

- Feiertage pro Jahr (API + optional Sales-Channel-Custom-Field **`custom_additional_holidays`**), Cache `cache.app` mit TTL bis Jahresende, Methoden u. a. `getHolidaysForYear`, `isHoliday`, `isWeekend`, `isWorkday`, `adjustToWorkday`, `clearAllCache`, `cleanupOldHolidays`, `debugCache`.

## `CategoryCopyService` / `itk:copy:category` (Experimentell - nicht deployed)

- Kopiert eine Kategorie inkl. aller Kinder; neue Wurzel: **„&lt;Name&gt; - Kopie“**, Kinder behalten Namen.

---

# CLI-Befehle

| Befehl | Klasse | Beschreibung |
|--------|--------|--------------|
| **itk:copy:category** | `CopyCategoryCommand` | Argument **`category_id`** (UUID). |
| **itk:holiday:test** | `HolidayServiceTestCommand` | Optionen: `--year`, `--sales-channel`, `--clear-cache`, `--test-api`, `--test-cache`, `--test-custom-fields`, `--cleanup`, `--interactive`, `--date`. |
| **itk:custom-fields:install** | `CustomFieldInstallCommand` | Installiert/aktualisiert Produktbox-Felder, Kunden-Felder (Trusted Shops), über `CustomFieldInstaller` zusätzliche Feiertage am Sales Channel. |

---

# Storefront-JavaScript (Einstieg)

- **`src/Resources/app/storefront/src/main.js`:** importiert `./js/badges`, registriert Plugin **`CompareModal`** für Selektor `[data-compare-modal]`.
- **`src/Resources/app/storefront/src/js/main.js`:** `./labels`, `./checkout`.
- Weitere Plugin-Quelldateien existieren unter `plugin/` (z. B. `gallery-slider.plugin.js`, `horizontal-product-navigation.plugin.js`); ohne Registrierung in `main.js` sind sie im gebauten Theme ggf. inaktiv, sofern nicht anderweitig eingebunden.

---

# Abhängigkeiten zur Laufzeit (Überblick)

- **Storefront / Core:** Standard.
- **NetiNextEasyCoupon:** `EasterEggController`, `EasyCouponImportExportSubscriber`, Migration Profil `neti_easy_coupon`.
- **Optionale DB-Strukturen:** `_itk_easter_eggs`, `_itk_easter_eggs_log`, `_itk_sw6_recommended_product_properties` (keine Shopware-Migrationen im Theme dafür im überprüften Umfang – Betrieb/DB-Verantwortung).