refactor solution to PHP through AI

2026-07-20 14:27:17 +02:00
parent a77f6f19cf
commit 151bc70775
21 changed files with 2563 additions and 41 deletions
@@ -0,0 +1,124 @@
+---
+name: elixforms-php-project-architecture
+description: >
+  Architettura e struttura della parte PHP del progetto elixForms Custom Pages.
+  Descrive la cartella php/, la libreria common condivisa, il pattern delle pagine,
+  le convenzioni di naming, e il deploy su Apache.
+  Attiva questa skill quando lavori sulla parte PHP del progetto,
+  crei nuove pagine PHP, modifichi l'architettura, o devi capire come è organizzato il codice PHP.
+---
+
+# Architettura PHP del Progetto elixForms Custom Pages
+
+## Panoramica
+
+La cartella `php/` contiene le custom page elixForms realizzate in **PHP 8.0+ puro** (nessun framework). Ogni pagina è un file PHP autonomo che include la libreria `common/` e produce HTML server-side con **Bootstrap Italia**.
+
+Questa struttura è l'equivalente PHP del monorepo React in `react/`.
+
+## Struttura del Workspace
+
+```
+elixforms-custom-pages/
+├── react/                        ← Custom pages React (esistente)
+└── php/                          ← Custom pages PHP
+    ├── AGENTS.md                 ← Regole dell'agente PHP
+    ├── common/                   ← Libreria condivisa PHP
+    │   ├── ElixFormsComponent.php    ← Classe base astratta
+    │   ├── ElixFormsElement.php      ← Wrapper layout label+input
+    │   └── QueryParamHelper.php      ← Utility query string
+    └── scelta-carriera/          ← Esempio di pagina custom
+        └── index.php                 ← Entry point (classe + rendering)
+```
+
+## Pattern Architetturale: Singolo File PHP per Pagina
+
+Ogni pagina (es. `scelta-carriera/`) è un file PHP autonomo che:
+
+1. **Include la libreria `common/`** tramite `require_once`
+2. **Definisce una classe** che estende `ElixFormsComponent`
+3. **Sovrascrive `createCustomFormFields()`** per i campi specifici
+4. **Istanzia e renderizza** la pagina con `echo $page->render()`
+5. **Genera HTML completo** (dalla `<!DOCTYPE html>` al `</html>`)
+6. **Non richiede build** — servito direttamente da Apache
+
+## Namespace e Autoloading
+
+Il progetto usa **namespace PSR-4**:
+
+```php
+namespace ElixForms\Common;  // Per le classi in common/
+```
+
+L'autoloading è gestito manualmente con `require_once` (non Composer):
+
+```php
+require_once __DIR__ . '/../common/ElixFormsComponent.php';
+// ElixFormsComponent.php include internamente:
+//   - QueryParamHelper.php
+//   - ElixFormsElement.php
+```
+
+## Requisiti PHP
+
+- **Versione minima**: PHP 8.0+
+- **Funzionalità usate**:
+  - `declare(strict_types=1)` — strict typing
+  - Typed properties (`protected array $properties`)
+  - `match` expression (nel renderField)
+  - Named arguments
+  - Union types (`int|null`, `string|null`)
+  - Arrow functions (`fn() =>`)
+
+## CSS Strategy
+
+Le pagine PHP usano `<link>` tags per caricare i CSS (non bundle JS):
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Titillium+Web:wght@300;400;600;700&display=swap">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-italia@2.18.2/dist/css/bootstrap-italia.min.css">
+<link rel="stylesheet" href="https://console-unipr.elixforms.it/rwe2/css/design-bs/util.css">
+<link rel="stylesheet" href="https://console-unipr.elixforms.it/rwe2/css/themes/blu-italia.css">
+```
+
+> **Nota**: Stessi CSS del progetto React, ma caricati via `<link>` anziché `@import url()` nel JS bundle.
+
+## Integrazione con elixForms
+
+Identica alla versione React:
+
+1. **Query parameters**: Parametri obbligatori passati nell'URL da elixForms
+2. **Form POST**: Il form fa submit a `https://procedure.unipr.it/rwe2/ComeBackToElixAndSave`
+3. **Hidden inputs**: I parametri query vengono inseriti come campi hidden nel form
+4. **Encoding**: `accept-charset="ISO-8859-1"` per compatibilità con il backend
+
+## Convenzioni di Naming
+
+- **Cartelle pagina**: kebab-case (es. `scelta-carriera`)
+- **File entry point**: sempre `index.php`
+- **Classi PHP**: PascalCase con suffisso `Page` (es. `SceltaCarrieraPage`)
+- **Namespace**: `ElixForms\Common` per la libreria condivisa
+- **Configurazione**: opzionale `config.json` nella cartella della pagina
+
+## Differenze con il Progetto React
+
+| Aspetto | React (`react/`) | PHP (`php/`) |
+|---|---|---|
+| **Linguaggio** | TypeScript/JSX | PHP 8.0+ |
+| **Rendering** | Client-side | Server-side |
+| **Build tool** | Vite (single bundle JS) | Nessuno (file serviti direttamente) |
+| **Dipendenze** | npm (React, Vite, plugin) | Nessuna (PHP built-in) |
+| **CSS loading** | `@import url()` + CSS injection plugin | `<link>` tags |
+| **State management** | React state (`this.setState`) | Stateless (`$_GET`) |
+| **Deploy** | Upload del bundle `.js` | Upload dei file `.php` |
+| **Dev server** | `npm run dev` (Vite HMR) | `php -S` / Docker |
+
+## Deploy su Apache
+
+1. Caricare la cartella `php/` sul server Apache
+2. Configurazione Apache minima:
+   - `mod_php` o `php-fpm` abilitato
+   - `DirectoryIndex index.php` (default Apache)
+3. La pagina è accessibile via URL: `https://server/php/nome-pagina/`
+4. elixForms reindirizza l'utente alla pagina passando i parametri via query string