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

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

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

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

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

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

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

Skill elixforms-php-create-new-page:

• Guida step-by-step per creare una nuova pagina PHP custom

[NEW] 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

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

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