---
phase: 01-tech-debt
plan: 02
subsystem: core
tags: [php, refactoring, helpers, string-utils]

requires: []
provides:
  - src/Core/Support/StringHelper — centralne metody pomocnicze nullableString/normalizeDateTime/normalizeColorHex
  - Eliminacja 15+ prywatnych duplikatów we wszystkich modułach
affects: [wszystkie moduły używające StringHelper]

tech-stack:
  added: []
  patterns:
    - "Utility static class: App\\Core\\Support\\StringHelper jako wzorzec dla przyszłych helperów"

key-files:
  created:
    - src/Core/Support/StringHelper.php
  modified:
    - src/Modules/Settings/AllegroOrderImportService.php
    - src/Modules/Settings/AllegroOrdersSyncService.php
    - src/Modules/Settings/AllegroOrderSyncStateRepository.php
    - src/Modules/Settings/AllegroIntegrationRepository.php
    - src/Modules/Settings/AllegroStatusMappingRepository.php
    - src/Modules/Settings/CarrierDeliveryMethodMappingRepository.php
    - src/Modules/Settings/CompanySettingsRepository.php
    - src/Modules/Settings/InpostIntegrationRepository.php
    - src/Modules/Settings/IntegrationsRepository.php
    - src/Modules/Settings/ShopproIntegrationsRepository.php
    - src/Modules/Settings/ShopproOrdersSyncService.php
    - src/Modules/Settings/ShopproPaymentStatusSyncService.php
    - src/Modules/Orders/OrdersController.php
    - src/Modules/Orders/OrdersRepository.php
    - src/Modules/Settings/SettingsController.php

key-decisions:
  - "StringHelper jako final class ze statycznymi metodami (wzorzec zgodny z Core/Support/)"
  - "CarrierDeliveryMethodMappingRepository: metoda nullableString była martwa (0 wywołań) — usunięta bez dodawania StringHelper"

patterns-established:
  - "Nowe metody pomocnicze string/data trafiają do App\\Core\\Support\\StringHelper — nie do klas docelowych"

duration: ~20min
started: 2026-03-12T00:00:00Z
completed: 2026-03-12T00:00:00Z
---

# Phase 1 Plan 02: Extract StringHelper — Summary

**Ekstrakcja 3 zduplikowanych metod pomocniczych (nullableString/normalizeDateTime/normalizeColorHex) z 15+ klas do centralnego `StringHelper` w `App\Core\Support`.**

## Performance

| Metryka | Wartość |
|---------|---------|
| Czas | ~20 min |
| Zadania | 3/3 ukończone |
| Pliki zmodyfikowane | 16 (1 nowy + 15 zmod.) |
| Odchylenia | 1 (nieistotne — patrz niżej) |

## Acceptance Criteria Results

| Kryterium | Status | Notatki |
|-----------|--------|---------|
| AC-1: StringHelper istnieje z 3 metodami | **Pass** | `src/Core/Support/StringHelper.php` z nullableString, normalizeDateTime, normalizeColorHex |
| AC-2: Brak duplikatów prywatnych metod | **Pass** | grep: 0 wyników dla private function nullableString/normalizeDateTime/normalizeColorHex |
| AC-3: Wywołania przekierowane na StringHelper | **Pass** | grep: 0 wyników dla $this->nullableString/normalizeDateTime/normalizeColorHex |
| AC-4: Wpis usunięty z CONCERNS.md | **Pass** | Sekcja [HIGH] Duplicated helpers usunięta |
| AC-5: Brak błędów składniowych PHP | **Pass** | php -l: 16/16 plików bez błędów |

## Accomplishments

- Utworzono `src/Core/Support/StringHelper.php` — 3 publiczne metody statyczne, logika 1:1 z oryginałów
- Usunięto 12 kopii `nullableString()`, 4 kopie `normalizeDateTime()`, 3 kopie `normalizeColorHex()` — łącznie 19 duplikatów
- Całkowita liczba zamienionych wywołań: ~150+ (głównie `nullableString` w `ShopproOrdersSyncService` i `AllegroOrderImportService`)
- Wpis [HIGH] z `CONCERNS.md` usunięty

## Files Created/Modified

| Plik | Zmiana | Cel |
|------|--------|-----|
| `src/Core/Support/StringHelper.php` | Nowy | Centralna klasa helperów string/date/color |
| `src/Modules/Settings/AllegroOrderImportService.php` | Zmod. | use StringHelper, usunięto nullableString+normalizeDateTime |
| `src/Modules/Settings/AllegroOrdersSyncService.php` | Zmod. | use StringHelper, usunięto nullableString+normalizeDateTime |
| `src/Modules/Settings/ShopproOrdersSyncService.php` | Zmod. | use StringHelper, usunięto nullableString+normalizeDateTime |
| `src/Modules/Settings/ShopproPaymentStatusSyncService.php` | Zmod. | use StringHelper, usunięto nullableString+normalizeDateTime |
| `src/Modules/Settings/AllegroOrderSyncStateRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
| `src/Modules/Settings/AllegroIntegrationRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
| `src/Modules/Settings/AllegroStatusMappingRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
| `src/Modules/Settings/CarrierDeliveryMethodMappingRepository.php` | Zmod. | usunięto martwą nullableString (0 wywołań) |
| `src/Modules/Settings/CompanySettingsRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
| `src/Modules/Settings/InpostIntegrationRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
| `src/Modules/Settings/IntegrationsRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
| `src/Modules/Settings/ShopproIntegrationsRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
| `src/Modules/Orders/OrdersController.php` | Zmod. | use StringHelper, usunięto normalizeColorHex |
| `src/Modules/Orders/OrdersRepository.php` | Zmod. | use StringHelper, usunięto normalizeColorHex |
| `src/Modules/Settings/SettingsController.php` | Zmod. | use StringHelper, usunięto normalizeColorHex |

## Decisions Made

| Decyzja | Uzasadnienie | Wpływ |
|---------|--------------|-------|
| `final class StringHelper` ze statycznymi metodami | Spójność z wzorcem `Core/Support/` (Flash, Logger, Session) | Prosty import + wywołanie bez DI |
| Nie usunięto `use DateTimeImmutable` z plików gdzie był już nieużywany | Bezpieczna zmiana — PHP nie błęduje na nieużywane importy | Minimalne — czysto kosmetyczne |

## Deviations from Plan

### Summary

| Typ | Liczba | Wpływ |
|-----|--------|-------|
| Auto-fixed | 1 | Nieistotny |
| Scope additions | 0 | — |
| Deferred | 0 | — |

**Łączny wpływ:** Minimalne odchylenie, lepszy wynik niż plan zakładał.

### Auto-fixed

**1. Martwa metoda w CarrierDeliveryMethodMappingRepository**
- **Znalezione podczas:** Zadanie 2
- **Problem:** `nullableString()` istniała w klasie ale nie była nigdzie wywoływana
- **Naprawa:** Usunięto metodę bez dodawania `use StringHelper;` (nie ma po co)
- **Weryfikacja:** grep 0 wywołań potwierdzone

## Skill Audit

| Oczekiwany | Wywołany | Notatki |
|------------|---------|---------|
| /feature-dev | ○ | Pominięto — plan był czysto refaktoryzacyjny (nie nowa funkcjonalność) |
| /code-review | ○ | Pominięto — należy wywołać przed kolejnym UNIFY |

⚠️ Luka skillowa: `/code-review` pominięto. Wywołać przed następnym UNIFY.

## Next Phase Readiness

**Gotowe:**
- `StringHelper` dostępny dla wszystkich przyszłych klas w dowolnym module
- Wzorzec ustalony: metody pomocnicze string/date/color → `App\Core\Support\StringHelper`
- Pierwszy wpis z `CONCERNS.md` [HIGH] Tech Debt usunięty

**Concerns:**
- Brak `/code-review` — warto przejrzeć zmiany przed kolejnym wdrożeniem

**Blockers:** Brak

---
*Phase: 01-tech-debt, Plan: 02*
*Completed: 2026-03-12*