diff --git a/.gitbook/assets/logoxoops.jpg b/.gitbook/assets/logoxoops.jpg index 20545b0..6fc9578 100644 Binary files a/.gitbook/assets/logoxoops.jpg and b/.gitbook/assets/logoxoops.jpg differ diff --git a/.gitbook/assets/xmf_debug_dump_1.png b/.gitbook/assets/xmf_debug_dump_1.png index 020e72a..fb1a36a 100644 Binary files a/.gitbook/assets/xmf_debug_dump_1.png and b/.gitbook/assets/xmf_debug_dump_1.png differ diff --git a/.gitbook/assets/xmf_debug_dump_2.png b/.gitbook/assets/xmf_debug_dump_2.png index b4e59ed..4bf7df1 100644 Binary files a/.gitbook/assets/xmf_debug_dump_2.png and b/.gitbook/assets/xmf_debug_dump_2.png differ diff --git a/README.md b/README.md index 0cabb1a..4148aef 100644 --- a/README.md +++ b/README.md @@ -3,15 +3,16 @@  ## The XMF \(XOOPS Module Framework\) Cookbook +**Version 1.2.28** ### View it on: [](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: [](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)\) diff --git a/SUMMARY.md b/SUMMARY.md index 33027ae..ff6da02 100644 --- a/SUMMARY.md +++ b/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) diff --git a/basic-ingredients/forward-compatibility.md b/basic-ingredients/forward-compatibility.md index 8e068ad..c31f393 100644 --- a/basic-ingredients/forward-compatibility.md +++ b/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. diff --git a/cover.jpg b/cover.jpg index b73f151..0b9cdde 100644 Binary files a/cover.jpg and b/cover.jpg differ diff --git a/en/assets/logoXoops.jpg b/en/assets/logoXoops.jpg index 20545b0..6fc9578 100644 Binary files a/en/assets/logoXoops.jpg and b/en/assets/logoXoops.jpg differ diff --git a/en/assets/xmf_debug_dump_1.png b/en/assets/xmf_debug_dump_1.png index 020e72a..fb1a36a 100644 Binary files a/en/assets/xmf_debug_dump_1.png and b/en/assets/xmf_debug_dump_1.png differ diff --git a/en/assets/xmf_debug_dump_2.png b/en/assets/xmf_debug_dump_2.png index b4e59ed..4bf7df1 100644 Binary files a/en/assets/xmf_debug_dump_2.png and b/en/assets/xmf_debug_dump_2.png differ diff --git a/recipes/README.md b/recipes/README.md index c6f4210..f7ea127 100644 --- a/recipes/README.md +++ b/recipes/README.md @@ -40,4 +40,5 @@ * Generate Keyword Lists * Generate a Search Summary * [Highlighting Content](highlighting-content.md) +* [Using ULID](using-ulid.md) diff --git a/recipes/using-ulid.md b/recipes/using-ulid.md new file mode 100644 index 0000000..4532529 --- /dev/null +++ b/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 +