SeeQuence

Table of Contents

Italian Version


 * Overview
 * System requirements
 * Features
 * License
 * Resources
 * Credits
 * Usage
 * Including seeQuence
 * Public interface
 * Constructor
 * Accessory methods
 * Sequence generator methods
 * Notes
 * External functions
 * The past and the future
 * Changelog
 * To-Do

=Overview=

This is the seeQuence documentation. seeQuence project can be found at: http://santecaserio.altervista.org/seequence/

seeQuence is a SQL-style Sequence Number Generator (Sequence) written in PHP. It can be used to use client-side sequences for those DBMS's which don't support them server-side, like MySQL, SQLite and others. Or, it can just be used to identify rows in a text file or other unique objects. PostgreSQL's implementation of SQL sequences has been a guideline for seeQuence.

Here is the documentation I used as a reference for this Sequence Number Generator implementation: And, partly:
 * CREATE SEQUENCE (PostgreSQL)
 * Sequence Manipulation Functions (PostgreSQL)
 * CREATE SEQUENCE (Oracle)

seeQuence seems to be stable enough. I tested every function and use it for simple purposes. The only reason why its version number ends with an "a" (alpha) is that I didn't have any feedback about seeQuence. Also, I would like to add some features before releasing a 1.0 version.

System requirements
First of all, you can't use seeQuence if you don't know what PHP is :) Also, I don't know what PHP version is requested. I wrote seeQuence in PHP 5.2. I suppose it runs on many previous versions, but I didn't test it. So, any feedback about past PHP versions are welcome. There are no other requirements (no module, no web server, no dbms, no specific os requested=.

Features
seeQuence does all that PostgreSQL sequences do. It supports:


 * Settable min/max values, even negative
 * Settable increment, even negative (descending sequence)
 * Cycle: when the value reaches max/min value, it can return to the beginning (optional)
 * Initial value: sequence can start from a number which is not min/max value
 * nextval reads next (or first) number and returns it
 * currval returns the last generated number, if any
 * setval sets the current value to a given value

Also:


 * reset sets the current value to the initial value
 * values can be inserted in a field of an associative array (ie: "id" field)
 * Suppots serialization
 * Supports constant sequences (increment=0)
 * The object can be generated from a SQL string (create sequence command for Postgresql or Oracle)
 * You can generate a SQL string to recreate the sequence on PostgreSQL

License
seeQuence is Free Software. This definition inherits (only) software covered by the GNU (Affero) General Public License, version 3. If you need to have it with another license, you can contact the author (see below).

See also GPL v3 text and FAQ.

This documentation is public domain. If you can/want to help improve this document, just do it: you need no permissions. And use it as you want, I don't care.

See also public domain on Wikipedia.

Resources

 * Project Page
 * Forum (Italian, but you can write in English)

I&#8217;m not sure why but this woelbg is loading extremely slow for me. Is anyone else having this issue or is it a problem on my end? I&#8217;ll check back later and see if the problem still exists. I&#8217;m not sure why but this woelbg is loading extremely slow for me. Is anyone else having this issue or is it a problem on my end? I&#8217;ll check back later and see if the problem still exists.

=Usage=

Including seeQuence
seeQuence consists in one class and one external function, both contained in the file `seequence.php`. Put it where you want to, you can even rename it.

If you may need to use the create_sequence function to instantiate many objects in one code line, don't use __autoload (it can't automatically include the file to find create_sequence). Also, __autoload is not a good programming practice.

Constructor
seeQuence class may be called in two ways:

sequence($min_value, $max_value, $increment, $cycle, $initial_value)
 * Normal way

None of above parameters is mandatory. If one or more parameters is not specified, a default value will be calculated. Default values depend on the sequence's direction (ascending or descending).


 * SQL way

sequence($sql_string)

This form was added in version 0.2a. You can generate the object from a SQL string. The SQL string must be a CREATE SEQUENCE command for PostgreSQL or Oracle containing no comments. Here is the syntax:

CREATE [ TEMPORARY | TEMP ] SEQUENCE name [ INCREMENT [ BY ] increment ] [ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ] [ START [ WITH ] start ] [ CACHE cache ] [ [ NO ] CYCLE ]


 * INCREMENT [BY] increment specifies the increment parameter.
 * MINVALUE minvalue specifies the min_value parameter; NOMINVALUE means that the default value will be assigned to min_value.
 * MAXVALUE minvalue specifies the max_value parameter; NOMAXVALUE means that the default value will be assigned to miax_value.
 * START [ WITH ] start specifies the initial_value parameter.
 * [ NO ] CYCLE specifies wether the sequence must cycle. For Oracle compatibility, also NOCYCLE is understood.

The parser is not case sensitive and ignores empty lines and spaces, but comments cause an error. Parameters order is not relevant, like in Oracle. The name of the sequence, the keyword TEMP | TEMPORARY (Posgresql), the CACHE parameter and the ORDER parameter (Oracle) will be ignored.

Default values

 * increment
 * Default value is 1, so the sequences are ascending by default.


 * min_value
 * Default value is 1 for ascending sequences, (-PHP_INT_MAX + increment) for descending sequences.


 * max_value
 * Default value is (PHP_INT_MAX - increment) for ascending sequences, -1 for descending sequences.


 * cycle
 * Default value is false.


 * initial_value
 * Default value is equal to min_value.

Warning: After a sequence is created, these values can not be changed.

Accessory methods
 int get_min_value  Returns the minimum value.

 int get_max_value  Returns the maximum value.

 int get_increment  Returns the increment value.

 bool get_cycle  Returns a boolean value indicating if the sequence will restart from min_value when it gets to max_value (or vice versa for descending sequences).

 int get_initial_value  Returns the initial value.

 string toSql($sequence_name)  Added in 0.2a. Returns an SQL string. It is the CREATE SEQUENCE command which can be used to recreate the sequence in a PostgreSQL db. The sequence will be called $sequence_name. The only incompatibility with Oracle is that the string may contain "NO CYCLE", while Oracle only understands "NOCYCLE". You can add a row to your PHP code for compatibility: $sql = str_replace('NO CYCLE', 'NOCYCLE', $sql); Keywords are uppercase. See above for details about the syntax.

 void values_in_assoc(&$arr, $key='id')  Added in 0.3a. Puts generated values into $arr (an associative array), in a field named $key (if not specified: "id"). $arr is passed by reference.

Sequence generator methods
 void nextval  Increments/decrements current value and returns the new value. If $current_value gets higher than $max_value or lower than $min_value returns null.

 int currval  Returns last generated value if any, else returns null.

 void setval($value, $is_called=true)  Set current value to $value. Default value of $is_called is true, which means that a call to nextval will generate another value. If false, nextval will generate $value.

 void reset([$new_value])  Resets the value to $new_value, if specified. Else, resets the sequence to $initial_value.

 bool validate($check_if_absurd=false)  Returns true if properties set by user are valid, else false. Also checks if properties type is integer. If $check_if_absurd is true (default: false) it also checks if properties are logically correct (at least one value should be generated after $initial_value).

External functions
 array create_sequences($num, $use_different_ranges=true)  Added in 0.3a. Automatically creates (and returns in an array) $num sequences. If $use_different_ranges is set to true, the sequences will use different ranges of numbers. If it's false, the sequences will use same range (but will generate different numbers within the range). First method uses bigger numbers (unreadable for humans), second method makes bigger addictions.

=The past and the future=

Changelog
0.3a (12-09-08)
 * added method to_assoc_array
 * added function create_sequences
 * added some comments
 * removed documentation file from the distro (refer to this URL)

0.2a (not public)
 * added the ability to pass a SQL string to the constructor
 * added toSql

0.1a (august 2008)
 * First public version.

To-Do
No garantees that these features will really be implemented. No reliable time estimations.


 * Zerofill option (already supported in a non-public release)
 * Support for big integers (GMP functions)
 * Add sequence values to a CSV file
 * Add sequence values to an XML file
 * Generate the sequence from a PostgreSQL record: "SELECT * FROM sequence"
 * If the sequence is very simple, export to Firebird