elixforms-web-pages/.artifacts/php_implementation_plan.md

# Port elixForms Custom Pages in PHP + Creazione Agenti React e PHP

## Obiettivo

Creare una versione PHP della libreria `common/` e una pagina di esempio `scelta-carriera`, replicando la stessa architettura e logica attualmente implementata in React/TypeScript. Inoltre, creare due agenti specializzati ("React" e "PHP") e le relative skill per il mondo PHP.

## Panoramica dell'architettura React attuale

```mermaid
graph TD
    A["ElixFormsComponentAbstract.tsx<br/>(classe astratta)"] --> B["SceltaCarrieraComponent.tsx<br/>(override createCustomFormFields)"]
    A --> C["RecuperoPropostaCctDaContrattiComponent.tsx<br/>(override createCustomFormFields + autocomplete)"]
    A --> D["ElixFormsElement.tsx<br/>(layout label+input)"]
    A --> E["QueryParamHelper.tsx<br/>(lettura query params)"]
    A --> F["ElixFormsTypes.tsx<br/>(tipi opzioni)"]
    B --> G["App.jsx + main.jsx<br/>(entry point pagina)"]
    C --> H["App.jsx + main.jsx<br/>(entry point pagina)"]
```

## Differenze chiave React → PHP

| Aspetto | React | PHP |
|---|---|---|
| **Rendering** | Client-side (JSX → DOM) | Server-side (PHP → HTML) |
| **State management** | `this.state` + `this.setState()` | Valori da `$_GET` / `$_POST` (stateless) |
| **Form field factory** | Callback con oggetto factory | Metodi della classe base chiamati direttamente |
| **Build** | Vite → singolo bundle JS | Nessuna build — file PHP serviti direttamente |
| **CSS** | Iniettati nel JS via plugin | `<link>` tag nell'HTML |
| **Bootstrap Italia** | Classi HTML nel JSX | Stesse classi HTML nel template PHP |

> [!IMPORTANT]
> In PHP non serve un build tool. Ogni pagina è un singolo file PHP (o un set di file PHP) che include la libreria common e produce HTML direttamente.

## Proposed Changes

### 1. Libreria Common PHP

#### [NEW] [ElixFormsComponent.php](file:///c:/__Git/_UniPR/elixforms-custom-pages/php/common/ElixFormsComponent.php)

Classe astratta PHP che replica `ElixFormsComponentAbstract.tsx`:

- **Proprietà**: `$properties` (array associativo equivalente a `IElixFormsComponentProperties`)
- **Metodi factory**: `createTextInput()`, `createTextAreaInput()`, `createNumberInput()`, `createBooleanInput()`, `createRadioInput()`, `createCheckboxInput()`, `createDropdownInput()`, `createHiddenInput()`
- **Metodi di layout**: `render()` che genera l'intera pagina HTML (header Bootstrap Italia, breadcrumb, card, form, footer)
- **Metodi estensibili**: `createCustomFormFields()`, `renderExtraContentPre()`, `renderExtraContentPost()` — da sovrascrivere nelle pagine figlie
- **Validazione**: Controllo parametri obbligatori (`mandatoryFormFieldNames`) dalla query string
- I valori dei campi vengono pre-popolati da `$_GET` (equivalente di `QueryParamHelper`)

#### [NEW] [ElixFormsElement.php](file:///c:/__Git/_UniPR/elixforms-custom-pages/php/common/ElixFormsElement.php)

Classe wrapper per layout label+input (replica `ElixFormsElement.tsx`):
- Genera il layout a due colonne Bootstrap (`row`, `col-12 col-md-4`, `col-12 col-md-8`)

#### [NEW] [QueryParamHelper.php](file:///c:/__Git/_UniPR/elixforms-custom-pages/php/common/QueryParamHelper.php)

Classe statica utility (replica `QueryParamHelper.tsx`):
- `getCheckedFromQuery($paramName)` → `int[]`
- `getOptionFromQuery($paramName)` → `?int`
- `getBooleanFromQuery($paramName)` → `?bool`
- `getDecodedTextFromQuery($paramName)` → `?string`

---

### 2. Pagina di Esempio

#### [NEW] [index.php](file:///c:/__Git/_UniPR/elixforms-custom-pages/php/scelta-carriera/index.php)

Pagina di esempio che replica `scelta-carriera` React:
- Estende `ElixFormsComponent` sovrascrivendo `createCustomFormFields()`
- Definisce dropdown, text input, textarea, boolean, radio, checkbox
- Include il CSS di Bootstrap Italia e del design system UniPR via `<link>`

---

### 3. Skill PHP (nuove)

#### [NEW] [SKILL.md](file:///c:/__Git/_UniPR/elixforms-custom-pages/.agents/skills/php-common-library/SKILL.md)

Skill `elixforms-php-common-library`:
- Documenta la libreria PHP common, i metodi della classe base, le proprietà, e il pattern di estensione

#### [NEW] [SKILL.md](file:///c:/__Git/_UniPR/elixforms-custom-pages/.agents/skills/php-create-new-page/SKILL.md)

Skill `elixforms-php-create-new-page`:
- Guida step-by-step per creare una nuova pagina PHP custom

#### [NEW] [SKILL.md](file:///c:/__Git/_UniPR/elixforms-custom-pages/.agents/skills/php-project-architecture/SKILL.md)

Skill `elixforms-php-project-architecture`:
- Descrive la struttura della cartella `php/` e le convenzioni del monorepo PHP

---

### 4. Agenti (AGENTS.md personalizzati)

> [!IMPORTANT]
> Gli "agenti" nella struttura Gemini vengono realizzati creando file `AGENTS.md` nelle rispettive cartelle. In questo modo ogni agente "scopre" automaticamente le regole specifiche per il proprio contesto.

#### [NEW] [AGENTS.md](file:///c:/__Git/_UniPR/elixforms-custom-pages/react/AGENTS.md)

Agente **"React"** — regole specifiche per il framework React:
- Usa React + TypeScript class components per la libreria common
- Usa Vite per il bundling single-file
- Bootstrap Italia con classi HTML nel JSX
- Regola sugli ID dei form fields (ripresa dal root)
- Riferimenti alle skill React esistenti

#### [NEW] [AGENTS.md](file:///c:/__Git/_UniPR/elixforms-custom-pages/php/AGENTS.md)

Agente **"PHP"** — regole specifiche per PHP:
- PHP puro, nessun framework
- Bootstrap Italia con classi HTML nei template PHP
- Pattern ereditarietà con classe base
- Stessa regola sugli ID dei form fields
- Riferimenti alle skill PHP

---

## Struttura finale del workspace

```
elixforms-custom-pages/
├── .agents/
│   ├── AGENTS.md                          ← Regole globali (invariate)
│   └── skills/
│       ├── common-library/                ← Skill React (esistente)
│       ├── create-new-page/               ← Skill React (esistente)
│       ├── css-design-system/             ← Skill condivisa (esistente)
│       ├── custom-workflow-logic/         ← Skill condivisa (esistente)
│       ├── dev-workflow/                  ← Skill React (esistente)
│       ├── project-architecture/          ← Skill React (esistente)
│       ├── typescript-react-conventions/  ← Skill React (esistente)
│       ├── vite-build-config/             ← Skill React (esistente)
│       ├── php-common-library/            ← [NEW] Skill PHP
│       ├── php-create-new-page/           ← [NEW] Skill PHP
│       └── php-project-architecture/      ← [NEW] Skill PHP
├── react/
│   ├── AGENTS.md                          ← [NEW] Agente React
│   ├── common/
│   ├── scelta-carriera/
│   └── recupero-proposta-cct-da-contratti/
└── php/
    ├── AGENTS.md                          ← [NEW] Agente PHP
    ├── common/
    │   ├── ElixFormsComponent.php          ← [NEW]
    │   ├── ElixFormsElement.php            ← [NEW]
    │   └── QueryParamHelper.php            ← [NEW]
    └── scelta-carriera/
        └── index.php                       ← [NEW]
```

## Open Questions

> [!IMPORTANT]
> **Versione PHP**: quale versione minima di PHP devo usare? (es. PHP 7.4+ o PHP 8.0+ con typed properties, union types, match expression, ecc.)

> [!IMPORTANT]
> **Namespace PHP**: vuoi usare i namespace PSR-4 (es. `namespace ElixForms\Common;`) o preferisci un approccio più semplice con `require_once`?

> [!IMPORTANT]
> **Deploy**: le pagine PHP verranno servite da un web server Apache/Nginx? O dovranno essere incluse/embedded in un sistema esistente?

## Verification Plan

### Manual Verification

- Verificare che la pagina PHP `scelta-carriera/index.php` generi HTML valido con la stessa struttura del corrispettivo React
- Verificare che i campi del form (dropdown, text, textarea, boolean, radio, checkbox) siano tutti presenti e funzionanti
- Verificare che i parametri obbligatori vengano correttamente letti dalla query string
- Verificare che il form faccia POST a `https://procedure.unipr.it/rwe2/ComeBackToElixAndSave` con encoding `ISO-8859-1`
- Verificare che le skill e gli agenti siano correttamente scoperti da Gemini