From 01cb1ee33eb324ae3fcf95266d0d713af9fd00f7 Mon Sep 17 00:00:00 2001
From: Yoshinari Takaoka <mumumu@mumumu.org>
Date: Fri, 3 Nov 2023 04:59:12 +0900
Subject: [PATCH 1/4] Added json_validate function description.

---
 reference/json/functions/json-validate.xml | 140 +++++++++++++++++++++
 reference/json/versions.xml                |   1 +
 2 files changed, 141 insertions(+)
 create mode 100644 reference/json/functions/json-validate.xml

diff --git a/reference/json/functions/json-validate.xml b/reference/json/functions/json-validate.xml
new file mode 100644
index 000000000000..5f8cbe428dcc
--- /dev/null
+++ b/reference/json/functions/json-validate.xml
@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="function.json-validate" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>json_validate</refname>
+  <refpurpose>Validates a JSON string</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>bool</type><methodname>json_validate</methodname>
+   <methodparam><type>string</type><parameter>json</parameter></methodparam>
+   <methodparam><type>int</type><parameter>depth</parameter><initializer>512</initializer></methodparam>
+   <methodparam><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
+  </methodsynopsis>
+  <para>
+   Check if a specified string contains a valid json.
+   Errors during validation can be fetched by using
+   <function>json_last_error</function> and/or
+   <function>json_last_error_msg</function>.
+  </para>
+  <para>
+   It's guaranteed that the json valid in <function>json_validate</function>
+   is also valid in <function>json_decode</function>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>json</parameter></term>
+     <listitem>
+      <para>
+       The json string being analyzed.
+      </para>
+      <para>
+       This function only works with UTF-8 encoded strings.
+      </para>
+      &json.implementation.superset;
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>depth</parameter></term>
+     <listitem>
+      <para>
+       Maximum nesting depth of the structure being decoded.
+       The value must be greater than <literal>0</literal>,
+       and less than or equal to <literal>2147483647</literal>.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>flags</parameter></term>
+     <listitem>
+      <para>
+       Bitmask of
+       <constant>JSON_INVALID_UTF8_IGNORE</constant>.
+       The behaviour of these constants is described on the
+       <link linkend="json.constants">JSON constants</link> page.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns &true; if the string passed contains a valid json, otherwise
+   returns &false;.
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   If <parameter>depth</parameter> is outside the allowed range,
+   a <classname>ValueError</classname> is thrown.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>json_validate</function> examples</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(json_validate('{ "test": { "foo": "bar" } }'));
+var_dump(json_validate('{ "": "": "" } }'));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+bool(true)
+bool(false)
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>json_decode</function></member>
+    <member><function>json_last_error</function></member>
+    <member><function>json_last_error_msg</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/json/versions.xml b/reference/json/versions.xml
index 061749a6b23d..1fbb43574adb 100644
--- a/reference/json/versions.xml
+++ b/reference/json/versions.xml
@@ -6,6 +6,7 @@
 <versions>
  <function name='json_decode' from='PHP 5 &gt;= 5.2.0, PHP 7, PHP 8, PECL json &gt;= 1.2.0'/>
  <function name='json_encode' from='PHP 5 &gt;= 5.2.0, PHP 7, PHP 8, PECL json &gt;= 1.2.0'/>
+ <function name='json_validate' from='PHP 8 &gt;= 8.3.0'/>
  <function name='json_last_error' from='PHP 5 &gt;= 5.3.0, PHP 7, PHP 8'/>
  <function name='json_last_error_msg' from='PHP 5 &gt;= 5.5.0, PHP 7, PHP 8'/>
 

From 4a3e37a0d3c54f9087b926a27bb9b265b1fc877a Mon Sep 17 00:00:00 2001
From: Yoshinari Takaoka <mumumu@mumumu.org>
Date: Mon, 6 Nov 2023 20:09:24 +0900
Subject: [PATCH 2/4] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>
---
 reference/json/functions/json-validate.xml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/reference/json/functions/json-validate.xml b/reference/json/functions/json-validate.xml
index 5f8cbe428dcc..be9a53063ef3 100644
--- a/reference/json/functions/json-validate.xml
+++ b/reference/json/functions/json-validate.xml
@@ -3,7 +3,7 @@
 <refentry xml:id="function.json-validate" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>json_validate</refname>
-  <refpurpose>Validates a JSON string</refpurpose>
+  <refpurpose>Checks if a string contains valid JSON</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -34,7 +34,7 @@
      <term><parameter>json</parameter></term>
      <listitem>
       <para>
-       The json string being analyzed.
+       The string to validate.
       </para>
       <para>
        This function only works with UTF-8 encoded strings.
@@ -70,7 +70,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns &true; if the string passed contains a valid json, otherwise
+   Returns &true; if the given string is syntactically valid JSON, otherwise
    returns &false;.
   </para>
  </refsect1>

From f337a4308154f724db190702f40108e9a86ca959 Mon Sep 17 00:00:00 2001
From: Yoshinari Takaoka <mumumu@mumumu.org>
Date: Mon, 6 Nov 2023 20:13:42 +0900
Subject: [PATCH 3/4] Apply suggestions from code review in description part.

---
 reference/json/functions/json-validate.xml | 30 ++++++++++++++++++----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/reference/json/functions/json-validate.xml b/reference/json/functions/json-validate.xml
index be9a53063ef3..8b47010ea3c7 100644
--- a/reference/json/functions/json-validate.xml
+++ b/reference/json/functions/json-validate.xml
@@ -15,15 +15,35 @@
    <methodparam><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Check if a specified string contains a valid json.
-   Errors during validation can be fetched by using
-   <function>json_last_error</function> and/or
+   Returns whether the given &string; is syntactically valid JSON.
+   If <function>json_validate</function> returns &true;, <function>json_decode</function>
+   will successfully decode the given string when using the same
+   <parameter>depth</parameter> and <parameter>flags</parameter>.
+  </para>
+  <para>
+   If <function>json_validate</function> returns &false;, the cause
+   can be retrieved using <function>json_last_error</function> and
    <function>json_last_error_msg</function>.
   </para>
   <para>
-   It's guaranteed that the json valid in <function>json_validate</function>
-   is also valid in <function>json_decode</function>.
+   <function>json_validate</function> uses less memory than
+   <function>json_decode</function> if the decoded JSON payload is
+   not used, because it does not need to build the array or
+   object structure containing the payload.
   </para>
+  <caution>
+   <para>
+    Calling <function>json_validate</function> immediately before
+    <function>json_decode</function> will unnecessarily parse the string
+    twice, as <function>json_decode</function> implicitly performs
+    validation during decoding.
+   </para>
+   <para>
+    <function>json_validate</function> should therefore only be used
+    if the decode JSON payload is not immediately used and knowing whether
+    the string contains valid JSON is needed.
+   </para>
+  </caution>
  </refsect1>
 
  <refsect1 role="parameters">

From d9f89f7c195b29153d9dded6f737ac360ddc0b43 Mon Sep 17 00:00:00 2001
From: Yoshinari Takaoka <mumumu@mumumu.org>
Date: Wed, 15 Nov 2023 03:18:23 +0900
Subject: [PATCH 4/4] fixed flags parameter description.

---
 reference/json/functions/json-validate.xml | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/reference/json/functions/json-validate.xml b/reference/json/functions/json-validate.xml
index 8b47010ea3c7..f45929ae944a 100644
--- a/reference/json/functions/json-validate.xml
+++ b/reference/json/functions/json-validate.xml
@@ -76,10 +76,9 @@
      <term><parameter>flags</parameter></term>
      <listitem>
       <para>
-       Bitmask of
-       <constant>JSON_INVALID_UTF8_IGNORE</constant>.
-       The behaviour of these constants is described on the
-       <link linkend="json.constants">JSON constants</link> page.
+       Currently only
+       <constant>JSON_INVALID_UTF8_IGNORE</constant>
+       is accepted.
       </para>
      </listitem>
     </varlistentry>