elixforms-web-pages/php/AGENTS.md

Agente PHP — Regole e Convenzioni

Questo file definisce le istruzioni specifiche, le regole e le convenzioni per lo sviluppo e la manutenzione delle pagine custom e dei componenti scritti in PHP 8.0+ nella cartella php/.

Gestione ID dei Form Element

Gli ID dei campi del form (es. nel Dropdown, Checkbox, TextField) creati tramite i metodi della classe ElixFormsComponent.php non devono mai essere cambiati o manipolati (ad es. aggiungendo suffissi come _dropdown), in quanto la piattaforma elixForms si basa sul loro nome ed ID esatto. In caso di conflitti di ID (ad esempio con input hidden), applicare il suffisso _hidden all'input hidden e mantenere l'ID originale senza suffissi sull'elemento principale visibile.

Convenzioni di Codice e Framework

1. PHP Puro (No Framework):

   • Utilizzare PHP 8.0+ con tipizzazione forte (declare(strict_types=1);).
   • Sfruttare le feature moderne come match expression, property promotion e typed properties.
   • Le pagine custom ereditano da ElixFormsComponent e sovrascrivono createCustomFormFields().

2. Namespace PSR-4:

   • Tutte le classi nella libreria comune usano il namespace ElixForms\Common;.
   • L'autoload PSR-4 è gestito da Composer tramite vendor/autoload.php.
   • Gli entry point includono require_once __DIR__ . '/../../vendor/autoload.php';; le classi comuni non devono includersi manualmente tra loro.

3. Rendering Server-Side:

   • I file PHP generano direttamente l'HTML server-side usando il design system Bootstrap Italia di UniPR.
   • Non c'è alcun passaggio di build o bundling JS.

4. Checkbox e Stato:

   • I checkbox inviano il proprio stato serializzato come stringa separata da virgole tramite un input hidden (gestito client-side da uno script JS automatico).

Deploy e Server Locale

• Dipendenze: dalla root del repository eseguire composer install --optimize-autoloader oppure composer-install.bat.
• Deploy: Eseguire composer install --no-dev --optimize-autoloader e caricare sul server sia php/ sia vendor/, mantenendole allo stesso livello.
• Server locale:
  • PHP CLI: Avviare il server dalla cartella php/ tramite php -S localhost:8080 (le pagine saranno raggiungibili su http://localhost:8080/<nome-pagina>/).
  • Docker: Dalla root del repository, eseguire:

    docker run --rm -p 8080:8080 -v "${PWD}:/app" -w /app/php php:8.2-cli php -S 0.0.0.0:8080
    

Skill PHP Correlate

Fai riferimento alle seguenti skill per maggiori dettagli operativi:

• elixforms-php-common-library: Classi, metodi factory e helper.
• elixforms-php-create-new-page: Guida passo passo per la creazione di nuove pagine.
• elixforms-php-project-architecture: Struttura delle cartelle, convenzioni e deploy.
• elixforms-css-design-system: Linee guida del design system UniPR.
• elixforms-custom-workflow-logic: Query parameters ed integrazione elixForms.