PHP Comprehensive Coverage

.github/actions/setup/action.yml

@@ -21,7 +21,7 @@ runs:
       with:
         php-version: ${{ inputs.php-version }}
         extensions: "mongodb-${{ inputs.driver-version }}"
-        key: "extcache-v1"
+        key: "extcache-${{ inputs.driver-version }}"
 
     - name: Cache extensions
       uses: actions/cache@v4

.github/workflows/add-redirects.yml

@@ -0,0 +1,133 @@
+name: Verify Redirects
+
+on:
+  pull_request_target:
+
+jobs:
+  verify-redirects:
+    name: Verifying Redirects
+    runs-on: ubuntu-latest
+    env:
+      REDIRECTS_FILE: "pr/config/redirects"
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Check Out Base Branch
+        uses: actions/checkout@v4
+
+      - name: Checkout PR Head Branch  
+        uses: actions/checkout@v4  
+        with:  
+          token: ${{ secrets.GITHUB_TOKEN }}  
+          ref: ${{ github.event.pull_request.head.ref }}  
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          path: pr
+
+      - name: Get Changed Files
+        id: changed-files
+        uses: tj-actions/changed-files@c65cd883420fd2eb864698a825fc4162dd94482c
+        with:
+          include_all_old_new_renamed_files: true
+
+      - name: Find Missing Redirects for Renamed Files
+        id: renamed-files
+        if: steps.changed-files.outputs.renamed_files_count > 0
+        env:
+          RENAMED_FILES: ${{ steps.changed-files.outputs.all_old_new_renamed_files }}
+        run: |
+          renamed_redirects=""
+
+          for file in $RENAMED_FILES; do
+
+            # only run for .txt files
+            if [[ ! "$file" == *.txt ]]; then
+              continue
+            fi
+
+            # format old and new URLs
+            old=$(echo "$file" | cut -d',' -f1)
+            old="${old#source}"
+            old="${old%.txt}"
+            new=$(echo "$file" | cut -d',' -f2)
+            new="${new#source}"
+            new="${new%.txt}"
+
+            redirect='${prefix}/${version}'"$old"'/ -> ${base}/${version}'"$new"'/'
+
+            # if redirect not already in file, add to string to add to PR description
+            if ! grep -q "$redirect" $REDIRECTS_FILE; then
+              renamed_redirects+="<li>[&lt;v&gt;-*]: $redirect</li>"
+            fi
+          done
+
+          echo "redirects=${renamed_redirects}" >> "$GITHUB_OUTPUT"  
+
+      - name: Find Missing Redirects for Deleted Files
+        id: deleted-files
+        if: steps.changed-files.outputs.deleted_files_count > 0
+        env:
+          DELETED_FILES: ${{ steps.changed-files.outputs.deleted_files }}
+        run: |
+          deleted_redirects=""
+
+          for file in $DELETED_FILES; do
+
+            # only run for .txt files
+            if [[ ! "$file" == *.txt ]]; then
+              continue
+            fi
+
+            # format old URL
+            old=$(echo "$file" | cut -d',' -f1)
+            old="${old#source}"
+            old="${old%.txt}"
+
+            redirect='${prefix}/${version}'"$old"'/ -> ${base}/${version}/'
+
+            # escape special characters before searching for string           
+            escaped_redirect=$(printf '%s\n' "$redirect" | sed 's/[[*${}|\\]/\\&/g')
+
+            # if redirect not already in file, add to string to add to PR description
+            if ! grep -qE "${escaped_redirect}$" $REDIRECTS_FILE; then
+              deleted_redirects+="<li>[&lt;v&gt;-*]: $redirect</li>"
+            fi
+          done
+
+          echo "redirects=${deleted_redirects}" >> "$GITHUB_OUTPUT"  
+
+      - name: Build Redirect HTML
+        id: build-redirect-html
+        env:
+          RENAMED_REDIRECTS: ${{ steps.renamed-files.outputs.redirects }}
+          DELETED_REDIRECTS: ${{ steps.deleted-files.outputs.redirects }}
+        run: |
+          redirect_html=''
+          combined_redirects="${RENAMED_REDIRECTS}${DELETED_REDIRECTS}"
+
+          if [ -n "$combined_redirects" ]; then
+            redirect_html="<h3>Suggested redirects for moved, renamed, and deleted files:</h3><p><em>Replace &lt;v&gt; with the earliest backport target version</p></em>$combined_redirects"
+          fi
+
+          echo "redirect_html=${redirect_html}" >> "$GITHUB_OUTPUT"
+
+      - name: Update PR Description
+        uses: MongoCaleb/pr-description-action@4bdfe35b98f64532b419ad20b350a92546cd3aa1
+        with:
+          regex: "- \\[( |x)\\] Did you add redirects\\?.*"
+          appendContentOnMatchOnly: false
+          regexFlags: is
+          content: "- [ ] Did you add redirects?\n ${{ steps.build-redirect-html.outputs.redirect_html }}"
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check for duplicates in redirects file
+        run: |
+          if [[ -f "$REDIRECTS_FILE" ]]; then  
+            duplicates=$(sort "$REDIRECTS_FILE" | uniq -d)  
+            if [[ -n "$duplicates" ]]; then  
+              echo "Duplicate lines found in $REDIRECTS_FILE:" 
+              echo "$duplicates"  
+              exit 1 # error
+            fi
+          else  
+             "Redirects file doesn't exist. Skipping duplicate check."  
+          fi

.github/workflows/coding-standards.yml

@@ -5,6 +5,7 @@ on:
     paths:
       - "source/**/*.php"
       - ".github/workflows/*.yml"
+      - ".github/actions/**"
 
 env:
   PHP_VERSION: "8.2"

.github/workflows/static-analysis.yml

@@ -5,6 +5,7 @@ on:
     paths:
       - "source/**/*.php"
       - ".github/workflows/*.yml"
+      - ".github/actions/**"
   workflow_call:
     inputs:
       ref:

composer/composer.json

@@ -15,4 +15,4 @@
       "dealerdirect/phpcodesniffer-composer-installer": true
     }
   }
-}
+}

config/redirects

@@ -25,7 +25,7 @@ raw: ${prefix}/stable -> ${base}/current/
 # redirects in standardized docs
 [v1.20-*]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/${version}/get-started/
 [v1.20-*]: ${prefix}/${version}/tutorial/connecting/ -> ${base}/${version}/connect/
-[v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/monitoring/cluster-monitoring/
+[v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/monitoring-logging/monitoring/
 [v1.20-*]: ${prefix}/${version}/tutorial/crud/ -> ${base}/${version}/read/
 [v1.20-*]: ${prefix}/${version}/tutorial/codecs/ -> ${base}/${version}/data-formats/codecs/
 [v1.20-*]: ${prefix}/${version}/tutorial/collation/ -> ${base}/${version}/
@@ -45,7 +45,7 @@ raw: ${prefix}/stable -> ${base}/current/
 # note: this mapping does not account for all of the new pages
 [*-v1.19]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/v1.x/get-started/
 [*-v1.19]: ${prefix}/${version}/tutorial/connecting/ -> ${base}/v1.x/connect/
-[*-v1.19]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/v1.x/monitoring/cluster-monitoring/
+[*-v1.19]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/v1.x/monitoring-logging/monitoring/
 [*-v1.19]: ${prefix}/${version}/tutorial/crud/ -> ${base}/v1.x/read/
 [*-v1.19]: ${prefix}/${version}/tutorial/codecs/ -> ${base}/v1.x/data-formats/codecs/
 [*-v1.19]: ${prefix}/${version}/tutorial/collation/ -> ${base}/v1.x/
@@ -59,4 +59,38 @@ raw: ${prefix}/stable -> ${base}/current/
 [*-v1.19]: ${prefix}/${version}/tutorial/example-data/ -> ${base}/v1.x/
 [*-v1.19]: ${prefix}/${version}/tutorial/modeling-bson-data/ -> ${base}/v1.x/data-formats/modeling-bson-data/
 [*-v1.19]: ${prefix}/${version}/tutorial/stable-api/ -> ${base}/v1.x/stable-api/
-[*-v1.19]: ${prefix}/${version}/tutorial/aws-lambda/ -> ${base}/v1.x/aws-lambda/
+[*-v1.19]: ${prefix}/${version}/tutorial/aws-lambda/ -> ${base}/v1.x/aws-lambda/
+
+# comprehensive coverage redirects
+[*-master]: ${prefix}/${version}/aggregation/atlas-search/ -> ${base}/${version}/atlas-search/
+[*-master]: ${prefix}/${version}/aws-lambda/ -> ${base}/${version}/connect/aws-lambda/
+[*-master]: ${prefix}/${version}/connect/stable-api/ -> ${base}/${version}/connect/connection-options/stable-api/
+[*-master]: ${prefix}/${version}/builders/ -> ${base}/${version}/crud/builders/
+[*-master]: ${prefix}/${version}/write/bulk-write/ -> ${base}/${version}/crud/bulk-write/
+[*-master]: ${prefix}/${version}/write/delete/ -> ${base}/${version}/crud/delete/
+[*-master]: ${prefix}/${version}/write/gridfs/ -> ${base}/${version}/crud/gridfs/
+[*-master]: ${prefix}/${version}/write/insert/ -> ${base}/${version}/crud/insert/
+[*-master]: ${prefix}/${version}/read/count/ -> ${base}/${version}/crud/query/count/
+[*-master]: ${prefix}/${version}/read/cursor/ -> ${base}/${version}/crud/query/cursor/
+[*-master]: ${prefix}/${version}/read/distinct/ -> ${base}/${version}/crud/query/distinct/
+[*-master]: ${prefix}/${version}/read/project/ -> ${base}/${version}/crud/query/project/
+[*-master]: ${prefix}/${version}/read/retrieve/ -> ${base}/${version}/crud/query/retrieve/
+[*-master]: ${prefix}/${version}/read/specify-a-query/ -> ${base}/${version}/crud/query/specify-a-query/
+[*-master]: ${prefix}/${version}/read/specify-documents-to-return/ -> ${base}/${version}/crud/query/specify-documents-to-return/
+[*-master]: ${prefix}/${version}/read-write-pref/ -> ${base}/${version}/crud/read-write-pref/
+[*-master]: ${prefix}/${version}/write/replace/ -> ${base}/${version}/crud/replace/
+[*-master]: ${prefix}/${version}/write/transaction/ -> ${base}/${version}/crud/transaction/
+[*-master]: ${prefix}/${version}/write/update/ -> ${base}/${version}/crud/update/
+[*-master]: ${prefix}/${version}/data-formats/codecs/ -> ${base}/${version}/data-formats/custom-types/codecs/
+[*-master]: ${prefix}/${version}/databases-collections/time-series/ -> ${base}/${version}/data-formats/time-series/
+[*-master]: ${prefix}/${version}/read/change-streams/ -> ${base}/${version}/monitoring-logging/change-streams/
+[*-master]: ${prefix}/${version}/monitoring/cluster-monitoring/ -> ${base}/${version}/monitoring-logging/monitoring/
+[*-master]: ${prefix}/${version}/compatibility/ -> ${base}/${version}/references/compatibility/
+[*-master]: ${prefix}/${version}/whats-new/ -> ${base}/${version}/references/release-notes/
+[*-master]: ${prefix}/${version}/upgrade/ -> ${base}/${version}/references/upgrade/
+[*-master]: ${prefix}/${version}/connect/tls/ -> ${base}/${version}/security/tls/
+[*-master]: ${prefix}/${version}/aggregation/vector-search/ -> ${base}/${version}/vector-search/
+[*-master]: ${prefix}/${version}/monitoring/ -> ${base}/${version}/monitoring-logging/
+[*-master]: ${prefix}/${version}/read/ -> ${base}/${version}/crud/
+[*-master]: ${prefix}/${version}/write/ -> ${base}/${version}/crud/
+[*-master]: ${prefix}/${version}/faq/ -> ${base}/${version}/

phpcs.xml.dist

@@ -0,0 +1,119 @@
+<?xml version="1.0"?>
+<ruleset>
+    <arg name="basepath" value="." />
+    <arg name="extensions" value="php" />
+    <arg name="parallel" value="80" />
+    <arg name="cache" value=".phpcs-cache" />
+    <arg name="colors" />
+
+    <!-- Ignore warnings (n), show progress of the run (p), and show sniff names (s) -->
+    <arg value="nps"/>
+
+    <file>source</file>
+
+    <!-- Target minimum supported PHP version -->
+    <config name="php_version" value="80100"/>
+
+    <!-- ****************************************** -->
+    <!-- Import rules from doctrine/coding-standard -->
+    <!-- ****************************************** -->
+    <rule ref="Doctrine">
+        <!-- ******************************************** -->
+        <!-- Exclude sniffs we simply don't want for docs -->
+        <!-- ******************************************** -->
+        <exclude name="PSR1.Classes.ClassDeclaration.MissingNamespace" />
+        <exclude name="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly" />
+        <exclude name="Squiz.NamingConventions.ValidVariableName.MemberNotCamelCaps" />
+        <!-- Results in false positives with comments used to denote include blocks -->
+        <exclude name="SlevomatCodingStandard.ControlStructures.BlockControlStructureSpacing.IncorrectLinesCountAfterControlStructure" />
+        <exclude name="Squiz.Classes.ClassFileName.NoMatch" />
+        <!-- Results in false positives with comments used to denote include blocks before functions -->
+        <exclude name="Squiz.Commenting.FunctionComment.WrongStyle" />
+        <!-- Results in false positives with comments used to denote include blocks after functions -->
+        <exclude name="Squiz.WhiteSpace.FunctionSpacing.After" />
+        <!-- The following three excludes allow for more compact single-item array declarations -->
+        <exclude name="Squiz.Arrays.ArrayDeclaration.IndexNoNewline" />
+        <exclude name="Generic.Arrays.ArrayIndent.CloseBraceNotNewLine" />
+        <exclude name="Squiz.Arrays.ArrayDeclaration.CloseBraceNewLine" />
+
+        <!-- *********************************** -->
+        <!-- Exclude sniffs that cause BC breaks -->
+        <!-- *********************************** -->
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming" />
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousExceptionNaming" />
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming" />
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousTraitNaming" />
+
+        <!-- Can cause subtle BC breaks -->
+        <exclude name="SlevomatCodingStandard.TypeHints.DeclareStrictTypes" />
+
+
+        <!-- **************************************** -->
+        <!-- Exclude sniffs that force unwanted style -->
+        <!-- **************************************** -->
+        <exclude name="Generic.Formatting.MultipleStatementAlignment" />
+        <exclude name="Squiz.Commenting.FunctionComment.ThrowsNoFullStop" />
+        <exclude name="SlevomatCodingStandard.TypeHints.UnionTypeHintFormat.DisallowedShortNullable" />
+
+        <!-- Keep long typehints (for now) -->
+        <exclude name="PSR12.Keywords.ShortFormTypeKeywords" />
+        <exclude name="SlevomatCodingStandard.PHP.TypeCast.InvalidCastUsed" />
+        <exclude name="SlevomatCodingStandard.TypeHints.LongTypeHints" />
+
+
+        <!-- ************************************************ -->
+        <!-- Exclude sniffs that may cause functional changes -->
+        <!-- ************************************************ -->
+        <exclude name="Generic.PHP.ForbiddenFunctions.FoundWithAlternative" />
+        <exclude name="SlevomatCodingStandard.ControlStructures.DisallowYodaComparison" />
+        <exclude name="SlevomatCodingStandard.ControlStructures.EarlyExit" />
+        <exclude name="SlevomatCodingStandard.ControlStructures.UselessIfConditionWithReturn" />
+        <exclude name="SlevomatCodingStandard.Functions.StaticClosure" />
+        <exclude name="SlevomatCodingStandard.Functions.UnusedInheritedVariablePassedToClosure" />
+        <exclude name="SlevomatCodingStandard.Operators.DisallowEqualOperators" />
+
+
+        <!-- ********************************************************* -->
+        <!-- Exclude sniffs that cause a huge diff - enable separately -->
+        <!-- ********************************************************* -->
+        <exclude name="SlevomatCodingStandard.Commenting.DocCommentSpacing.IncorrectAnnotationsGroup" />
+
+
+        <!-- ********************* -->
+        <!-- Exclude broken sniffs -->
+        <!-- ********************* -->
+
+        <!-- Sniff currently broken when casting arrays, see https://github.com/squizlabs/PHP_CodeSniffer/issues/2937#issuecomment-615498860 -->
+        <exclude name="Squiz.Arrays.ArrayDeclaration.ValueNoNewline" />
+
+        <!-- Disable forbidden annotation sniff as excluding @api from the list doesn't work -->
+        <exclude name="SlevomatCodingStandard.Commenting.ForbiddenAnnotations.AnnotationForbidden" />
+    </rule>
+
+
+    <!-- **************************************** -->
+    <!-- Enable rules not enforced by Doctrine CS -->
+    <!-- **************************************** -->
+
+    <!-- Require arrow functions where possible -->
+    <rule ref="SlevomatCodingStandard.Functions.RequireArrowFunction"/>
+
+
+    <!-- ****************************************************** -->
+    <!-- Don't require annotations to specify traversable types -->
+    <!-- ****************************************************** -->
+    <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingTraversableTypeHintSpecification" />
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingTraversableTypeHintSpecification" />
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingTraversableTypeHintSpecification" />
+    </rule>
+
+    <rule ref="Generic.Files.InlineHTML.Found">
+        <exclude-pattern>source/includes/aws-lambda/index.php</exclude-pattern>
+    </rule>
+
+</ruleset>

snooty.toml

@@ -22,14 +22,14 @@ toc_landing_pages = [
     "/reference/class/MongoDBModelDatabaseInfo",
     "/reference/class/MongoDBModelIndexInfo",
     "/connect",
-    "/read",
-    "/databases-collections",
-    "/write",
+    "/connect/connection-options/",
+    "/aggregation",
+    "/data-formats",
+    "/data-formats/custom-types",
     "/indexes",
     "/security",
-    "/data-formats",
     "/upgrade",
-    "/aggregation",
+    "/security/authentication",
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"