Difference between revisions of "Man Tecnico:Analisi gestione allegati"

From CDG Wiki
Jump to navigation Jump to search
 
Line 235: Line 235:
 
=== Modifiche al file rendicontazione.php ===
 
=== Modifiche al file rendicontazione.php ===
 
Le modifiche al file rendicontazione.php hanno previsto la creazione di un oggetto ObiettivoRendicontazioneAllegato, dal quale viene inizializzata una variabile di nome $allegati contenente il risultato della chiamata alla funzione getAll sull’oggetto appena creato.
 
Le modifiche al file rendicontazione.php hanno previsto la creazione di un oggetto ObiettivoRendicontazioneAllegato, dal quale viene inizializzata una variabile di nome $allegati contenente il risultato della chiamata alla funzione getAll sull’oggetto appena creato.
Successivamente vengono definiti i permessi sugli allegati tramite un un array con indici ‘user_id’ e ‘allegati_permission’, il primo contenente la matricola utente selezionato, l’altro contenente le voci ‘canDownload’ e ‘canDelete’, le quali a loro volta vengono inizializzare con i nomi dei file md5 che l’utente selezionato può modificare.
+
Successivamente vengono definiti i permessi sugli allegati tramite un array con indici ‘user_id’ e ‘allegati_permission’, il primo contenente la matricola utente selezionato, l’altro contenente le voci ‘canDownload’ e ‘canDelete’, le quali a loro volta vengono inizializzare con i nomi dei file md5 che l’utente selezionato può modificare.
 
A questo punto i dati vengono codificati per poi essere salvati all’interno di un cookie temporaneo.
 
A questo punto i dati vengono codificati per poi essere salvati all’interno di un cookie temporaneo.
 
È stato poi introdotto del codice html per la creazione di un modulo di gestione dei file.
 
È stato poi introdotto del codice html per la creazione di un modulo di gestione dei file.
Line 242: Line 242:
 
Successivamente si controlla che l’utente abbia i privilegi di “edit_responsabile” e in caso affermativo, se non è periodo di rendicontazione, si proibisce l’eliminazione anche a quegli utenti che potrebbero operarla, mostrando un carattere ‘-’ al posto del pulsante di eliminazione.
 
Successivamente si controlla che l’utente abbia i privilegi di “edit_responsabile” e in caso affermativo, se non è periodo di rendicontazione, si proibisce l’eliminazione anche a quegli utenti che potrebbero operarla, mostrando un carattere ‘-’ al posto del pulsante di eliminazione.
 
Se invece è periodo di rendicontazione, il tasto elimina viene mostrato (per gli utenti “edit-responsaibile”) e inoltre viene abilitata una form per il caricamento dei file e viene richiamata la funzione getUploadForm, in modo da aggiornare automaticamente la lista dei file presenti una volta aggiunto un nuovo file.
 
Se invece è periodo di rendicontazione, il tasto elimina viene mostrato (per gli utenti “edit-responsaibile”) e inoltre viene abilitata una form per il caricamento dei file e viene richiamata la funzione getUploadForm, in modo da aggiornare automaticamente la lista dei file presenti una volta aggiunto un nuovo file.
 
  
 
=== upload.php ===
 
=== upload.php ===

Latest revision as of 14:34, 28 September 2020

La Gestione degli allegati fornisce una interfaccia semplice ed intuitiva che permette di caricare allegati ed effettuare il download degli stessi.

Analisi dei requisiti

All'interno del processo di budget, in determinati contesti vi è la necessità di poter gestire file allegati. Piuttosto che lo sviluppo di una soluzione ad-hoc per ogni funzionalità che necessita di poter eseguire l’upload / il download di file, risulta utile in termini di tempi di sviluppo, di manutenibilità e scalabilità della soluzione nonché di uniformità dell’interfaccia, prevedere un sistema centralizzato per la gestione dei file allegati.

La gestione degli allegati dovrà garantire la possibilità per gli utenti di eseguire l’upload di file all’interno dell’applicativo con tutte le limitazioni previste dall’amministratore circa la tipologia di file e la loro dimensione massima.

Fornirà inoltre un’helper per poter generare velocemente l’interfaccia per la visualizzazione dei file disponibili per il download in forma tabellare, pronti per essere scaricati oppure eliminati: le operazioni di caricamento ed eliminazione sono sottoposte a policy di sicurezza che impediscono accessi non desiderati alle risorse in questione in quanto verificano, ogni volta, la corretta configurazione dei permessi della risorsa umana che esegue l'operazione. A questo proposito risulta necessario implementare un sistema che permetta alle funzionalità specifiche di gestire le policy di sicurezza per le operazioni sui file in maniera indipendente e autonoma ma che sfrutti il meccanismo di accesso definito con la gestione centralizzata, in modo di impedire accessi non autorizzati ai file o ad operazione su di essi.

Descrizione delle funzionalità

Valutando quanto considerato nell'analisi dei requisiti, si definiscono le funzionalità che il modulo di Gestione degli allegati dovrà fornire.

Verrà prevista, all'interno della pagina, una sezione in cui l'utente potrà effettuare l'upload di documenti ed una sezione in cui l'utente potrà effettuare il download e l'eliminazione degli allegati stessi.

L'upload dei file avviene tramite una form in cui l'utente potrà selezionare il file dal proprio PC: l'effettivo caricamento del file nell'applicativo dipende dall'estensione del file, dalla sua dimensione e dal superamento delle policy di sicurezza.

I file caricati saranno elencati in una tabella che si aggiorna dinamicamente ogni qual volta l'utente carichi od elimini un file; da questa tabella è possibile scaricare una copia del file. Le operazioni di download e di eliminazione sono soggette a policy di sicurezza, messa in atto per garantire un accesso sicuro ai documenti.

Scelte implementative

Non sono state create pagine particolare o moduli, bensì sono state aggiunte due classi al core dell'applicativo: tali classi consentono di creare, ove necessario includere la funzionalità di gestione degli allegati, un oggetto che andrà a renderizzazione il form di upload degli allegati e la tabella di consultazione degli allegati disponibili.

I documenti caricati saranno salvati sul file system, nella directory uploads/tracciati_anno, suddivisi per anno di caricamento. I documenti caricati saranno salvati anche in una tabella ad hoc del database, contenente oltre al nome del file ed il path dello stesso, usa serie di informazioni utili per controllare le policy di sicurezza e facilitare il download.

Sarà predisposta anche una tabella intermedia che collegherà il processo aziendale (es: rendicontazione degli obiettivi) in cui è stato inserito il modulo di gestione degli allegati con la tabella di cui sopra.

Modello ER

allegato

Campo Tipo Obbligatorio Note
ID Int Si (PK) Identificativo dell’allegato. Autoincrementale.
filename_md5 Varchar Si Nome del file codificato in md5.
filename_plain Varchar Si Nome del file.
file_path Varchar Si Percorso fisico in cui risiede il file.
mime_type Varhcar Si Mime type del file.
content_lenght Varchar Si Dimensione del file.
user_id Varchar Si Matricola dell’utente selezionato, ID della tabella cm_users.
createdAt Datetime No Data e ora di creazione.
updatedAt Datetime No Data e ora di modifica.
deletedAt Datetime No Data e ora di eliminazione.

Modello Classi

Allegato.php

Rappresentazione della tabella allegato del database; contiene le funzionalità per eliminare e scaricare un allegato

AllegatoHelper.php

Classe di supporto per migliorare la gestione degli allegati in cui sono implementate le funzionalità per caricare file, per verificare le policy di sicurezza, per generare dinamicamente la tabella riepilogativa dei file

Classe Allegato

La classe Allegato contiene il codice per la creazione di un oggetto allegato che avviene all’interno del costruttore mediante il passaggio dell’id. Gli attributi di questa classe comprendono tutti i campi della tabella “allegato” e ne definiscono di nuovi quali:

   1. $table_name, contenente il nome della tabella.
   2. $allowed_mime_type, contenente un array di mime type accettati dal sistema.
   3. $max_content_lenght, contenente la dimensione massima del file espressa in byte.

Per una descrizione più precisa dei mime type accettati e del valore di $max_content_lenght, la definizione di tali parametri è realizzata nel file config.php.


__construct($id = null)

$id: Identificativo dell’allegato. Dopo aver verificato che l’id non è nullo, viene eseguita una query per il caricamento dell’allegato identificato dall’id passato come parametro. Se il risultato della query contiene un valore, allora viene effettivamente costruito l’oggetto recuperando i valori dall’istanza del database restituita dalla query.

Messaggi di errore:

Nel caso in cui il risultato della query sia un insieme vuoto, il sistema lancia una exception recante il messaggio: "Impossibile creare l'oggetto Allegato con ID = ".$id


getAll($filters = array())

$filters: Array di stringhe contenenti delle condizioni per la ricerca tramite query. Il metodo getAll restituisce alla funzione chiamante un oggetto di nome $file, istanza della classe Allegato. L’allegato da restituire viene selezionato tramite una query che ha come clausola “WHERE” la lista di condizioni definita dall’array $filters.


save($array_row)

$array_row: Array contenente i valori i campi di un’istanza di allegato. Dopo aver verificato che l’array $array_row non sia vuoto, tramite una query inserisce nel database i valori contenuti all’interno di $array_row[‘Allegato’]. Successivamente, viene inizializzata la variabile $return con il valore restituito in seguito all’esecuzione della query. Se questo valore è pari a “1”, allora l’allegato è stato correttamente salvato.

Messaggi di errore:

Se $array_row risulta vuoto, oppure se il valore restituito dalla chiamata della query è diverso da “1”, il sistema lancia il seguente messaggio di errore: “Allegato non salvato nel database”


delete($filename_md5)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. Il metodo delete si occupa di controllare se il parametro passato è una stringa o meno, nel caso affermativo viene creata una variabile di nome $allegato alla quale viene attribuito il valore restituito dalla chiamata alla funzione getAll, passando come parametro il contenuto della variabile $filename_md5. Successivamente avviene una eliminazione logica dell’istanza della tabella “allegato” il cui id è uguale all’attributo id dell’oggetto $allegato. Successivamente viene restituito come valore il risultato (“1” se l’operazione è andata a buon fine, false altrimenti).

Classe ObiettivoRendicontazioneAllegato

La classe ObiettivoRendicontazioneAllegato estende la classe Allegato e contiene il seguente attributo:

   1. $bridge_table_name: stringa di testo contenente il nome della tabella obiettivo_rendicontazione_allegato.

Il cotruttore della classe viene ereditato dalla classe Allegato.


getAll($filters = array())

$filters: Array di stringhe contenenti delle condizioni per la ricerca tramite query. Il metodo getAll controlla se l’array $filters è vuoto o meno, e nel caso non lo sia genera una condizione, che viene poi utilizzata all’interno della clausola “WHERE” della query che reperisce le istanze della tabella “obiettivi_rendicontazione_allegato”. Successivamente viene inizializzata una variabile di nome $allegato_ids tramite il valore del campo “allegato_id”. Il valore resitutito è dato dalla chiamata al metodo getRelatedAllegato passando come parametro la variabile $allegato_ids.


getRelatedAllegato($allegato_ids)

$allegato_ids: Array contenente gli id degli allegati. Il metodo prevede un controllo sulla variabile $allegato_ids, che verifica che non sia un array vuoto. In tal caso viene dichiarata una variabile di nome $allegato come una stringa contenente tutti gli elementi dell’array $allegato_ids separati da una virgola. Successivamente, se la variabile $allegato è diversa da una stringa vuota si procede con l’esecuzione di una query che restituisce tutti quelle righe della tabella allegato il cui ID è presente nella stringa $allegato. Successivamente viene creato un oggetto di nome $file di tipo ObiettivoRendicontazioneAllegato, i cui attributi assumono il valore dei risultati della query. Viene infine creato l’array $file_allegato (che assume il valore dell’oggetto $file) e viene poi restituito.


save($array_row)

$array_row: Array contenente i valori i campi di un’istanza di allegato. Dopo aver controllato che l’array $array_row non sia vuoto, si procede con un altro controllo sulla dimensione dell’allegato. Se questo è minore o uguale alla massima dimensione consentita si controlla che il mime_type del file da caricare sia presente nella lista dei mime_type consentiti. Se tutti questi controlli vanno a buon fine si procede con la creazione di una nuova riga nella tabella “allegato”, prendendo i valori dei campi da $array_row[‘Allegato’]. Successivamente viene invocata la funzione getAll della classe Allegato, passando come parametro il nome del file. Il valore restituito da tale chiamata viene assunto dalla variabile $allegato. La funzione procede con la creazione della corrispondente riga della tabella “obiettivo_rendicontazione_allegato”, e il risultato dell’esecuzione di tale query viene salvato nella variabile $return_query. Se l’esecuzione della query è andata a buon fine, la funzione restituisce la variabile $allegato.

Messaggi di errore
   1. Se il risultato della query di inserimento dell’obbiettivo_rendicontazione_allegato è diverso da “1”, il sistema mostra il messaggio “allegato non salvato”.
   2. Se il mime_type non risulta presente nella lista di mime_type accettati, il sistema informa l’utente con il messaggio: “il tipo di file (mimetype) non è valido”.
   3. Se la dimensione del file è maggiore alla dimensione massima consentita, il sistema informa l’utente con il messaggio: "file troppo grande, supera ".$this→max_content_lenght."bytes".


delete($filename_md5)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. Il metodo delete cerca nel database il file il cui campo filename_md5 è uguale alla variabile $filename_md5 ed esegue una funzione di update volta all’eliminazione logica del file. Il valore restituito è dato dal risultato dell’operazione di modifica.


Classe AllegatoHelper

Attributi:

   1. $error_operazione_vietata: Stringa di errore.
   2. $error_md5: Stringa di errore.

downloadFile($filename_md5)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. Dopo aver controllato che la variabile $filename_md5 contenga effettivamente una stringa md5 valida, la funzione controlla che l’utente abbia i permessi di download del file e in caso affermativo la funzione restituisce il risultato della chiamata alla funzione renderFile($filename_md5) applicato all’oggetto AllegatoHelper. Tale funzione restituisce un oggetto contenente la riga della tabella “allegato” il cui campo filename_md5 è uguale alla variabile $filename_md5.

Messaggi di errore
   1. Nel caso in cui l’utente non abbia i permessi viene stampata la stringa $error_operazione_vietata e la funzione restituisce false.
   2. Nel caso in cui la stringa passata come parametro non sia in formato md5, viene stampata la stringa $error_md5 e la funzione restituisce false.


deleteFile($filename_md5)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. Effettuati i controlli sulla validità della stringa md5 e sui permessi di cancellazione dell’utente, viene invocata la funzione delete della classe Allegato passando come parametro la variabile $filename_md5.

Messaggi di errore
   1. Nel caso in cui l’utente non abbia i permessi viene stampata la stringa $error_operazione_vietata e la funzione restituisce false.
   2. Nel caso in cui la stringa passata come parametro non sia in formato md5, viene stampata la stringa $error_md5 e la funzione restituisce false.


isValidMd5($md5 = )

$md5: Stringa contenente il testo su cui eseguire il controllo. La funzione isValidMd5 controlla se la stringa passata come parametro è effettivamente in formato md5, in tal caso restituisce true, altrimenti false. Tramite la funzione pregmatch si verifica che la stringa contenga solo caratteri da “a” a “f” e numeri da “0” a “9”, e che questa sia lunga 32 caratteri.


canDownload($filename_md5)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. La funzione canDownload controlla se l’utente attualmente selezionato ha matricola uguale allo user_id presente nei cookie. Se tale condizione è verificata, si cicla sui permessi dell’utente e si valuta se all’interno dei permessi di download, c’è un file md5 il cui nome è uguale a $filename_md5. Se il file viene trovato allora la funzione restituisce true, altrimenti false.


canDelete($filename_md5)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. La funzione canDelete controlla se l’utente attualmente selezionato ha matricola uguale allo user_id presente nei cookie. Se tale condizione è verificata, si cicla sui permessi dell’utente e si valuta se all’interno dei permessi di cancellazione, c’è un file md5 il cui nome è uguale a $filename_md5. Se il file viene trovato allora la funzione restituis ce true, altrimenti false.


getDownloadLink($filename_md5, $filename_plain)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. $filename_plain: Stringa di testo contenente il nome di un file. Restituisce il codice html per la creazione del link di download. Viene utilizzata la costante DIRECTORY_SEPARATOR per ovviare alle differenze tra diversi sistemi operativi.


getDeleteLink($filename_md5, $filename_plain)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. $filename_plain: Stringa di testo contenente il nome di un file. Restituisce il codice html per la creazione del link di delete. Viene utilizzata la costante DIRECTORY_SEPARATOR per ovviare alle differenze tra diversi sistemi operativi.


getUploadForm($class, $allegato_data = array())

$class: Classe. $allegato_data: Array contenente i dati dell’allegato. La funzione getUploadForm è utilizzata per l’aggiornamento della sezione della pagina contenente i file caricati per una rendicontazione. Per ogni elemento dell’array $allegato_data, viene creato un campo di testo nascosto il cui nome è dato dalla concatenazione tra la stringa “field_” e l’indice dell’elemento nell’array, e il contenuto informativo è dato dal valore dell’elemento. Successivamente vengono reperiti tutti i file presenti nelle cartella di upload, inclusi quelli appena caricati (o appena eliminati) tramite jQuery AJAX.


uploadFile()

Funzione richiamata durante l’upload di un file, vengono reperiti in POST l’anno di riferimento e la classe, successivamente viene definito il path della cartella di upload e viene definito un nuovo nome per il file realizzato concatenando il risultato della funzione time() con il vecchio nome del file. Viene definito poi un array di nome $allegato, rappresentante un allegato e specificandone il nome in chiaro, il percorso (upload directory), il mime type e la dimensione. Successivamente la funzione cicla sull’array $_POST per cercare se esistono elementi di essi la cui chiave contiene la stringa ‘field_’ all’inizio del nome, e nel caso se ne trovasse uno, la stringa ‘field_’ viene rimpiazzata con una stringa vuota. Successivamente viene preso il file caricato nella cartella temporanea e spostato nella corretta cartella di upload.

Messaggi di errore
   1. Qualora non si riuscisse a spostare il file, il sistema risponderebbe con una stringa di errore: “impossibile muovere il file sul server”.


renderFile($filename_md5)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. Restituisce l’oggetto allegato il cui attributo ‘filename_md5’ combacia con $filename_md5.


encodePermissions($permissions_array)

$permissions_array: Array da codificare. L’array passato come parametro viene codificato in formato json, successivamente viene codificato in base64 e viene operato uno shift delle lettere della stringa così ottenuta.


decodePermissions($cookie_text)

$cookie_text: Testo da decodificare. Il testo da decodificare subisce l’operazione inversa di quanto descritto per la funzione encodePermissions.


updateFileGrant($filename_md5)

$filename_md5: Stringa di testo contenente il nome di un file codificato in md5. Viene eseguito l’update dei permessi sul cookie per uno specifico file, discriminato dal parametro $filename_md5.


Modifiche al file rendicontazione.php

Le modifiche al file rendicontazione.php hanno previsto la creazione di un oggetto ObiettivoRendicontazioneAllegato, dal quale viene inizializzata una variabile di nome $allegati contenente il risultato della chiamata alla funzione getAll sull’oggetto appena creato. Successivamente vengono definiti i permessi sugli allegati tramite un array con indici ‘user_id’ e ‘allegati_permission’, il primo contenente la matricola utente selezionato, l’altro contenente le voci ‘canDownload’ e ‘canDelete’, le quali a loro volta vengono inizializzare con i nomi dei file md5 che l’utente selezionato può modificare. A questo punto i dati vengono codificati per poi essere salvati all’interno di un cookie temporaneo. È stato poi introdotto del codice html per la creazione di un modulo di gestione dei file. I file vengono mostrati in una tabella e in base ai permessi dell’utente verranno visualizzati o meno i tasti “elimina” e i link per il download. Se non sono presenti allegati per la rendicontazione, viene mostrato un messaggio che informa l’utente, altrimenti vengono reperiti i link per il download e il delete dall’oggetto $allegati_helper (istanza della classe omonima). Successivamente si controlla che l’utente abbia i privilegi di “edit_responsabile” e in caso affermativo, se non è periodo di rendicontazione, si proibisce l’eliminazione anche a quegli utenti che potrebbero operarla, mostrando un carattere ‘-’ al posto del pulsante di eliminazione. Se invece è periodo di rendicontazione, il tasto elimina viene mostrato (per gli utenti “edit-responsaibile”) e inoltre viene abilitata una form per il caricamento dei file e viene richiamata la funzione getUploadForm, in modo da aggiornare automaticamente la lista dei file presenti una volta aggiunto un nuovo file.

upload.php

Per gestire l’upload dei file è stato creato il file upload.php, il quale definisce un oggetto $allegato come istanza della classe AllegatoHelper. Successivamente richiama la funzione uploadFile() di tale classe e stampa il json_encode del file caricato.


delete.php

In questo file viene creata un’istanza di AllegatoHelper e richiamando la funzione deleteFile di tale classe, si verifica se il file è stato cancellato o meno (sulla base del valore restituito).

Messaggi
   1. Se si verificano errori durante la cancellazione, viene stampato il messaggio: "Si è verificato un errore in fase di cancellazione del file".
   2. Se la cancellazione va a buon fine, viene stampato il messaggio: “Deleted”.


download.php

In questo file viene creata un’istanza di AllegatoHelper, e viene attribuito alla variabile $file il valore restituito dalla chiamata della funzione downloadFiles. Se $file è true, il download è andato a buon fine e viene definito l’header della pagina, altrimenti, il documento va scaricato in un altro modo e vengono avviate delle procedure di riconoscimento del tipo di file, in base al quale viene modificato l’header.

Messaggi di errore
   1. Nel caso in cui il file (da scaricare nel modo alternativo descritto sopra) non venisse trovato, il sistema mostra all’utente il messaggio “File non trovato”.



Torna all'Indice del Manuale Tecnico