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,258 @@
+---
+name: elixforms-php-create-new-page
+description: >
+  Guida step-by-step per creare una nuova pagina custom PHP nel progetto elixForms.
+  Copre la struttura dei file, l'importazione della libreria common,
+  le convenzioni di naming, e la configurazione per il deploy su Apache.
+  Attiva questa skill quando devi creare una nuova pagina PHP,
+  duplicare una pagina esistente, o scaffoldare un nuovo micro-progetto PHP nel monorepo.
+---
+
+# Creare una Nuova Pagina PHP elixForms Custom
+
+## Prerequisiti
+
+- PHP 8.0+ installato
+- Web server Apache configurato per servire la cartella `php/`
+
+## Step 1: Creare la Cartella della Pagina
+
+```powershell
+cd php
+mkdir <nome-pagina>
+```
+
+Il nome della cartella deve essere in **kebab-case** (es. `scelta-carriera`, `recupero-proposta`).
+
+## Step 2: Creare il File index.php
+
+Creare `php/<nome-pagina>/index.php`:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../common/ElixFormsComponent.php';
+
+use ElixForms\Common\ElixFormsComponent;
+
+/**
+ * Pagina custom "<NomePagina>" per elixForms.
+ */
+class NomePaginaPage extends ElixFormsComponent
+{
+    protected function createCustomFormFields(): string
+    {
+        $html = '';
+
+        // Aggiungi qui i campi del form usando i metodi factory:
+        // $html .= $this->createTextInput('COL0001', 'Campo Testo', true);
+        // $html .= $this->createDropdownInput('COL0002', 'Scelta', [...options], true);
+
+        return $html;
+    }
+
+    // Opzionale: contenuto extra prima del form
+    // protected function renderExtraContentPre(): string { return ''; }
+
+    // Opzionale: contenuto extra dopo il form
+    // protected function renderExtraContentPost(): string { return ''; }
+}
+
+// Entry point
+$page = new NomePaginaPage([
+    'moduleName' => 'Nome Modulo',
+    'cardTitle' => 'Titolo Pagina',
+    'cardDescription' => 'Descrizione della pagina.',
+    'userDisplayName' => '',         // Verrà popolato da elixForms
+    'headerTitle' => '',
+    'headerHeroImageSrc' => '',
+    'alertInfoTitle' => '',
+    'alertInfoMessage' => '',
+    'instructionsTitle' => '',
+    'instructionsMessage' => '',
+    'submitText' => 'INVIA',
+]);
+
+echo $page->render();
+```
+
+## Step 3: Definire i Campi Custom
+
+Sovrascrivere `createCustomFormFields()` con i campi necessari:
+
+```php
+protected function createCustomFormFields(): string
+{
+    $html = '';
+
+    // Dropdown
+    $html .= $this->createDropdownInput('COL0015', 'Scelta', [
+        ['value' => 0, 'label' => 'Opzione A'],
+        ['value' => 1, 'label' => 'Opzione B'],
+        ['value' => 2, 'label' => 'Opzione C'],
+    ], true);
+
+    // Testo
+    $html .= $this->createTextInput('COL0002', 'Nome', true);
+
+    // Textarea
+    $html .= $this->createTextAreaInput('COL0003', 'Note', false);
+
+    // Booleano (Sì/No)
+    $html .= $this->createBooleanInput('COL0004', 'Conferma', true);
+
+    // Radio
+    $html .= $this->createRadioInput('COL0005', 'Preferenza', [
+        ['value' => 1, 'label' => 'Prima scelta'],
+        ['value' => 2, 'label' => 'Seconda scelta'],
+    ], true);
+
+    // Checkbox
+    $html .= $this->createCheckboxInput('COL0006', 'Opzioni Multiple', [
+        ['value' => 1, 'label' => 'Opzione 1'],
+        ['value' => 2, 'label' => 'Opzione 2'],
+    ]);
+
+    // Numerico
+    $html .= $this->createNumberInput('COL0007', 'Quantità', true);
+
+    return $html;
+}
+```
+
+## Step 4: Opzionale — Aggiungere File di Configurazione
+
+Per pagine complesse, creare un file `config.json` nella cartella della pagina:
+
+```json
+{
+    "component": {
+        "moduleName": "Nome Modulo",
+        "cardTitle": "Titolo",
+        "cardDescription": "Descrizione",
+        "submitText": "CONFERMA"
+    },
+    "elixForms": {
+        "inputs": {
+            "codiceFiscale": "COL0009"
+        },
+        "outputs": {
+            "campo1": "COL0001",
+            "campo2": "COL0002"
+        }
+    }
+}
+```
+
+Caricare nel PHP:
+```php
+$config = json_decode(file_get_contents(__DIR__ . '/config.json'), true);
+
+$page = new NomePaginaPage($config['component']);
+echo $page->render();
+```
+
+## Step 4.1: Pagine Interattive e Chiamate Asincrone (AJAX)
+
+Se la pagina richiede autocompletamento o interattività (es. ricerca contratti):
+
+### 1. Proxy Script PHP Locale
+Per non esporre credenziali sensibili (API Key, Basic Auth) al client, creare sempre uno script proxy locale (es. `search-contratti.php`) che:
+- Riceve i dati dal client.
+- Esegue la chiamata protetta tramite `HttpClient`.
+- Valida con `json_decode` che la risposta sia JSON valido prima di inviarla.
+- Risponde con `500` e un JSON d'errore pulito in caso di eccezioni.
+
+### 2. Risoluzione Percorso URL in JavaScript
+Il server integrato PHP non esegue il redirect automatico per aggiungere lo slash alla fine delle cartelle. In JavaScript, calcolare sempre la base directory dinamica per supportare URL sia con che senza slash finale o con `index.php` esplicito:
+```javascript
+var baseDir = window.location.pathname;
+if (!baseDir.endsWith('/') && !baseDir.endsWith('.php')) {
+    baseDir += '/';
+}
+var lastSlash = baseDir.lastIndexOf('/');
+var dir = baseDir.substring(0, lastSlash + 1);
+
+var url = dir + 'search-contratti.php?term=' + encodeURIComponent(term);
+```
+
+### 3. Parsing Sicuro degli Errori HTTP (Fetch)
+Non eseguire direttamente `response.json()` su risposte d'errore (500/404) o non-JSON per evitare il crash `Unexpected token '<'`. Utilizzare la tecnica del `response.text()`:
+```javascript
+fetch(url)
+    .then(function(response) {
+        return response.text().then(function(text) {
+            var data = null;
+            try {
+                data = JSON.parse(text);
+            } catch (e) {
+                // Risposta non JSON (es. HTML d'errore del server)
+            }
+
+            if (!response.ok) {
+                var errMsg = (data && data.message) ? data.message :
+                             (data && data.error) ? data.error :
+                             ('Errore API: ' + response.status + ' ' + response.statusText);
+                throw new Error(errMsg);
+            }
+
+            if (data === null) {
+                throw new Error('Risposta del server non in formato JSON.');
+            }
+
+            return data;
+        });
+    })
+```
+## Step 5: Testing Locale
+
+Per testare le pagine localmente, è necessario avviare il server web dalla cartella radice `php/` (in modo che la cartella `common/` sia accessibile correttamente):
+
+### Opzione 1: PHP CLI Server locale
+```powershell
+cd php
+php -S localhost:8080
+```
+Aprire nel browser:
+```
+http://localhost:8080/<nome-pagina>/?RWE2_MODULE_ID=123&RWE2_REQUEST_ID=456&COL0002=test&COL0015=3
+```
+
+### Opzione 2: Docker
+Dalla root del repository, eseguire:
+```bash
+docker run --rm -p 8080:8080 -v "${PWD}/php:/app" -w /app php:8.2-cli php -S 0.0.0.0:8080
+```
+Aprire nel browser:
+```
+http://localhost:8080/<nome-pagina>/?RWE2_MODULE_ID=123&RWE2_REQUEST_ID=456&COL0002=test&COL0015=3
+```
+
+## Step 6: Deploy su Apache
+
+1. Caricare la cartella `php/` (o la singola cartella della pagina) sul server Apache
+2. Assicurarsi che Apache abbia `mod_php` o `php-fpm` configurato
+3. La pagina sarà accessibile via URL diretto (es. `https://server.example.com/php/nome-pagina/`)
+4. elixForms reindirizza l'utente alla pagina passando i parametri in query string
+
+## Struttura Finale
+
+```
+php/<nome-pagina>/
+├── index.php         ← Entry point e classe pagina
+└── config.json       ← Opzionale: configurazione separata
+```
+
+## Checklist Nuova Pagina PHP
+
+- [ ] Cartella creata in `php/<nome-pagina>/`
+- [ ] `index.php` con `declare(strict_types=1)` e namespace
+- [ ] Classe che estende `ElixFormsComponent`
+- [ ] `createCustomFormFields()` sovrascritta con i campi corretti
+- [ ] Proprietà di configurazione impostate correttamente
+- [ ] `require_once __DIR__ . '/../common/ElixFormsComponent.php'`
+- [ ] Test locale con `php -S` o Docker
+- [ ] Verifica che i campi form producano l'HTML corretto
+- [ ] Verifica che i parametri obbligatori vengano letti da `$_GET`