Skip to content

Commit 2c12b6b

Browse files
rustagirrustagir
committed
JM tech review 1
1 parent 3ede497 commit 2c12b6b

File tree

2 files changed

+74
-52
lines changed

2 files changed

+74
-52
lines changed

‎source/includes/write/transaction.php

Lines changed: 30 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -9,37 +9,41 @@
99
$checking = $client->bank->checking_accounts;
1010
$saving = $client->bank->saving_accounts;
1111

12-
$accountId = '5678';
13-
$transferAmount = 1000.00;
14-
15-
$callback = function (MongoDB\Driver\Session $session)
16-
use ($checking, $saving, $receipts, $accountId, $transferAmount): void {
17-
12+
$accountId = "5678";
13+
$transferAmount = 1000.0;
14+
15+
$callback = function (MongoDB\Driver\Session $session) use (
16+
$checking,
17+
$saving,
18+
$receipts,
19+
$accountId,
20+
$transferAmount
21+
): void {
1822
$checking->updateOne(
19-
['account_id' => $accountId],
20-
['$inc' => ['balance' => -$transferAmount]],
21-
['session' => $session]
23+
["account_id" => $accountId],
24+
['$inc' => ["balance" => -$transferAmount]],
25+
["session" => $session]
2226
);
23-
27+
2428
$saving->updateOne(
25-
['account_id' => $accountId],
26-
['$inc' => ['balance' => $transferAmount]],
27-
['session' => $session]
29+
["account_id" => $accountId],
30+
['$inc' => ["balance" => $transferAmount]],
31+
["session" => $session]
2832
);
2933

30-
$summary = sprintf(
31-
"SAVINGS +%u CHECKING -%u", $transferAmount, $transferAmount
32-
);
34+
$summary = sprintf('SAVINGS +%1$u CHECKING -%1$u', $transferAmount);
3335

34-
$receipts->insertOne([
35-
'account_id' => $accountId,
36-
'summary' => $summary,
37-
'timestamp' => new MongoDB\BSON\UTCDateTime(),
38-
],
39-
['session' => $session]);
36+
$receipts->insertOne(
37+
[
38+
"account_id" => $accountId,
39+
"summary" => $summary,
40+
"timestamp" => new MongoDB\BSON\UTCDateTime(),
41+
],
42+
["session" => $session]
43+
);
4044

41-
echo 'Successfully performed transaction!' , PHP_EOL;
42-
echo 'Summary: ', $summary, PHP_EOL;
45+
echo "Successfully performed transaction!", PHP_EOL;
46+
echo "Summary: ", $summary, PHP_EOL;
4347
};
4448
// end-callback
4549

@@ -48,7 +52,7 @@
4852

4953
try {
5054
MongoDB\with_transaction($session, $callback);
51-
} catch (Exception $e) {
52-
echo 'Caught exception: ', $e->getMessage(), "\n";
55+
} catch (MongoDB\Driver\Exception\RuntimeException $e) {
56+
echo "Caught exception: ", $e->getMessage(), PHP_EOL;
5357
}
5458
// end-txn

‎source/write/transaction.txt

Lines changed: 44 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -38,29 +38,50 @@ consistent, even if the operations encounter unexpected errors.
3838

3939
When using the {+php-library+}, you can create a new session from a
4040
``MongoDB\Client`` instance. Then, you can use the resulting
41-
``MongoDB\Driver\Session`` instance to perform transactions. You can
42-
improve your app's performance by reusing your client for multiple
43-
sessions and transactions instead of instantiating a new client each
44-
time.
41+
``MongoDB\Driver\Session`` instance to perform transactions.
4542

4643
.. warning::
4744

4845
Use a ``Session`` only in operations running on the
4946
``Client`` that created it. Using a ``Session`` with a
5047
different ``Client`` results in operation errors.
5148

52-
Methods
53-
-------
49+
Transaction APIs
50+
----------------
5451

55-
Create a ``Session`` by using the ``MongoDB\Client::startSession()``
56-
method on your ``Client`` instance. The {+php-library+} provides a
57-
Convenient Transaction API to manage the transaction lifecyle. Use the
58-
``MongoDB\with_transaction()`` method to run custom callback within a
59-
transaction. The ``with_transaction()`` method starts the transaction,
60-
then either commits it or ends it if there are errors. The
61-
:ref:`php-txn-example` section of this guide demonstrates how to use
52+
In this section, you can learn about the transaction APIs provided by
53+
the {+php-library+}. Before you begin a transaction, you must create a
54+
``Session`` by using the ``MongoDB\Client::startSession()``
55+
method on your ``Client`` instance. Then, you can use either of the
56+
following APIs to perform a transaction:
57+
58+
- :ref:`php-convenient-txn`
59+
- :ref:`php-core-txn`
60+
61+
.. _php-convenient-txn:
62+
63+
Convenient API
64+
~~~~~~~~~~~~~~
65+
66+
The {+php-library+} provides a **Convenient Transaction API** to manage
67+
the transaction lifecyle. Implement this API by using the
68+
``MongoDB\with_transaction()`` function to run custom callback within a
69+
transaction. The ``with_transaction()`` function performs the following
70+
tasks:
71+
72+
- Starts the transaction
73+
- Handles errors by either ending the transaction or retrying it, such
74+
as when the operation returns a ``TransientTransactionError``
75+
- Commits the transaction
76+
77+
The :ref:`php-txn-example` section of this guide demonstrates how to use
6278
this API to perform a transaction.
6379

80+
.. _php-core-txn:
81+
82+
Core API
83+
~~~~~~~~
84+
6485
Alternatively, you can have more control over your transaction lifecyle
6586
by using the methods provided by the ``Session`` class. The
6687
following table describes these methods:
@@ -82,8 +103,9 @@ following table describes these methods:
82103

83104
* - ``commitTransaction()``
84105
- | Commits the active transaction for this session. This method returns an
85-
error if there is no active transaction for the session or the
86-
transaction was previously ended.
106+
error if there is no active transaction for the session, the
107+
transaction was previously ended, or if there is a write
108+
conflict.
87109

88110
* - ``abortTransaction()``
89111
- | Ends the active transaction for this session. This method returns an
@@ -103,8 +125,8 @@ banking transaction. The code performs the following actions:
103125
collections.
104126
- Specifies the account number and amount to be transferred between
105127
accounts.
106-
- Defines the callback function, passing the ``Session`` instance as a
107-
parameter.
128+
- Defines the callback function, which receives the ``Session`` instance
129+
as a parameter.
108130
- Updates the customer's balances to reflect the money transfer.
109131
- Records a receipt of the transaction with a timestamp.
110132
- Prints a message if the transaction committed successfully.
@@ -120,7 +142,7 @@ Then, run the following code to perform the transaction. This code
120142
completes the following actions:
121143

122144
1. Creates a session from the client by using the ``startSession()`` method.
123-
#. Calls the ``with_transaction()`` method to manage the transaction,
145+
#. Calls the ``with_transaction()`` function to manage the transaction,
124146
passing the session and the callback as parameters.
125147

126148
.. io-code-block::
@@ -173,11 +195,7 @@ guide, see the following API documentation:
173195
To learn more about the ``Session`` class and methods,
174196
see the following {+extension-short+} API documentation:
175197

176-
- `MongoDB\\Driver\\Session
177-
<{+php-manual+}/class.mongodb-driver-session.php>`__
178-
- `MongoDB\\Driver\\Session::abortTransaction()
179-
<{+php-manual+}/mongodb-driver-session.aborttransaction.php>`__
180-
- `MongoDB\\Driver\\Session::commitTransaction()
181-
<{+php-manual+}/mongodb-driver-session.committransaction.php>`__
182-
- `MongoDB\\Driver\\Session::startTransaction()
183-
<{+php-manual+}/mongodb-driver-session.starttransaction.php>`__
198+
- :php:`MongoDB\Driver\Session <mongodb-driver-session>`
199+
- :php:`MongoDB\Driver\Session::abortTransaction() <mongodb-driver-session.aborttransaction>`
200+
- :php:`MongoDB\Driver\Session::commitTransaction() <mongodb-driver-session.committransaction>`
201+
- :php:`MongoDB\Driver\Session::startTransaction() <mongodb-driver-session.starttransaction>`

0 commit comments

Comments
 (0)