Adding ULID

README.md

@@ -3,15 +3,16 @@
 ![logoXoops.jpg](.gitbook/assets/logoxoops.jpg)
 
 ## The XMF \(XOOPS Module Framework\) Cookbook
+**Version 1.2.28**
 
 ### View it on: [![Gitbook](https://xoops.org/images/logoGitbookSmall.png)](https://xoops.gitbook.io/xmf-cookbook/)
 
-Copyright © 2013-2020 XOOPS Project \([xoops.org](https://xoops.org)\)
+Copyright © 2013-2023 XOOPS Project \([www.xoops.org](https://xoops.org)\)
 
 ### License:
 
 [![Creative Commons License](https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-nc-sa/4.0/)  
 Unless otherwise specified, this content is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/).
 
-All derivative works are to be attributed to XOOPS Project \([xoops.org](https://xoops.org)\)
+All derivative works are to be attributed to XOOPS Project \([www.xoops.org](https://xoops.org)\)
 

SUMMARY.md

@@ -22,6 +22,7 @@
     * [Standard Admin Pages](recipes/module-admin-pages/standard-admin-pages.md)
   * [Manage Metadata](recipes/manage-metadata.md)
   * [Highlighting Content](recipes/highlighting-content.md)
+  * [Using ULID](recipes/using-ulid.md)
 * [Reference](reference/README.md)
   * [Assert](reference/assert/README.md)
     * [Assertions](reference/assert/assertions.md)
@@ -68,7 +69,8 @@
   * [Random](reference/random.md)
   * [Request](reference/request.md)
   * [StopWords](reference/stopwords.md)
-  * [Uuid](reference/uuid.md)
+  * [ULID](reference/ulid.md) 
+  * [UUID](reference/uuid.md)
   * [Yaml](reference/yaml.md)
 * [Credits](credits.md)
 * [License:](license.md)

basic-ingredients/forward-compatibility.md

@@ -1,4 +1,4 @@
 # Forward Compatibility
 
-**XMF** is already included in the next generation of XOOPS. This means every line of module code written for XOOPS 2.5.8 using XMF is fully forward compatible! The API documented here is guaranteed to be supported in the next major XOOPS release.
+**XMF** is already included in the next generation of XOOPS. This means every line of module code written for XOOPS 2.5.10+ using XMF is fully forward compatible! The API documented here is guaranteed to be supported in the next major XOOPS release.
 

recipes/README.md

@@ -40,4 +40,5 @@
   * Generate Keyword Lists
   * Generate a Search Summary
 * [Highlighting Content](highlighting-content.md)
+* [Using ULID](using-ulid.md)
 

recipes/using-ulid.md

@@ -0,0 +1,85 @@
+# Using ULID
+
+ULID (Universally Unique Lexicographically Sortable Identifier) offers a sortable alternative to UUIDs. In XOOPS, the XMF (XOOPS Module Framework) library, which is part of the standard installation, includes ULID functionality. This tutorial explains how to use ULID in your XOOPS projects.
+
+### Understanding ULID and Its Benefits
+
+ULID (Universally Unique Lexicographically Sortable Identifier) is a type of identifier that aims to provide certain advantages over traditional UUIDs (Universally Unique Identifiers). While UUIDs are known for their global uniqueness, ULIDs bring two additional benefits: they are lexicographically sortable and more compact.
+
+#### Lexicographic Sortability
+One of the key features of ULIDs is that they are sortable by time, as the first part of a ULID is a timestamp. This property is immensely useful in scenarios where you need to maintain the order of creation of records or events. For instance, in a database, sorting rows by their ULID will naturally arrange them in the order they were created. This characteristic is not available with standard UUIDs, which are typically randomly generated and have no inherent order.
+
+#### Compact and URL-friendly
+ULIDs are represented as 26-character strings, consisting of Crockford's Base32 encoding, which is URL-safe and case-insensitive. This compactness makes ULIDs more efficient to store, faster to index, and easier to transmit. Their URL-friendly nature also makes them suitable for use in web applications where identifiers need to be passed in URLs.
+
+#### Uniqueness and Performance
+ULIDs maintain a high degree of uniqueness, similar to UUIDs, reducing the risk of collision (two records having the same identifier). Moreover, generating ULIDs is a fast operation, which does not significantly impact the performance of applications, even when large numbers of identifiers are required.
+
+### Summary
+ULID offers a modern approach to generating identifiers, combining the unique characteristics of UUIDs with the advantages of lexicographical sortability and compactness. In XOOPS, when using the XMF library, ULIDs become a straightforward and efficient solution for managing unique identifiers in web applications, particularly where the order of record creation is significant.
+
+### Using ULID in XOOPS with XMF
+
+ULID (Universally Unique Lexicographically Sortable Identifier) offers a sortable alternative to UUIDs. In XOOPS, the XMF (XOOPS Module Framework) library, which is part of the standard installation, includes ULID functionality. This tutorial explains how to use ULID in your XOOPS projects.
+
+#### Prerequisites
+- A XOOPS installation.
+
+### Step 1: Importing ULID Class
+Import the ULID class from XMF at the beginning of your PHP file:
+
+```php
+use Xmf\Ulid;
+```
+
+### Step 2: Generating a ULID
+Generate a new ULID using the `Ulid::generate()` method, which returns a ULID string:
+
+```php
+$ulid = Ulid::generate();
+echo $ulid; // Example output: 01ARZ3NDEKTSV4RRFFQ69G5FAV
+```
+
+### Step 3: Using ULID in Database Operations
+ULIDs serve as excellent unique identifiers for database records.
+
+#### Example: Inserting a Record
+For a table `my_table` with an `id` field:
+
+```php
+global $xoopsDB;
+$ulid = Ulid::generate();
+$sql = "INSERT INTO " . $xoopsDB->prefix('my_table') . " (`id`, `other_field`) VALUES ('$ulid', 'value')";
+$xoopsDB->query($sql);
+```
+
+### Step 4: Retrieving and Sorting by ULID
+Leverage the sortable nature of ULIDs for fetching records.
+
+#### Example: Selecting Records in Creation Order
+```php
+global $xoopsDB;
+$sql = "SELECT * FROM " . $xoopsDB->prefix('my_table') . " ORDER BY `id`";
+$result = $xoopsDB->query($sql);
+while ($row = $xoopsDB->fetchArray($result)) {
+    // Process each row
+}
+```
+
+### Step 5: Handling ULID in Templates
+ULIDs can be passed to Smarty templates.
+
+In PHP:
+
+```php
+$xoopsTpl->assign('ulid', Ulid::generate());
+```
+
+In Smarty template:
+
+```smarty
+<div>ULID: {$ulid}</div>
+```
+
+### Conclusion
+Integrating ULID with XOOPS through XMF provides a powerful method for generating and handling unique, sortable identifiers. It's particularly useful for applications where the order of record creation is important, offering a better alternative to traditional UUIDs in such scenarios.

reference/README.md

@@ -1,6 +1,6 @@
 # Reference
 
-This is a detailed overview of all of the XMF classes as of release 1.2.26.
+This is a detailed overview of all of the XMF classes as of release 1.2.28.
 
 ## Contents
 
@@ -49,5 +49,6 @@ This is a detailed overview of all of the XMF classes as of release 1.2.26.
 * [Random](random.md)
 * [Request](request.md)
 * [StopWords](stopwords.md)
+* [Ulid](ulid.md) 
 * [Uuid](uuid.md)
 * [Yaml](yaml.md)

reference/ulid.md

@@ -0,0 +1,29 @@
+# Ulid
+
+`Xmf\Ulid` class provides a unique identifier (ULID) generator for XOOPS modules. 
+
+ULIDs are a type of UUID that are designed to be more ordered and sequential than traditional UUIDs. This makes them well-suited for use in applications where it is important to be able to compare or order identifiers.
+
+## Uuid::generate()	
+Generates a new ULID
+
+## Uuid::encodeTime($time)	
+Encodes a timestamp into a ULID time component
+
+## Uuid::encodeRandomness()	
+Generates random data and encodes it into a ULID randomness component
+
+## Uuid::decode($ulid)	
+Decodes a ULID string into a time and randomness component array
+
+## Uuid::decodeTime($ulid)	
+Decodes the time component of a ULID string
+
+## Uuid::decodeRandomness($ulid)	
+Decodes the randomness component of a ULID string
+
+## Uuid::isValid($ulid)	
+Checks if a ULID string is valid
+
+## Uuid::microtimeToUlidTime($microtime)	
+Converts a microtime float value to a ULID time integer

table-of-content.md

@@ -46,6 +46,7 @@
     * Generate Keyword Lists
     * Generate a Search Summary
   * [Highlighting Content](recipes/highlighting-content.md)
+  * [Using ULID](recipes/using-ulid.md)
 * [Reference](reference/)
   * [Assert](reference/assert/)
     * [Assertions](reference/assert/assertions.md)
@@ -92,6 +93,7 @@
   * [Random](reference/random.md)
   * [Request](reference/request.md)
   * [StopWords](reference/stopwords.md)
+  * [Ulid](reference/ulid.md) 
   * [Uuid](reference/uuid.md)
   * [Yaml](reference/yaml.md)
 * [Credits](credits.md)

xmf-cookbook.md

@@ -4,12 +4,12 @@
 
 ## The XMF \(XOOPS Module Framework\) Cookbook
 
-Copyright © 2013-2020 XOOPS Project \([xoops.org](https://xoops.org)\)
+Copyright © 2013-2023 XOOPS Project \([www.xoops.org](https://xoops.org)\)
 
 ### License:
 
 [![Creative Commons License](https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-nc-sa/4.0/)  
 Unless otherwise specified, this content is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/).
 
-All derivative works are to be attributed to XOOPS Project \([xoops.org](https://xoops.org)\)
+All derivative works are to be attributed to XOOPS Project \([www.xoops.org](https://xoops.org)\)