Sequences
A sequence allows you to get a next value in form of a string, which is usually a function of the current value. If it has not been used before it delivers a first value. This concept is realized straightforward in Topincs. A sequence is setup and ready to be used when programming a trigger or service within five minutes.
Creating a sequence
The following form requires you to name the sequence, so you will be able to recognize it without inspecting the source code. More important is the id the sequence receives. After clicking Ok in the form the fact sheet of the new sequence is displayed. The id is the last part of the fact sheet URL. Also called system id.
Programming the sequence
The programmatic component of the sequence is a PHP class with two functions:
get_next_value and get_first_value. All parameters and
return values are strings. Take a look at
the following simple example for generating unique identifications for employees within a company.
A simple sequence producing E10000,E10001,E10002,…
Hint: If you remove the two functions from the class, you use the default sequence: 1,2,3,…
<?php
require_once("db/sequence/AbstractSequence.php");
// 1074 is the id of this sequence.
class Sequence1074 extends AbstractSequence {
// $last_value is a string
function get_next_value(string $last_value) : string {
$number = (int) substr($last_value, 1);
return "E" . ($number + 1);
}
function get_first_value() : string {
return "E10000";
}
}
Using the sequence
A sequence can be used in services and triggers. The most common use case is to automatically hand out a running number to a domain topic, like an employee, an invoice or purchased item. Whether you use a service or a trigger depends on your use case. A service allows more human control.
A trigger to assign an employee number upon topic creation
API reference
<?php
$employee = Tobject::get($topic_id);
$employee->set_id(sequence(1074));
The sequence function takes care of concurrency issues. It guarantees you a unique value within the system.
