Merge remote-tracking branch 'origin/5.next' into docs-string-agg

# Conflicts:
#	docs/en/appendices/5-4-migration-guide.md

Author: dereuromark

docs/en/appendices/5-4-migration-guide.md

@@ -45,6 +45,11 @@ version is reported as `unknown`), the header is omitted.
   has changed from `select` to `subquery`. If you need the previous behavior,
   explicitly set `'strategy' => 'select'` when defining associations.
   See [Associations](../orm/associations#has-many-associations) for more details.
+- `Model.afterSaveCommit` and `Model.afterDeleteCommit` events are now fired
+  when `save()` or `delete()` is called inside an outer transaction. Previously,
+  these events were silently suppressed. They are now deferred until the
+  outermost transaction commits, and discarded on rollback.
+  See [Table Objects](../orm/table-objects#aftersavecommit) for more details.
 
 ### Controller
 
@@ -72,6 +77,12 @@ version is reported as `unknown`), the header is omitted.
   `league/container` implementation by setting `App.container` to `cake` inside your `config/app.php`.
   See [Dependency Injection Container](../development/dependency-injection) for more details.
 
+### Collection
+
+- Added [`keys()`](../core-libraries/collections#keys) and [`values()`](../core-libraries/collections#values) methods for extracting keys or re-indexing values.
+- Added [`implode()`](../core-libraries/collections#implode) method to concatenate elements into a string.
+- Added [`when()`](../core-libraries/collections#when) and [`unless()`](../core-libraries/collections#unless) methods for conditional method chaining.
+
 ### Commands
 
 - You can use `$this->io` and `$this->args` inside your commands to access input/output and argument objects
@@ -102,6 +113,9 @@ version is reported as `unknown`), the header is omitted.
 - Added `FunctionsBuilder::stringAgg()` for portable string aggregation.
   Translates to `STRING_AGG` or `GROUP_CONCAT` per driver.
   See [Query Builder](../orm/query-builder#string-aggregation).
+- Added `Connection::afterCommit()` to register callbacks that run after the
+  outermost transaction commits. Callbacks are discarded on rollback.
+  See [Database Basics](../orm/database-basics#aftercommit) for more details.
 - Added `except()` and `exceptAll()` methods on `SelectQuery` for `EXCEPT`
   and `EXCEPT ALL` set operations. `EXCEPT ALL` is supported on PostgreSQL
   and recent MySQL/MariaDB versions; it is not supported on SQLite or SQL Server.
@@ -113,6 +127,12 @@ version is reported as `unknown`), the header is omitted.
   `Index::BRIN`, `Index::HASH`) for these access methods.
   See [Reading Indexes and Constraints](../orm/schema-system#reading-indexes-and-constraints).
 
+### Http
+
+- Added PSR-13 Link implementation with `Cake\Http\Link\Link` and `Cake\Http\Link\LinkProvider`
+  classes for hypermedia link support. Links added to responses are automatically emitted
+  as HTTP `Link` headers. See [Hypermedia Links](../controllers/request-response#hypermedia-links).
+
 ### I18n
 
 - `Number::toReadableSize()` now uses decimal units (KB = 1000 bytes) by default.
@@ -124,11 +144,9 @@ version is reported as `unknown`), the header is omitted.
   nested array format matching `contain()` syntax.
   See [Converting Request Data into Entities](../orm/saving-data#converting-request-data-into-entities).
 
-### Http
+### Testsuite
 
-- Added PSR-13 Link implementation with `Cake\Http\Link\Link` and `Cake\Http\Link\LinkProvider`
-  classes for hypermedia link support. Links added to responses are automatically emitted
-  as HTTP `Link` headers. See [Hypermedia Links](../controllers/request-response#hypermedia-links).
+- `TestCase::mockModel()` has been added to allow mocking of model classes in tests using Mockery mocks.
 
 ### Utility
 
@@ -137,12 +155,7 @@ version is reported as `unknown`), the header is omitted.
   path manipulation. See [Filesystem Utilities](../core-libraries/filesystem.md).
 - `Security::encrypt()` can now be configured to use longer keys with separate encryption and authentication keys that are derived from the provided key.
   You can set `Security.encryptWithRawKey` to enable this behavior. See [here](https://github.com/cakephp/cakephp/pull/19325) for more details.
-
-### Collection
-
-- Added [`keys()`](../core-libraries/collections#keys) and [`values()`](../core-libraries/collections#values) methods for extracting keys or re-indexing values.
-- Added [`implode()`](../core-libraries/collections#implode) method to concatenate elements into a string.
-- Added [`when()`](../core-libraries/collections#when) and [`unless()`](../core-libraries/collections#unless) methods for conditional method chaining.
+- Added `Text::mask()` method which masks a portion of a string with a repeated character. See [Text Masking](../core-libraries/text.md#text-masking) for more details.
 
 ### View
 

docs/en/core-libraries/text.md

@@ -453,4 +453,32 @@ Output:
 
     red, orange, yellow, green, blue, indigo and violet
 
+## Text Masking
+
+### Text::mask()
+
+`method` Cake\\Utility\\Text::**mask**(string $string, int $offset, ?int $length = null, string $maskCharacter = '*'): string
+
+Masks a portion of a string with a repeated character.
+
+Replaces characters starting at `$offset` for `$length` characters with `$maskCharacter`.
+If `$length` is `null`, masking continues to the end of the string.
+Negative offsets are supported and are calculated from the end of the string.
+
+```php
+$creditCardNumber = '4909090909091234';
+
+// Called as TextHelper
+echo $this->Text->mask($creditCardNumber, 0, 12, '*');
+
+// Called as Text
+use Cake\Utility\Text;
+
+echo Text::mask($creditCardNumber, 0, 12, '*');
+```
+
+Output:
+
+    ************1234
+
 <!-- end-text -->

docs/en/development/testing.md

@@ -1043,6 +1043,23 @@ In your `tearDown()` method be sure to remove the mock with:
 $this->getTableLocator()->clear();
 ```
 
+::: info Added in version 5.4
+:::
+
+If you prefer Mockery mocks you can use `mockModel()` instead of `getMockForModel()`.
+
+```php
+public function testSendingEmails(): void
+{
+    $model = $this->mockModel('EmailVerification');
+    $mock->shouldReceive('send')
+        ->once()
+        ->andReturn(true);
+
+    $model->verifyEmail('test@example.com');
+}
+```
+
 <a id="integration-testing"></a>
 
 ## Controller Integration Testing

docs/en/orm/database-basics.md

@@ -1107,6 +1107,53 @@ do the following:
 - If the closure returns `false`, a rollback will be issued.
 - If the closure executes successfully, the transaction will be committed.
 
+### afterCommit
+
+`method` Cake\\Database\\Connection::**afterCommit**(callable $callback): void
+
+You can register callbacks to run after the outermost transaction commits using
+``afterCommit()``. This is useful for deferring side effects like sending
+emails, dispatching jobs, or invalidating caches until you know the data has
+been persisted:
+
+```php
+$connection->begin();
+$connection->execute('UPDATE articles SET published = ? WHERE id = ?', [true, 2]);
+$connection->afterCommit(function () {
+    // Send notification email — only runs if the transaction commits.
+    $this->mailer->send('article-published');
+});
+$connection->commit(); // Callback fires here.
+```
+
+Callbacks are discarded if the transaction is rolled back. When nested
+transactions are in use, callbacks registered at any depth are deferred until
+the outermost transaction commits:
+
+```php
+$connection->begin();
+$connection->afterCommit(function () {
+    // This fires after the outermost commit.
+});
+
+$connection->begin(); // Nested (savepoint)
+$connection->afterCommit(function () {
+    // Also deferred to outermost commit.
+});
+$connection->commit(); // Releases savepoint — callbacks don't fire yet.
+
+$connection->commit(); // Outermost commit — both callbacks fire now.
+```
+
+If ``afterCommit()`` is called when no transaction is active, the callback
+executes immediately. This matches the semantics of the ORM's
+``Model.afterSaveCommit`` event, which also fires immediately for non-atomic
+saves.
+
+::: info Added in version 5.4.0
+`Connection::afterCommit()` was added.
+:::
+
 ## Interacting with Statements
 
 When using the lower level database API, you will often encounter statement

docs/en/orm/table-objects.md

@@ -320,8 +320,18 @@ The `Model.afterSave` event is fired after an entity is saved.
 The `Model.afterSaveCommit` event is fired after the transaction in which the
 save operation is wrapped has been committed. It's also triggered for non atomic
 saves where database operations are implicitly committed. The event is triggered
-only for the primary table on which `save()` is directly called. The event is
-not triggered if a transaction is started before calling save.
+only for the primary table on which `save()` is directly called.
+
+When `save()` is called inside an outer transaction (e.g. one started with
+`Connection::begin()`), the event is deferred until the outermost transaction
+commits. If the outer transaction is rolled back, the event is discarded. This
+ensures the event only fires after data has been persisted to the database.
+
+::: info Changed in version 5.4.0
+Previously, this event was not triggered if a transaction was started before
+calling `save()`. It is now deferred and fires after the outermost
+transaction commits.
+:::
 
 ### beforeDelete
 
@@ -342,10 +352,19 @@ The `Model.afterDelete` event is fired after an entity has been deleted.
 `method` Cake\\ORM\\Table::**afterDeleteCommit**(EventInterface $event, EntityInterface $entity, ArrayObject $options): void
 
 The `Model.afterDeleteCommit` event is fired after the transaction in which the
-delete operation is wrapped has been is committed. It's also triggered for non
+delete operation is wrapped has been committed. It's also triggered for non
 atomic deletes where database operations are implicitly committed. The event is
 triggered only for the primary table on which `delete()` is directly called.
-The event is not triggered if a transaction is started before calling delete.
+
+When `delete()` is called inside an outer transaction, the event is deferred
+until the outermost transaction commits. If the outer transaction is rolled
+back, the event is discarded.
+
+::: info Changed in version 5.4.0
+Previously, this event was not triggered if a transaction was started before
+calling `delete()`. It is now deferred and fires after the outermost
+transaction commits.
+:::
 
 ### Stopping Table Events