DOC Document new UX for unique index violations

silverstripe · Jan 15, 2025 · 02e3cff · 02e3cff
1 parent 6f86a03
commit 02e3cff
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 0 deletions.
diff --git a/en/02_Developer_Guides/00_Model/12_Indexes.md b/en/02_Developer_Guides/00_Model/12_Indexes.md
@@ -61,6 +61,11 @@ support the following:
 - `unique`: Index plus uniqueness constraint on the value
 - `fulltext`: Fulltext content index
 
+> [!NOTE]
+> Violating a unique index will throw a [`DuplicateEntryException`](api:SilverStripe\ORM\Connect\DuplicateEntryException) exception which you can catch and handle to produce appropriate validation messages.
+>
+> If the violation happens when calling [`DataObject::write()`](api:SilverStripe\ORM\DataObject::write()), the exception will be caught and a [`ValidationException`](api:SilverStripe\ORM\ValidationException) will be thrown instead. The CMS catches any `ValidationException` and displays them as user friendly validation errors in edit forms.
+
 ```php
 // app/src/MyTestObject.php
 namespace App\Model;

diff --git a/en/08_Changelogs/5.4.0.md b/en/08_Changelogs/5.4.0.md
@@ -13,6 +13,7 @@ title: 5.4.0 (unreleased)
   - [Reports quality of life updates](#reports-quality-of-life-updates)
   - [New `class_description` configuration on `DataObject`](#class-description)
   - [`oEmbed` sandboxing](#oembed-sandboxing)
+  - [UX improvement for unique indexes](#unique-indexes)
   - [Other new features](#other-new-features)
 - [API changes](#api-changes)
 - [Bug fixes](#bug-fixes)
@@ -101,6 +102,16 @@ SilverStripe\View\Shortcodes\EmbedShortcodeProvider:
     allow: 'fullscreen'
 ```
 
+### UX improvement for unique indexes {#unique-indexes}
+
+It has been possible to create unique indexes for `DataObject` models for a long time in Silverstripe CMS, but when these unique indexes were violated (i.e. a user tried to create a duplicate record), there was no UX feedback in the CMS.
+
+Violating a unique index will now throw a new [`DuplicateEntryException`](api:SilverStripe\ORM\Connect\DuplicateEntryException) exception which you can catch and handle to produce appropriate validation messages.
+
+If the violation happens when calling [`DataObject::write()`](api:SilverStripe\ORM\DataObject::write()), the exception will be caught and a [`ValidationException`](api:SilverStripe\ORM\ValidationException) will be thrown instead. The CMS catches any `ValidationException` and displays them as user friendly validation errors in edit forms.
+
+See [indexes](/developer_guides/model/indexes/) to learn about indexes in Silverstripe CMS.
+
 ### Other new features
 
 - A new [`BaseKernel::getBooted()`](api:SilverStripe\Core\BaseKernel::getBooted()) method has been added for checking whether the kernel has been booted yet or not.