From 9eeeb6c1aafe0ade899ca7d98e61822367b476c3 Mon Sep 17 00:00:00 2001
From: Gary Jones <gary@gamajo.com>
Date: Mon, 4 Nov 2019 22:53:33 +0000
Subject: [PATCH] Docs: Add PostsPerPage XML doc

See #1722.
---
 WordPress/Docs/WP/PostsPerPageStandard.xml | 69 ++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 WordPress/Docs/WP/PostsPerPageStandard.xml

diff --git a/WordPress/Docs/WP/PostsPerPageStandard.xml b/WordPress/Docs/WP/PostsPerPageStandard.xml
new file mode 100644
index 0000000000..aa24f740d4
--- /dev/null
+++ b/WordPress/Docs/WP/PostsPerPageStandard.xml
@@ -0,0 +1,69 @@
+<documentation title="High Posts Per Page Limit">
+    <standard>
+    <![CDATA[
+Using "posts_per_page" or "numberposts" with the value set to an high number opens up the potential for making requests slow if the query ends up querying thousands of posts.
+
+You should always fetch the lowest number possible that still gives you the number of results you find acceptable.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: posts_per_page is not over limit (default 100).">
+        <![CDATA[
+$args = array(
+    'posts_per_page' => <em>-1</em>,
+);
+$args = array(
+    'posts_per_page' => <em>100</em>,
+);
+$args = array(
+    'posts_per_page' => <em>'10'</em>,
+);
+
+$query_args['posts_per_page'] = <em>100</em>;
+
+_query_posts( 'nopaging=1&posts_per_page=<em>50</em>' );
+        ]]>
+        </code>
+        <code title="Invalid: posts_per_page is over limit (default 100).">
+        <![CDATA[
+$args = array(
+    'posts_per_page' => <em>101</em>,
+);
+
+$query_args['posts_per_page'] = <em>200</em>;
+
+_query_posts( 'nopaging=1&posts_per_page=<em>999</em>' );
+        ]]>
+        </code>
+    </code_comparison>
+    <code_comparison>
+        <code title="Valid: numberposts is not over limit (default 100).">
+        <![CDATA[
+$args = array(
+    'numberposts' => <em>-1</em>,
+);
+$args = array(
+    'numberposts' => <em>100</em>,
+);
+$args = array(
+    'numberposts' => <em>'10'</em>,
+);
+
+$query_args['numberposts'] = <em>'-1'<em>;
+
+_query_posts( 'numberposts=<em>50</em>' );
+        ]]>
+        </code>
+        <code title="Invalid: numberposts is over limit (default 100).">
+        <![CDATA[
+$args = array(
+    'numberposts' => <em>101</em>,
+);
+
+$query_args['numberposts'] = <em>'200'</em>;
+
+_query_posts( 'numberposts=<em>999</em>' );
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>