SeeQuence, documentazione in italiano

Tavola dei Contenuti

English Version


 * Panoramica
 * Requisiti di sistema
 * Funzionalità
 * Licenza
 * Risorse
 * Riconoscimenti
 * Utilizzo
 * Includere seeQuence
 * Interfaccia pubblica
 * Costruttore
 * Metodi accessori
 * Metodi del generatore di sequenze
 * Note
 * Funzioni esterne
 * Passato e futuro
 * Changelog
 * To-Do

=Panoramica=

Questa è la documentazione di seeQuence. Il progetto è reperibile al seguente URL: http://santecaserio.altervista.org/seequence/

seeQuence è un Sequence Number Generator (Sequence) (generatore di numeri sequenziali) stile SQL scritto in PHP. Grazie ad esso si possono utilizzare delle sequenze lato client in combinazione con quei DBMS che non le supportano lato server, come MySQL, SQLite e altri. Oppure, può essere utilizzato per identificare i record in un file di testo o qualunque altro tipo di oggetto univico. Come linea guida è stata utilizzata l'implementazione di PostgreSQL.

La documentazione che ho utilizzato come riferimento per questo generatore di numeri sequenziali è: E in parte:
 * CREATE SEQUENCE (PostgreSQL)
 * Funzioni per la manipolazione delle sequenze (PostgreSQL)
 * CREATE SEQUENCE (Oracle)

seeQuence sembra essere abbastanza stabile. Ho testato ogni metodo/funzione e lo utilizzo per compiti semplici. L'unica ragione per cui il numero di versione attuale termina con "a" è che non ho ancora ricevuto alcun commento su seeQuence. Inoltre, vorrei aggiungere qualche altra funzione prima di rilasciare una versione 1.0.

Requisiti di sistema
Prima di tutto, non puoi usare seeQuence se non sai cos'è PHP :) Inoltre, non so quale versione di PHP sia necessaria. Ho realizzato seeQuence con PHP 5.2. Suppongo che funzioni su diverse altre funzioni precedenti, ma non l'ho testato. Perciò, ogni segnalazione su come si comporta seeQuence con le vecchie versioni di PHP è la benvenuta. Non vi sono altri requisiti (nessun modulo aggiuntivo, nessun web server, nessun dbms, nessun so specifico è richiesto).

Funzionalità
seeQuence fa tutto ciò che fanno le sequenze di PostgreSQL. Supporta:

when the value reaches max/min value, it can return to the beginning (if you want so)
 * Valori minimo e massimo impostabili, anche negativi
 * Incremento impostabile, anche negativo (sequenza discendente)
 * Cycle: quando il valore raggiunge il massimo o il minimo può ritornare all'inizio (optionale)
 * Valore iniziale: la sequenza può iniziare da un numero diverso dal minimo/massimo
 * nextval legge il prossimo (o il primo) valore e lo restituisce
 * currval restituisce l'ultimo numero generato, se esiste
 * setval imposta il valore corrente a un dato valore specificato

Also:


 * reset imposta il valore corrente al valore iniziale
 * i valori possono essere inseriti in un array associativo (esempio: nel campo "id")
 * Supporta la serializzazione
 * Supporta le sequenza costanti (increment=0)
 * L'oggetto può essere generato partendo da una stringa SQL (comando create sequence per PostgreSQL o Oracle)
 * Può generare una stringa SQL per ricreare la sequenca su PostgreSQL

Licenza
seeQuence è Software Libero. Questa definizione riguarda (solo) i programmi distribuiti sotto la licenza GNU (Affero) General Public License, versione 3. Se hai bisogno di ottenerlo sotto una licenza differente, contatta l'autore (vedi sotto).

Vedi anche il testo (in inglese) della GPL v3 e la FAQ.

Questa documentazione è di pubblico dominio. Se puoi/vuoi aiutare a migliorare questo documento, fallo e basta: non devi chiedere il permesso a nessuno. E usala come ti pare, non mi interessa.

Vedi anche pubblico dominio su Wikipedia.

Risorse

 * Pagina del progetto (per ora solo in inglese)
 * Forum (Italiano, ma si può scrivere anche in altre lingue)

Riconoscimenti
La home page del progetto è: http://santecaserio.altervista.org/seequence L'email dell'autore è: federico_raz _AT_ yahoo, DOT it

Usatela per commenti, collaborazioni, richieste di supporto, etc.

=Utilizzo=

Includere seeQuence
seeQuence consiste in una classe e una funzione esterna, entrambe contenute del file `seequence.php`. Mettilo dove vuoi, puoi anche rinominarlo.

Se potresti aver bisogno di utilizzare la funzione create_sequence per istanziare diversi oggetti in una riga di codice, non usare l'__autoload (non può includere automaticamente il file per trovare create_sequence). Inoltre, __autoload non è una buona pratica di programmazione.

Costruttore
La classe seeQuence può essere istanziata in due modi:

sequence($minimo, $massimo, $incremento, $ciclo, $valore_iniziale)
 * Modo normale

Nessuno di questi parametri è obbligatorio. Se uno o più parametri sono omessi, viene calcolato un valore predefinito. I valori di default dipendono dalla direzione della sequenza (ascendente o discendente).


 * Modo SQL

sequence($stringa_sql)

Questa forma è stata aggiunta nella versione 0.2a. Puoi generare l'oggetto partendo da una stringa SQL. La stringa deve essere un comando CREATE SEQUENCE per PostgreSQL che non contiene commenti. Ecco la sintassi:

CREATE [ TEMPORARY | TEMP ] SEQUENCE nome [ INCREMENT [ BY ] incremento ] [ MINVALUE minimo | NO MINVALUE ] [ MAXVALUE massimo | NO MAXVALUE ] [ START [ WITH ] valore_iniziale ] [ CACHE cache ] [ [ NO ] CYCLE ]


 * INCREMENT [BY] incremento specifica il parametro incremento.
 * MINVALUE minimo specifica il parametro minimo; NOMINVALUE significa che un valore predefinito verrà assegnato al parametro minimo.
 * MAXVALUE minimo specifica il parametro massimo; NOMAXVALUE significa che un valore predefinito verrà assegnato al parametro massimo.
 * START [ WITH ] valore_iniziale specifica il parametro valore_iniziale.
 * [ NO ] CYCLE specifica se la sequenza deve ricominciare quando arriva al termine. Per compatibilità con Oracle, anche NOCYCLE viene compreso.

L'interprete non è case-sensitive e ignora le righe vuote e gli spazi, ma i commenti causano un errore. L'ordine dei parametri non è rilevante, come in Oracle. Il nome della sequenza, la parola chiave TEMP | TEMPORARY (PostgreSQL), il parametro CACHE e il parametro ORDER (Oracle) saranno ignorati).

Valori di default

 * incremento
 * Il valore predefinito è 1, quindi le sequenze sono ascendenti per default.


 * minimo
 * Il valore predefinito è 1 per le sequenze ascendenti, (-PHP_INT_MAX + incremento) per quelle discendenti.


 * massimo
 * Il valore predefinito è (PHP_INT_MAX - incremento) per le sequenze ascendenti, -1 per quelle discendenti.


 * ciclo
 * Il valore predefinito è false.


 * valore_iniziale
 * Il valore predefinito è uguale a minimo.

Attenzione: Dopo che una sequenza è stata creata, questi valori non possono più essere modificati.

Metodi accessori
 int get_min_value  Restituisce minimo.

 int get_max_value  Restituisce massimo.

 int get_increment  Restituisce incremento.

 bool get_cycle  Restituisce un valore booleano che indica se la sequenza ricomincerà da minimo dopo aver raggiunto massimo (o viceversa per le sequenza discendenti).

 int get_initial_value  Restituisce valore_iniziale.

 string toSql($nome_sequenza)  Aggiunto in 0.2a. Restituisce una stringa SQL. Si tratta del comando CREATE SEQUENCE che può essere utilizzato per ricreare la sequenza in un db PostgreSQL. La sequenza si chiamerà $nome_sequenza. La sola incompatibilità con Oracle è che la stringa potrebbe contenere "NO CYCLE", mentre Oracle comprende solo "NOCYCLE". Puoi aggiungere una riga di codice PHP per compatibilità: $sql = str_replace('NO CYCLE', 'NOCYCLE', $sql); Le parole chiave sono in maiuscolo. Vedi sopra per i dettagli sulla la sintassi.

 void values_in_assoc(&$arr, $chiave='id')  Aggiunto in 0.3a. Inserisce i valori generati in $arr (un array associativo), in un campo chiamato $chiave (se non è specificato: "id"). $arr viene passato per riferimento.

Metodi del generatore di sequenze
 void nextval  Incrementa/decrementa il valore corrente e restituisce il nuovo valore. Se il valore corrente diviene superiore al valore massimo o inferiore al minimo, restituisce null.

 int currval  Restituisce l'ultimo valore generato se esiste, altrimenti restituisce null.

 void setval($valore, $chiamato=true)  Imposta il valore corrente a $valore. Il valore predefinito di $chiamato è true, che significa che una chiamata a nextval genererà un nuovo valore. Se è false, nextval genererà $value.

 void reset([$new_value])  Reimposta il valore corrente a $nuovo_valore, se specificato. Altrimenti, reimposta la sequenza a $valore_iniziale.

 bool validate($controlla_se_assurdo=false)  Restituisce true se le proprietà impostate dall'utente sono valide, altrimenti false. Inoltre controlla se il ripo delle proprietà è integer. Se $controlla_se_assurdo è true (predefinito: false) controlla anche se le proprietà sono logicamente corrette (almeno un valore dovrebbe poter essere generato dopo $valore_iniziale).

Funzioni esterne
 array create_sequences($num, $usa_gamme_diverse=true)  Aggiunto in 0.3a. Crea automaticamente (e restituisce in un array) $num sequenze. Se $usa_gamme_diverse è true, le sequenza utilizzeranno diverse gamme di numeri. Se è falso, se sequenze utilizzeranno la stessa gamma (ma genereranno valori diversi all'interno di questa gamma). Il primo metodo utilizza grandi numeri (illeggibili per gli esseri umani), il secondo effettua addizioni più impegnative.

=Il passato e il futuro=

Changelog
0.3a (12-09-08)
 * aggiunto metodo to_assoc_array
 * aggiunta funzione create_sequences
 * aggiunti alcuni commenti
 * rimosso file di documentazione dalla distro (fai riferimento a questo URL)

0.2a (non pubblica)
 * aggiunta possibilità di passare una stringa SQL al costruttore
 * aggiunto toSql

0.1a (agosto 2008)
 * Prima versione pubblica.

To-Do
Non ci sono garanzie che queste funzionalità vengano realmente implementate. Nessuna stima realistica sui tempi.


 * Opzione zerofill (già supportata in una versione non pubblica)
 * Supporto per grandi numeri (funzioni GMP)
 * Aggiungere i valori generati a un file CSV
 * Aggiungere i valori generati a un file XML
 * Generare la sequenza da un record PostgreSQL: "SELECT * FROM sequence"
 * Se la sequenza è molto semplice, possibilità di esportarla in Firebird