Most transaction-oriented data contains a unique identifier that you can use to refer back to a specific record or event. If you are generating sales orders online you will likely want each order to have a unique order number. If you are saving orders in a database the order number will most likely be the primary key for the order table. If you are storing order information in flat files, the name of the file will likely be derived from the order number.

Unique numbers can be generated using the dollar function $nextnum. At a minimum, this file is passed the name of the file identifier where the current number is stored. As with all dollar function, the best way to learn about the function is to open the helper form associated with the function. Here we show the parameter descriptions provided by the nextnum help.

The $nextnum function has two modes as we describe next.

Update Mode

Most of the time you will use $nextnum to increment a transaction number and return the new number. This mode is implied by passing a non-zero increment value to the $nextnum function. In the example below we assume that this logic can be used to obtain the next available quote number or invoice number. Quote numbers are stored in the private data text file next_quote_number.txt and invoice numbers are stored in next_invoice_number.txt. The nextnum function will create these files if they don't exist.

If this is the very first quote, the number will start from 1000 and will be incremented by 3 for each new quote. Invoice numbers will start from 30000 and will be incremented by 1 for each new quote.

if ($quote_order) {
	$_SESSION['invoice_number'] = $this->site->dollar_function('nextnum','next_quote_number',1000,3);
}
else {
	$_SESSION['invoice_number'] = $this->site->dollar_function('nextnum','next_invoice_number',30000,1);
}

Retrieval Mode

Occasionally, you may want to know what highest used transaction number is without altering the number. This is achieved by passing zero as the increment number. In this example, we obtain the last issued invoice number and we iterate through the previous 100 invoices.

$latest_invoice = $this->site->dollar_function('nextnum','next_invoice_number');
$recent = $latest_invoice - 100;
for ($i = $latest_invoice; $i > $recent; $i--) {
	$this->process_invoice($i);
}

Never use this Retrieval Mode method to retrieve the latest identifier for the current user session since other users (web visitors) may be incrementing the next number data as well. Instead, if you need to know the latest transaction generated by the current user, you should copy the nextnum value to a session variable and use this to refer back to the latest value.

If you are embedding $nextnum into a page, rather than calling it from PHP code, you can copy the number to a session variable at the same time as we show here:

$nextnum(next_invoice_number,30000,1,invoice_number)

We can then use $session(invoice_number) to refer to a file that we may want to save as part of our transaction definition for example.