# Yii 1.1: struttura e funzioni chiave ## Scopo Questo documento serve a due tipi di lettori: - developer che devono capire dove intervenire senza perdere tempo nel framework; - AI agent che devono orientarsi nel codice Musa e scegliere il punto di modifica corretto. Il focus e' sui componenti Yii che Musa usa davvero: controller, helper HTML, sessioni, paginazione, grid, captcha ed error handling. ## Vista d'insieme In Musa il flusso tipico e': 1. Il controller prepara modello, data provider e configurazione di rendering. 2. La view compone la pagina usando widget Yii e helper `CHtml`. 3. Le parti interattive della griglia vengono coordinate da JS (`jquery.yiigridview.js`) e da `CGridView`. 4. Gli errori vengono gestiti da `CErrorHandler` e dalla view `framework/views/exception.php`. Pattern ricorrente in Musa: - logica di presentazione spinta nel controller tramite `RenderSettings`; - view relativamente sottile; - HTML generato con helper Yii, non con stringhe sparse; - grid guidate da `dataProvider`, `columns` e filtri AJAX. ## Struttura del framework rilevante | Area | Ruolo pratico | Quando usarla | |---|---|---| | `framework/base` | Fondazioni del framework: componenti, eventi, error handler, classi base application | Quando serve intercettare errori o costruire componenti applicativi riusabili | | `framework/web` | Strato web: request, response, controller, sessioni, paginazione, HTML helper, captcha | Quando il codice gira dentro una richiesta HTTP | | `framework/zii/widgets/grid` | Widget per tabelle interattive e colonne configurabili | Quando una lista deve essere filtrabile, ordinabile o azionabile | | `framework/views` | View di sistema, inclusa la pagina di eccezione | Quando si vuole cambiare il comportamento di fallback degli errori | ## Funzioni e responsabilita' ### `CPagination` File: [`framework/web/CPagination.php`](/var/www/html/dev/yii/framework/web/CPagination.php) Responsabilita': - calcolare pagina corrente, offset e limit; - costruire URL di paginazione; - applicare `LIMIT` e `OFFSET` ai criteri SQL. Funzioni chiave: - `getPageSize()` e `setPageSize()` per dimensionare il numero di righe per pagina; - `getPageCount()` per calcolare il totale delle pagine; - `getCurrentPage()` e `setCurrentPage()` per leggere o forzare la pagina corrente; - `createPageUrl()` per generare il link di pagina; - `applyLimit()` per applicare il limite al `CDbCriteria`; - `getOffset()` e `getLimit()` per integrazioni SQL. Uso in Musa: - la paginazione e' stata resa dipendente da una costante di configurazione del framework; - il comportamento e' stato centralizzato nel core Yii per evitare logiche duplicate nei config applicativi. ### `CCaptchaAction` File: [`framework/web/widgets/captcha/CCaptchaAction.php`](/var/www/html/dev/yii/framework/web/widgets/captcha/CCaptchaAction.php) Responsabilita': - generare l'immagine captcha; - salvare il codice di verifica in sessione; - validare l'input dell'utente. Funzioni chiave: - `run()` per servire l'immagine o il codice; - `getVerifyCode()` per recuperare o rigenerare il valore; - `validate()` per confrontare l'input con il codice atteso; - `renderImageGD()` e `renderImageImagick()` per il rendering grafico. Uso in Musa: - tipicamente collegato a form di login, recupero password e flussi sensibili; - la customizzazione Sophia corregge un caso in cui il captcha non veniva visualizzato correttamente. ### `CHtml` File: [`framework/web/helpers/CHtml.php`](/var/www/html/dev/yii/framework/web/helpers/CHtml.php) Responsabilita': - generare markup HTML sicuro e coerente; - costruire form controls legati ai model Yii; - produrre markup per link, bottoni, label, error summary. Funzioni chiave: - `link()` per link HTML con supporto a `submit`; - `submitButton()` per bottoni di submit; - `activeLabel()` e `activeLabelEx()` per etichette collegate al model; - `activeTextArea()` e `activeDropDownList()` per campi di form; - `errorSummary()` per mostrare gli errori di validazione; - `tag()` per generare tag generici. Uso in Musa: - il controller costruisce etichette, bottoni e widget direttamente tramite `CHtml`; - `errorSummary()` e' usato nei form classici e nelle schermate di manutenzione; - molte view mantengono il markup coerente con Bootstrap o con i widget booster. ### `CHttpSession` File: [`framework/web/CHttpSession.php`](/var/www/html/dev/yii/framework/web/CHttpSession.php) Responsabilita': - aprire, chiudere e mantenere la sessione HTTP; - esporre la sessione come oggetto accessibile via array; - gestire cookie, timeout, ID e garbage collection. Funzioni chiave: - `open()` e `close()` per il ciclo di vita della sessione; - `regenerateID()` per sicurezza e riallineamento della sessione; - `getTimeout()`, `setTimeout()`, `getCookieParams()`, `setCookieParams()` per la configurazione; - `ArrayAccess` (`offsetGet`, `offsetSet`, `offsetUnset`) per uso pratico come `Yii::app()->session[...]`. Uso in Musa: - e' il punto giusto quando un flusso dipende dalla persistenza lato browser; - la customizzazione Sophia aggiunge header di cache-control per migliorare il back del browser. ### `CErrorHandler` File: [`framework/base/CErrorHandler.php`](/var/www/html/dev/yii/framework/base/CErrorHandler.php) Responsabilita': - intercettare eccezioni e errori PHP; - scegliere se renderizzare la pagina di errore standard o la view di dettaglio; - costruire trace, source code snippet e header HTTP appropriati. Funzioni chiave: - `handle()` come entrypoint del gestore errori; - `handleException()` e `handleError()` per i due rami principali; - `renderException()` e `renderError()` per la fase di output; - `getViewFile()` per risolvere il file di view corretto; - `renderSourceCode()` per stampare il contesto della riga di errore. Uso in Musa: - utile per distinguere ambiente DEV e produzione; - la customizzazione Sophia permette il dettaglio completo quando `YII_DEBUG` e' attivo. ### `framework/views/exception.php` File: [`framework/views/exception.php`](/var/www/html/dev/yii/framework/views/exception.php) Responsabilita': - presentare all'utente la pagina di eccezione di default; - stampare tipo errore, messaggio, file, riga e stack trace. Uso in Musa: - e' stato esteso per loggare i dettagli dell'eccezione su file; - e' il punto di fallback visuale quando l'errore non viene gestito altrove. ### `CGridColumn` File: [`framework/zii/widgets/grid/CGridColumn.php`](/var/www/html/dev/yii/framework/zii/widgets/grid/CGridColumn.php) Responsabilita': - rappresentare una colonna della griglia; - renderizzare header, filter cell, data cell e footer; - incapsulare le regole di output di una singola colonna. Funzioni chiave: - `renderHeaderCell()` e `renderHeaderCellContent()`; - `renderFilterCell()` e `renderFilterCellContent()`; - `renderDataCell()` e `renderDataCellContent()`; - `renderFooterCell()` e `renderFooterCellContent()`; - `getDataCellContent()` per il contenuto della cella dati. Uso in Musa: - le colonne vengono configurate dal controller via array e oggetti `RenderSettings`; - il commit Sophia ha introdotto il concetto di `footer2` per supportare una seconda riga di footer. ### `CGridView` File: [`framework/zii/widgets/grid/CGridView.php`](/var/www/html/dev/yii/framework/zii/widgets/grid/CGridView.php) Responsabilita': - orchestrare il rendering della tabella, dei filtri, dei footer e del client script; - integrare `CGridColumn` e il `dataProvider`; - gestire l'output della griglia interattiva. Funzioni chiave: - `init()` e `initColumns()` per preparare il widget; - `registerClientScript()` per caricare il JS della griglia; - `renderItems()` per il rendering completo; - `renderTableHeader()`, `renderFilter()`, `renderTableBody()`, `renderTableFooter()`; - `getHasFooter()` e, nella customizzazione Sophia, `getHasFooter2()`. Uso in Musa: - la griglia e' spesso sostituita o estesa con widget personalizzati come `widgets.FrmGridView`; - il controller passa `dataProvider`, `columns`, `ajaxType`, `responsiveTable` e la logica di filtro. ## Pattern Musa da ricordare ### 1. RenderSettings come layer di presentazione Musa usa oggetti `RenderSettings` nel controller per descrivere come deve essere resa ogni sezione della UI. Esempio reale: - [`MusaCorsiIscrizioniController.php`](/var/www/html/dev/musa_app/protected/controllers/MusaCorsiIscrizioniController.php#L119) - [`MusaCorsiFormazioniDettController.php`](/var/www/html/dev/musa_app/protected/controllers/MusaCorsiFormazioniDettController.php#L238) Effetto pratico: - la stessa action puo' esporre rendering diverso per griglia, filtri, form e bottoni; - il controller conserva la logica di mapping, la view resta piu' semplice. ### 2. Grid view guidata dal controller In [`musaCorsiSessioni/admin.php`](/var/www/html/dev/musa_app/protected/views/musaCorsiSessioni/admin.php#L30) la view: - disegna i pulsanti gia' preparati dal controller; - abilita o disabilita i filtri inline in base a `RenderSettings`; - passa `dataProvider`, `columns` e opzioni al widget della griglia. ### 3. CHtml per markup coerente Le view e i controller Musa usano `CHtml` per: - bottoni di submit e link di ritorno; - label active legate ai model; - `errorSummary()` per i form; - tag generici per intestazioni e wrapper. ### 4. Estensioni widget Musa usa anche widget o helper custom quando il comportamento Yii standard non basta, per esempio: - `widgets.FrmGridView`; - `booster.widgets.TbSelect2`; - `booster.widgets.TbButtonColumn`. ## Come lavorare su questi file - Se il problema e' di impaginazione o limiti pagina, parti da `CPagination`. - Se riguarda input captcha o recupero password, parti da `CCaptchaAction`. - Se vuoi cambiare HTML di form o link, parti da `CHtml`. - Se il problema e' di sessione o browser back, parti da `CHttpSession`. - Se vuoi cambiare la gestione errori, guarda prima `CErrorHandler` e poi `framework/views/exception.php`. - Se il problema riguarda una tabella, la catena da seguire e' `CGridView` -> `CGridColumn` -> `jquery.yiigridview.js`.