125 lines
5.2 KiB
Markdown
125 lines
5.2 KiB
Markdown
---
|
|
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/
|
|
├── composer.json ← Configurazione Composer e autoload PSR-4
|
|
├── vendor/ ← Autoloader generato (non versionato)
|
|
├── 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. **Carica l'autoloader Composer** tramite `vendor/autoload.php`
|
|
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 PSR-4 è gestito da Composer:
|
|
|
|
```php
|
|
require_once __DIR__ . '/../../vendor/autoload.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) | Composer (autoload PSR-4) |
|
|
| **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. Eseguire `composer install --no-dev --optimize-autoloader` dalla root del repository
|
|
2. Caricare sul server le cartelle `php/` e `vendor/`, mantenendole allo stesso livello
|
|
3. Configurazione Apache minima:
|
|
- `mod_php` o `php-fpm` abilitato
|
|
- `DirectoryIndex index.php` (default Apache)
|
|
4. La pagina è accessibile via URL: `https://server/php/nome-pagina/`
|
|
5. elixForms reindirizza l'utente alla pagina passando i parametri via query string
|