docs: add more details to upgrade notes for 4.7 release

user_guide_src/source/changelogs/v4.7.0.rst

@@ -173,6 +173,8 @@ To use a different encryption key permanently, pass a custom config when creatin
     // Get a new handler instance with the custom config (not shared)
     $handler = service('encrypter', $config, false);
 
+.. _v470-interface-changes:
+
 Interface Changes
 =================
 
@@ -183,6 +185,8 @@ Interface Changes
 - **Database:** The ``QueryInterface`` now includes the ``getOriginalQuery()`` method.
 - **Images:** The ``ImageHandlerInterface`` now includes a new method: ``clearMetadata()``.
 
+.. _v470-method-signature-changes:
+
 Method Signature Changes
 ========================
 
@@ -235,11 +239,15 @@ Method Signature Changes
     - ``CodeIgniter\Session\Handlers\RedisHandler::read($id): false|string``
     - ``CodeIgniter\Session\Handlers\RedisHandler::gc($max_lifetime): int``
 
+.. _v470-property-signature-changes:
+
 Property Signature Changes
 ==========================
 
 - **Entity:** The protected property ``CodeIgniter\Entity\Entity::$dataCaster`` type has been changed from ``DataCaster`` to ``?DataCaster`` (nullable).
 
+.. _v470-removed-deprecated-items:
+
 Removed Deprecated Items
 ========================
 

user_guide_src/source/installation/upgrade_470.rst

@@ -12,6 +12,102 @@ Please refer to the upgrade instructions corresponding to your installation meth
     :local:
     :depth: 2
 
+****************
+Breaking Changes
+****************
+
+PHP 8.2 Required
+================
+
+The minimum PHP requirement has been updated to **PHP 8.2**.
+
+If your current runtime is older than PHP 8.2, upgrade PHP first before
+upgrading CodeIgniter.
+
+Validation ``regex_match`` Placeholders
+=======================================
+
+Placeholders in the ``regex_match`` validation rule must now use double curly
+braces.
+
+If you previously used single braces like
+``regex_match[/^{placeholder}$/]``, update it to:
+``regex_match[/^{{placeholder}}$/]``.
+
+This avoids ambiguity with regex quantifiers such as ``{1,3}``.
+
+Model Primary Key Validation Timing and Exceptions
+==================================================
+
+The ``insertBatch()`` and ``updateBatch()`` methods now honor model settings
+like ``updateOnlyChanged`` and ``allowEmptyInserts``. This change ensures
+consistent handling across all insert/update operations.
+
+Primary key values are now validated before database queries in
+``insert()``/``insertBatch()`` (without auto-increment), ``update()``, and
+``delete()``.
+
+Invalid primary key values now throw ``InvalidArgumentException`` instead of
+database-layer ``DatabaseException``.
+
+If your code catches ``DatabaseException`` for invalid primary keys, update it
+to handle ``InvalidArgumentException`` as well.
+
+Entity Change Detection Is Now Deep
+===================================
+
+``Entity::hasChanged()`` and ``Entity::syncOriginal()`` now perform deep
+comparison for arrays and objects.
+
+If you relied on the previous shallow (reference-based) behavior, review your
+entity update flows and tests because nested changes are now detected.
+
+Also, ``Entity::toRawArray()`` now recursively converts arrays of entities when
+``$recursive`` is ``true``.
+
+Encryption Handler Key State
+============================
+
+``OpenSSLHandler`` and ``SodiumHandler`` no longer mutate the handler's internal
+key when a key is passed via ``$params`` to ``encrypt()``/``decrypt()``.
+
+If your code depended on passing a key once and reusing it implicitly later,
+move to explicit key configuration in ``Config\\Encryption`` (or pass a custom
+config when creating the encrypter service).
+
+Interface Changes
+=================
+
+Some interface changes have been made. Classes that implement framework
+interfaces should update their APIs to reflect these changes.
+
+See :ref:`ChangeLog <v470-interface-changes>` for details.
+
+Method Signature Changes
+========================
+
+Some method signature changes have been made. Classes that extend framework
+classes should update their method signatures to keep LSP compatibility.
+
+See :ref:`ChangeLog <v470-method-signature-changes>` for details.
+
+Property Signature Changes
+==========================
+
+Some property type signatures have changed (for example nullable
+``Entity::$dataCaster``). If you extend these classes, update your code
+accordingly.
+
+See :ref:`ChangeLog <v470-property-signature-changes>` for details.
+
+Removed Deprecated Items
+========================
+
+Some deprecated items have been removed. If your app still uses or extends
+these APIs, update your code before upgrading.
+
+See :ref:`ChangeLog <v470-removed-deprecated-items>` for details.
+
 *************
 Project Files
 *************