Skip to content

Commit 367a4c7

Browse files
norareidynorareidy
committed
Merge remote-tracking branch 'upstream/comp-cov' into DOCSP-47056-logging-monitoring
2 parents 094032f + b236465 commit 367a4c7

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+1320
-707
lines changed

‎.github/actions/setup/action.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ runs:
2121
with:
2222
php-version: ${{ inputs.php-version }}
2323
extensions: "mongodb-${{ inputs.driver-version }}"
24-
key: "extcache-v1"
24+
key: "extcache-${{ inputs.driver-version }}"
2525

2626
- name: Cache extensions
2727
uses: actions/cache@v4

‎.github/workflows/coding-standards.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ on:
55
paths:
66
- "source/**/*.php"
77
- ".github/workflows/*.yml"
8+
- ".github/actions/**"
89

910
env:
1011
PHP_VERSION: "8.2"

‎.github/workflows/static-analysis.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ on:
55
paths:
66
- "source/**/*.php"
77
- ".github/workflows/*.yml"
8+
- ".github/actions/**"
89
workflow_call:
910
inputs:
1011
ref:

‎phpcs.xml.dist

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
<?xml version="1.0"?>
2+
<ruleset>
3+
<arg name="basepath" value="." />
4+
<arg name="extensions" value="php" />
5+
<arg name="parallel" value="80" />
6+
<arg name="cache" value=".phpcs-cache" />
7+
<arg name="colors" />
8+
9+
<!-- Ignore warnings (n), show progress of the run (p), and show sniff names (s) -->
10+
<arg value="nps"/>
11+
12+
<file>source</file>
13+
14+
<!-- Target minimum supported PHP version -->
15+
<config name="php_version" value="80100"/>
16+
17+
<!-- ****************************************** -->
18+
<!-- Import rules from doctrine/coding-standard -->
19+
<!-- ****************************************** -->
20+
<rule ref="Doctrine">
21+
<!-- ******************************************** -->
22+
<!-- Exclude sniffs we simply don't want for docs -->
23+
<!-- ******************************************** -->
24+
<exclude name="PSR1.Classes.ClassDeclaration.MissingNamespace" />
25+
<exclude name="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly" />
26+
<exclude name="Squiz.NamingConventions.ValidVariableName.MemberNotCamelCaps" />
27+
<!-- Results in false positives with comments used to denote include blocks -->
28+
<exclude name="SlevomatCodingStandard.ControlStructures.BlockControlStructureSpacing.IncorrectLinesCountAfterControlStructure" />
29+
<exclude name="Squiz.Classes.ClassFileName.NoMatch" />
30+
<!-- Results in false positives with comments used to denote include blocks before functions -->
31+
<exclude name="Squiz.Commenting.FunctionComment.WrongStyle" />
32+
<!-- Results in false positives with comments used to denote include blocks after functions -->
33+
<exclude name="Squiz.WhiteSpace.FunctionSpacing.After" />
34+
<!-- The following three excludes allow for more compact single-item array declarations -->
35+
<exclude name="Squiz.Arrays.ArrayDeclaration.IndexNoNewline" />
36+
<exclude name="Generic.Arrays.ArrayIndent.CloseBraceNotNewLine" />
37+
<exclude name="Squiz.Arrays.ArrayDeclaration.CloseBraceNewLine" />
38+
39+
<!-- *********************************** -->
40+
<!-- Exclude sniffs that cause BC breaks -->
41+
<!-- *********************************** -->
42+
<exclude name="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming" />
43+
<exclude name="SlevomatCodingStandard.Classes.SuperfluousExceptionNaming" />
44+
<exclude name="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming" />
45+
<exclude name="SlevomatCodingStandard.Classes.SuperfluousTraitNaming" />
46+
47+
<!-- Can cause subtle BC breaks -->
48+
<exclude name="SlevomatCodingStandard.TypeHints.DeclareStrictTypes" />
49+
50+
51+
<!-- **************************************** -->
52+
<!-- Exclude sniffs that force unwanted style -->
53+
<!-- **************************************** -->
54+
<exclude name="Generic.Formatting.MultipleStatementAlignment" />
55+
<exclude name="Squiz.Commenting.FunctionComment.ThrowsNoFullStop" />
56+
<exclude name="SlevomatCodingStandard.TypeHints.UnionTypeHintFormat.DisallowedShortNullable" />
57+
58+
<!-- Keep long typehints (for now) -->
59+
<exclude name="PSR12.Keywords.ShortFormTypeKeywords" />
60+
<exclude name="SlevomatCodingStandard.PHP.TypeCast.InvalidCastUsed" />
61+
<exclude name="SlevomatCodingStandard.TypeHints.LongTypeHints" />
62+
63+
64+
<!-- ************************************************ -->
65+
<!-- Exclude sniffs that may cause functional changes -->
66+
<!-- ************************************************ -->
67+
<exclude name="Generic.PHP.ForbiddenFunctions.FoundWithAlternative" />
68+
<exclude name="SlevomatCodingStandard.ControlStructures.DisallowYodaComparison" />
69+
<exclude name="SlevomatCodingStandard.ControlStructures.EarlyExit" />
70+
<exclude name="SlevomatCodingStandard.ControlStructures.UselessIfConditionWithReturn" />
71+
<exclude name="SlevomatCodingStandard.Functions.StaticClosure" />
72+
<exclude name="SlevomatCodingStandard.Functions.UnusedInheritedVariablePassedToClosure" />
73+
<exclude name="SlevomatCodingStandard.Operators.DisallowEqualOperators" />
74+
75+
76+
<!-- ********************************************************* -->
77+
<!-- Exclude sniffs that cause a huge diff - enable separately -->
78+
<!-- ********************************************************* -->
79+
<exclude name="SlevomatCodingStandard.Commenting.DocCommentSpacing.IncorrectAnnotationsGroup" />
80+
81+
82+
<!-- ********************* -->
83+
<!-- Exclude broken sniffs -->
84+
<!-- ********************* -->
85+
86+
<!-- Sniff currently broken when casting arrays, see https://github.com/squizlabs/PHP_CodeSniffer/issues/2937#issuecomment-615498860 -->
87+
<exclude name="Squiz.Arrays.ArrayDeclaration.ValueNoNewline" />
88+
89+
<!-- Disable forbidden annotation sniff as excluding @api from the list doesn't work -->
90+
<exclude name="SlevomatCodingStandard.Commenting.ForbiddenAnnotations.AnnotationForbidden" />
91+
</rule>
92+
93+
94+
<!-- **************************************** -->
95+
<!-- Enable rules not enforced by Doctrine CS -->
96+
<!-- **************************************** -->
97+
98+
<!-- Require arrow functions where possible -->
99+
<rule ref="SlevomatCodingStandard.Functions.RequireArrowFunction"/>
100+
101+
102+
<!-- ****************************************************** -->
103+
<!-- Don't require annotations to specify traversable types -->
104+
<!-- ****************************************************** -->
105+
<rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint">
106+
<exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingTraversableTypeHintSpecification" />
107+
</rule>
108+
<rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint">
109+
<exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingTraversableTypeHintSpecification" />
110+
</rule>
111+
<rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint">
112+
<exclude name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingTraversableTypeHintSpecification" />
113+
</rule>
114+
115+
<rule ref="Generic.Files.InlineHTML.Found">
116+
<exclude-pattern>source/includes/aws-lambda/index.php</exclude-pattern>
117+
</rule>
118+
119+
</ruleset>

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ toc_landing_pages = [
2828
"/indexes",
2929
"/security",
3030
"/upgrade",
31+
"/security/authentication",
3132
]
3233

3334
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

‎source/connect/connection-options.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ The following example shows how to use the ``$uriOptions`` parameter of the
6767
:copyable: true
6868
:start-after: // start-client-options
6969
:end-before: // end-client-options
70-
:emphasize-lines: 5-8, 11
70+
:emphasize-lines: 6-9, 12
7171

7272
.. note::
7373

@@ -248,6 +248,8 @@ Authentication Options
248248
To learn about the authentication options available in the {+driver-short+}, see
249249
:ref:`Authentication Mechanisms. <php-auth>`
250250

251+
.. _php-selection-discovery-options:
252+
251253
Server Selection and Discovery Options
252254
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
253255

‎source/connect/connection-options/stable-api.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ The following code example shows how to specify {+stable-api+} version 1:
5656
:copyable: true
5757
:start-after: // start-specify-v1
5858
:end-before: // end-specify-v1
59-
:emphasize-lines: 3-4
59+
:emphasize-lines: 3
6060

6161
.. note::
6262

‎source/crud/read-write-pref.txt

Lines changed: 41 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,7 @@ This section shows how to further customize your read operation
208208
settings in the following ways:
209209

210210
- :ref:`Apply a tag set <php-tag-sets>`
211-
- :ref:`Specify a local threshold <php-local-threshold>`
211+
- :ref:`Configure load balancing behavior <php-load-balancing>`
212212

213213
.. _php-tag-sets:
214214

@@ -241,19 +241,51 @@ to prefer reads from secondary replica set members in the following order:
241241
:start-after: start-tag-set
242242
:end-before: end-tag-set
243243

244+
.. _php-load-balancing:
245+
246+
Load Balancing
247+
~~~~~~~~~~~~~~
248+
249+
When connecting to a sharded cluster or a replica set, the {+library-short+} uses
250+
**load balancing** to handle read and write requests. Load balancing allows the library to
251+
distribute these requests across multiple servers to avoid overwhelming
252+
any one server and ensure optimal performance.
253+
254+
When connecting to a sharded cluster, the {+library-short+} determines the closest ``mongos``
255+
instance by calculating which one has the lowest network round-trip time. Then, the library
256+
determines the latency window by adding this ``mongos``'s average round-trip time to the
257+
:ref:`localThresholdMS value <php-local-threshold>`. The library load balances requests
258+
across up to two random ``mongos`` instances that fall within the latency window. For each request,
259+
the library chooses the server with the lower operation load by determining its ``operationCount``
260+
value.
261+
262+
When connecting to a replica set, the {+library-short+} first selects replica set members
263+
according to your read preference. Then, the library follows the same process as
264+
described in the preceding paragraph. After calculating the latency window, the library
265+
selects up to two random replica set members that fall within the window and chooses
266+
the member with the lower ``operationCount`` value to receive the request.
267+
268+
.. tip::
269+
270+
To learn more about load balancing, see :manual:`Sharded Cluster Balancer
271+
</core/sharding-balancer-administration/>` in the {+mdb-server+} manual.
272+
273+
To learn how to customize the library's server selection behavior, see
274+
:ref:`php-selection-discovery-options` in the Specify Connection Options guide.
275+
244276
.. _php-local-threshold:
245277

246278
Local Threshold
247-
~~~~~~~~~~~~~~~
279+
```````````````
248280

249-
If multiple replica-set members match the read preference and tag sets you specify,
250-
the {+php-library+} reads from the nearest replica-set members, chosen according to
251-
their ping time.
281+
The {+library-short+} uses the local threshold value to calculate the
282+
latency window for server selection. This value determines the servers
283+
that are eligible to receive read and write requests.
252284

253-
By default, the library uses only members whose ping times are within 15 milliseconds
254-
of the nearest member for queries. To distribute reads between members with
255-
higher latencies, pass an options array to the ``MongoDB\Client`` constructor that
256-
sets the ``localThresholdMS`` option.
285+
By default, the library uses only ``mongos`` instances or replica set members whose
286+
ping times are within 15 milliseconds of the nearest server. To
287+
distribute reads among servers with higher latencies, pass an options array to
288+
the ``MongoDB\Client`` constructor that sets the ``localThresholdMS`` option.
257289

258290
The following example specifies a local threshold of 35 milliseconds:
259291

‎source/crud/transaction.txt

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,37 @@ When using the {+php-library+}, you can create a new session from a
4646
``Client`` that created it. Using a ``Session`` with a
4747
different ``Client`` results in operation errors.
4848

49+
.. _php-causal-consistency:
50+
51+
Causal Consistency
52+
~~~~~~~~~~~~~~~~~~
53+
54+
.. sharedinclude:: dbx/causal-consistency.rst
55+
56+
.. replacement:: insert-one-method
57+
58+
``MongoDB\Collection::insertOne()``
59+
60+
.. replacement:: update-one-method
61+
62+
``MongoDB\Collection::updateOne()``
63+
64+
.. replacement:: find-one-method
65+
66+
``MongoDB\Collection::findOne()``
67+
68+
.. replacement:: delete-one-method
69+
70+
``MongoDB\Collection::deleteOne()``
71+
72+
.. replacement:: majority-rc
73+
74+
``majority``
75+
76+
.. replacement:: majority-wc
77+
78+
``majority``
79+
4980
Transaction APIs
5081
----------------
5182

0 commit comments

Comments
 (0)