
###################################################
#                                                 #
# Php-residence non ha ALCUNA GARANZIA; vedere il #
#           file COPYING per i dettagli.          #
#                                                 #
###################################################

PHP-RESIDENCE versione 1.3.1
Programma per la gestione di hotel e di affitti settimanali o 
giornalieri.

http://www.digitaldruid.net/php-residence/


SICUREZZA
Se php-residence viene utilizzato in un ambiente di rete non 
sicuro e' consigliabile attivare la password dell'utente 
amministratore ed eventualmente utilizzare connessioni ssl.
Non vi dovrebbero essere problemi se piu' computer accedono 
contemporaneamente al database e gli utenti normali non 
dovrebbero poter compiere azioni non consentitegli dai privilegi 
loro assegnatigli.


ATTENZIONE
E' consigliabile custodire tutti i dati anche in modi piu' 
sicuri e fare frequenti backup su file del database 
utilizzando il sistema di backup di php-residence.


REQUISITI SOFTWARE
-apache (>=1.3.26) o altro web server che supporti php
-php (>=3.0.18) con estensione per postgresql, mysql o sqlite
-postgresql (>=7.4.7) o mysql (>=4.1.11) o sqlite
-un browser che supporti html 4.01 con encoding utf-8

Le versioni indicate sono quelle che sono state provate, 
potrebbe funzionare anche su quelle anteriori. Il programma e' 
stato provato solo su Linux, in teoria dovrebbe funzionare anche 
su altri sistemi operativi che supportino i programmi 
precedenti.
CONFIGURAZIONE DI APACHE: Apache deve avere il supporto per 
php ed eseguire con esso le pagine con estensione .php. Cio' 
normalmente e' gia' predisposto per php4, mentre per php3 si 
dovrebbe aggiungere la riga:

AddType application/x-httpd-php3 .php

nei file di configurazione di Apache (httpd.conf o srm.conf).
CONFIGURAZIONE DI MYSQL: Per creare un utente in mysql 
collegarsi al database mysql come root (comando 
"mysql --user=root mysql") ed eseguire la query: 

GRANT ALL PRIVILEGES on nomedatabase.* to utente@localhost IDENTIFIED BY 'pass';

sostituendo rispettivamente nomedatabase, utente e pass con i 
vostri dati.
CONFIGURAZIONE DI POSTGRESQL: assicurarsi che il server 
postgres sia avviato con l'opzione "-i" per permettere 
collegamenti via TCP/IP (in Debian 2.2 porre "PGALLOWTCPIP=yes" 
in /etc/postgresql/postmaster.init, in Red Hat 7.2 porre 
"tcpip_socket = true" in /var/lib/pgsql/data/postgresql.conf). 
Inoltre devono essere settati i permessi giusti nel file 
pg_hba.conf (di solito vanno bene quelli di default). Per creare 
un utente in postgresql utilizzare il comando 
"createuser nome_utente" da utente postgres ("su postgres" da 
root) e rispondere si quando viene chiesto se potra' creare 
database.
CONFIGURAZIONE DI SQLITE: il database sqlite in realtà è un file 
che risiede nella cartella dati, quindi se si utilizza una 
versione 5 o superiore di php non c'è bisogno di nessuna 
configurazione speciale. Tra i dati per il collegamento al 
database non c'è bisogno di inserire nome utente, password ed il 
nome del server.


INSTALLAZIONE
Copiare la cartella php-residence sotto una directory 
raggiungibile dal web (DocumentRoot nei file di configurazione 
di apache), e puntare il browser su 
http://localhost/php-residence/inizio.php (o dove avete 
posizionato la cartella). La directory dati all'interno di 
php-residence deve essere accessibile in scrittura dall'utente 
con cui gira il server web (utente www-data in Debian), anche 
dopo l'installazione. Quindi se si usa un servizio di hosting 
potrebbe essere necessario cambiarli via ftp: per esempio con 
cuteftp (win) o gftp (linux) connettersi e cliccare col tasto 
destro sulla cartella dati sul server (colonna di destra), 
scegliere l'opzione CHMOD e aggiungere i permessi di 
scrittura (755 o 777).
Dopo la schermata iniziale, dove si potra' scegliere la linga 
italiana, si dovranno inserire i dati per collegarsi al 
database, alcuni dei quali sono gia' presenti con valori che 
dovrebbero andar bene nella maggior parte dei casi. La password 
e' necessaria solo se abilitata nel server postgres o mysql. In 
Debian con php3 rispondere si alla domanda riguardante 
l'estensione "pgsql.so". Dopo aver inserito i dati sugli 
appartamenti (almeno il numero), si dovra' creare l'anno che si 
intende gestire (si potranno in seguito aggiungere al periodo 
scelto dei mesi alla fine ma non toglierne). Se esiste l'anno 
precedente si possono importare eventuali prezzi e prenotazioni 
riguardanti mesi in comune. Alla fine si arriva alla facciata 
principale, che penso sia abbastanza intuitiva. Prima di poter 
inserire delle prenotazioni si dovranno inserire i prezzi dei 
relativi periodi.

Per la disinstallazione cancellare la directory php-residence
e distruggere il database creato (destroydb nomedatabase o 
dropdb nomedatabase a seconda della versione per postgresql).


AGGIORNAMETO DA VERSIONI PRECEDENTI
Prima di aggiornare e' opportuno fare un backup del database  
con il sistema di backup di php-residence e salvare backup.php, 
pena la PERDITA DI TUTTI I DATI! Controllare anche che i nuovi 
requisiti software siano compatibili con quelli attuali.
Lasciare nella cartella dove e' installato php-residence solo 
la cartella dati (sempre con i permessi di scrittura per il web 
server), cacellando tutto il resto. Copiarci poi i files della 
nuova versione (tranne la cartella dati naturalmente) e PER 
PRIMA COSA accedere al menu' principale (come utente 
amministratore se il login e' attivato) e premere il tasto 
"aggiorna" attendendo che si finisca di caricare la pagina. Se 
si usano moduli o temi aggiuntivi ricordarsi di  copiare anche 
essi con i files della nuova versione.
E' possibile passare dall'utilizzo di un database postgresql a 
uno mysql o viceversa utilizzando il sistema di backup. 

Se si utilizza sqlite come database l'aggiornamento ad una nuova 
versione non è supportato, si dovrà prima passare ad un database 
mysql o postgresql con il sistema di backup.

Se si utilizza una versione di mysql inferiore alla 4.1 si 
raccomanda di creare un file di backup prima di aggiornare mysql 
ad una versione uguale o superiore alla 4.1 e di ripristinare 
tale file subito dopo.

Per chi aggiorna da una versione precedente alla 1.1 i modelli 
internet eventualmente presenti nelle loro posizioni predefinite 
saranno rinominati. Ache file con i vecchi nomi che richiamano i 
contenuti dei file con i nuovi nomi saranno creati , ma si 
raccomanda di aggiornare i link nel resto del proprio sito per 
farli puntare ai nuovi nomi.

Per chi aggiorna da una versione precedente alla 0.2 le cartelle 
da lasciare sono datipermanenti e le cartelle degli anni, poi si
deve creare la cartella contr  e trasferirvi i contratti 
rinominandoli da contratto1.php a contr01.php, ecc.


CONSIGLI
-Utilizzare i tasti del browser per tornare indietro dopo la 
 visualizzazione di un documento. 
-Inserire sempre numeri con al massimo 2 decimali come soldi. 
 Per separare i decimali si puo' utilizzare la virgola o il
 punto, ma NON separare le migliaia.
-Se non si inserisce nessun metodo per l'assegnazione di un 
 appartamento in una prenotazione il programma assegnera'
 automaticamente l' appartamento tenendo conto del numero di 
 persone e delle priorita' degli appartamenti (piu' bassa e' e 
 prima viene assegnato).
-Le prenotazioni gia' iniziate e quelle con orario di entrata 
 registrato vengono considerate fisse. Per spostare quelle gia' 
 iniziate viene offerta una opzione qunado si tenta di muoverle 
 in appartamenti non vuoti.
-La regola di assegnazione 1 puo' essere usata per appartamenti
 riservati ad agenzie che devono essere informate in caso di 
 prenotazione.
-Con la regola di assegnazione 2 si puo' per esempio associare 
 una tariffa soprannominata "4 persone" agli appartamenti che
 possono ospitare 4 persone.
-Se non si vuole che il programma assegni automaticamente 
 gli appartamenti basta assegnare sempre a tutte le 
 prenotazioni un appartamento fisso.
-Fare una installazione di prova per vedere il funzionamento
 prima di inserire i dati reali.
-Si puo' assegnare un prezzo diverso per ogni periodo anche se 
 nella pagina di inserimento prezzi ve ne sono solo 8 (se ne 
 inseriscono 8 alla volta).
-Se si opera tra 2 anni non creare il nuovo anno fino a quando
 non inizia, ma continuare ad inserire le prenotazioni dell'
 anno successivo dal menu' dell'anno corrente, eventualmente si
 possono aggiungere i periodi necessari. Quando poi arriva il
 nuovo anno crearlo importando le prenotazioni dall'anno
 precedente (per fare cio' si devono utilizzare gli stessi tipi
 di periodi dell'anno precedente e se i periodi sono 
 settimanali anche lo stesso giorno di inizio/fine settimana).
 Si consiglia di lasciare attivata l'opzione in "configura e 
 personalizza" per creare il nuovo anno in automatico il 10 
 Gennaio.
-Per il nome degli appartamenti usare per esempio 07 o 007 
 invece di 7 per avere delle tabelle dei mesi ordinate.
-Il browser raccomandato per il back-office è mozilla firefox o 
 qualsiasi altro browser basato su mozilla (www.mozilla.org).
-Si possono aggiungere nuovi utenti disattivati e cambiare le 
 loro colonne selezionate nella pagina delle personalizzazioni 
 per avere profili diversi nella tabella con tutte le 
 prenotazioni.
-Se le stanze di solito vengono pulite il giorno prima 
 dell'arrivo dei clienti nella pagina della personalizzazioni si 
 puo' cambiare il momento in cui le prenotazioni vengono 
 considerate cominciate in modo che non vengano piu' spostate.
-Se si usa php-residence via internet e si ha una connessione a 
 tempo si puo' installarlo anche sul computer di casa e 
 subordinarlo (da configura --> interconnessioni) alla 
 installazione di internet per risparmiare.


INSERIMENTO DEI DOCUMENTI
Da "configura e personalizza", cliccando sul loro numero, si 
possono editare i testi dei documenti da stampare, salvare o 
inviare come email. I testi vanno inseriti in formato HTML, RTF, 
o in testo semplice per spedire email. Dopo l'installazione di 
php-residence saranno presenti alcuni esempi di documenti già 
utilizzabili. Per inserire facilmente un documento RTF scrivete 
prima il testo con il vostro programma preferito (per esempio 
Word o OpenOffice), salvate il file in formato RTF e riapritelo 
con un editor di testi, copiate poi tutto il testo ed 
incollatelo nel documento.
Nei documenti si possono utilizzare delle variabili predefinite 
che se vuote verranno sostituite da spazi da riempire. Le parti 
di documento all'interno dei tag [r][/r] verranno ripetute per 
ogni prenotazione (se i tag non sono presenti tutto il documento 
verrà ripetuto). All'interno di queste parti si possono inserire 
delle liste con i tag [r2][/r2] (per ospiti) o [r3][/r3] (per 
costi aggiuntivi). Per esempio per la lista con i dati degli 
ospiti le variabili finiscono tutte col suffisso "_ospite".
Alcune variabili disponibili che si possono inserire sono (la 
lista completa è nella pagina di modifica dei documenti):

Dati del cliente:
[cognome]		cognome
[nome]			nome
[data_nascita]		data di nascita
[il]			'il' (maschile) o 'la' (femminile)
[Il]			'Il' (maschile) o 'La' (femminile)
[al]			'al' (maschile) o 'alla' (femminile)
[e]			'e' (maschile) o 'a' (femminile)
[o]			'o' (maschile) o 'a' (femminile)
[Mr]			'' (maschile) o 's' (femminile)
[nazione]		nazione di provenienza
[citta]			citta' di residenza
[via]			via
[via2]			come $via ma inserisce la parola via
			davanti agli spazi se non e' definita
[numcivico]		numero civico
[cap]			codice di avviamento postale
[telefono]		numero di telefono
[telefono2]		secondo telefono
[telefono3]		terzo telefono
[fax]			numero di fax

Dati della prenotazione:
[num_persone]		numero di persone
[n_letti_agg]		letti aggiuntivi dei costi
[num_persone_tot]	numero di persone + letti aggiuntivi
[costo_tot]		prezzo totale
[caparra]		caparra
[resto_caparra]		prezzo totale - caparra
[data_inizio]		data di arrivo
[data_fine]		data di partenza
[nome_tariffa]		nome della tariffa
[costo_tariffa]		prezzo senza costi aggiuntivi e sconto
[sconto]		sconto
[commento]		commento
[appartamento]		numero dell' appartamento
[app_assegnabili]	lista degli appartamenti assegnabili 
			separati da virgole
[pagato]		quanto e' stato pagato finora
[tutti_i_costi_agg]	lista con tutti i costi aggiuntivi con i
			rispettivi valori
[nome_costo_agg_sel]	nome del costo aggiuntivo selezionato 
			prima di vedere il documento
[valore_costo_agg_sel]	valore del costo aggiuntivo selezionato
			prima di vedere il documento
[oggi]			data odierna
[costo_tot_p],		come i precedenti senza _p finale ma 
[caparra_p],[pagato_p],	formattati con punti e virgole per 
[resto_caparra_p],	decimali e migliaia
[costo_tariffa_p],
[sconto_p],
[tutti_i_costi_agg_p],
[valore_costo_agg_sel_p]

[errore_ripetizione]	quando non nulla la prenotazione 
			corrente non viene aggiunta al documento
[email_gia_inviata]	1 se una email con stesso oggetto è già 
			stata inviata al cliente, 0 altrimenti
[messaggio_di_errore]	quando non nulla il suo contenuto viene 
			mostrato al posto del documento


PAGINE PER IL SITO WEB
E' possibile creare delle pagine da inserire in un sito 
internet, per esempio per permettere ai visitatori di 
controllare la disponibilita' ed eventualmente richiedere di 
prenotare via email. Si accede alla creazione delle pagine da 
"Configura e personalizza". La pagina che viene creata può 
essere spostata sul propio sito web (sempre con supporto 
per php) da dove pero' dovra' potere accedere comunque al 
database con i dati forniti al momento della creazione della 
pagina.
Una volta creata la pagina potra' essere editata a mano per 
inserire il proprio html. Si puo' inserire l'html all'inizio 
e alla fine del file, potendo cosi' per esempio racchiudere la 
form di disponibilita' all'interno di una tabella. Editando il 
file si possono inoltre cambiare tutte le variabili inserite al 
momento della creazione e anche le frasi della form.
Si raccomanda di non spostare a mano e rinominare i files, 
invece li si può creare direttamente nella loro posizione finale 
impostando la directory dove vengono creati in "configura e 
personalizza". In questo modo la pagine verranno automaticamente 
aggiornate quando si crea un nuovo anno o quando si aggiorna il 
database.
I pagine per il sito web possono essere visualizzate in modalità 
frame aggiungedo ?framed=1 alla loro URL, in questo modo verrà 
mostrata una versione semplificata della pagina personalizzabile 
con un file css esterno. Questa modalità può essere utilizzata 
per esempio per avviare le richieste di disponibilità in un 
riquadro (iframe) all'interno di altre pagine del sito. Se si 
aggiunge anche &blank=1 alla URL la form si aprirà in una nuova 
finestra.


GESTIONE UTENTI
Si puo' accede alla gestione degli utenti dalla pagina "Configura 
e personalizza". Nuovi utenti possono essere utilizzati per dare 
accesso diretto ad agenzie da parte del proprietario, o da una
agenzia per dare la possibilita ai proprietari di controllare la
disponibilita e bloccare periodi. 
Si possono limitare gli appartamenti che un utente puo' 
utilizzare in due modi: o facendo in modo che possa inserire 
prenotazioni solo nei periodi selezionati della regola di 
assegnazione 1, oppure facendo in modo che possa utilizzare solo 
tariffe abbinate a determinati appartamenti tramite la regola di 
assegnazione 2 e che non possa ne' inserire ne' modificare 
l'assegnazione degli appartamenti.
Se viene dimenticata la password dell'utente amministratore si 
puo' cancellare il file abilita_login all'interno della directory 
dati, in questo modo verra' disabilitato il login iniziale e 
chiunque potra' accedere con i privilegi dell'utente 
amministratore.


LICENZA D'USO
Vedere il file COPYING.


AUTORE
Marco M. F. De Santis 
Email: marco@digitaldruid.net
