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 è:

• CREATE SEQUENCE (PostgreSQL)
• Funzioni per la manipolazione delle sequenze (PostgreSQL)

E in parte:

• 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:

• 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)

when the value reaches max/min value, it can return to the beginning (if you want so)

• 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

GPL v3

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.

Interfaccia pubblica

Costruttore

La classe seeQuence può essere istanziata in due modi:

• Modo normale

sequence($minimo, $massimo, $incremento, $ciclo, $valore_iniziale)

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).

Notes

Puoi serializzare le istanze di seeQuence.
Non puoi (e non dovresti mai) clonare le istanze di seeQuence.

ATTENZIONE: anche se seeQuence non imposta mai automaticamente valori non validi, accetta sempre l'input dell'utente senza validarlo. Quindi, è possibile avere sequenze costanti (incremento=0) o sequenze assurde che generano valori imprevedibili. Se non sei sicuro dei valori che hai impostato, utilizza il metodo validate().

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