From: Seamus Lee <seamuslee001@gmail.com>
Date: Sun, 3 Nov 2019 06:20:31 +0000 (+1100)
Subject: [NFC] Update Doc block as per Patrick
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=dc7c2d3eb782aa439784f26ac44bffd2e51f77c6;p=civicrm-core.git

[NFC] Update Doc block as per Patrick
---

diff --git a/CRM/Utils/String.php b/CRM/Utils/String.php
index 3dacacf16e..6e53d00776 100644
--- a/CRM/Utils/String.php
+++ b/CRM/Utils/String.php
@@ -940,11 +940,21 @@ class CRM_Utils_String {
   }
 
   /**
-   * Use xkerman/restricted-unserialize to unserialize a string of data.
+   * Safely unserialize a string of scalar or array values (but not objects!)
+   *
+   * Use `xkerman/restricted-unserialize` to unserialize strings using PHP's
+   * serialization format. `restricted-unserialize` works like PHP's built-in
+   * `unserialize` function except that it does not deserialize object instances,
+   * making it immune to PHP Object Injection {@see https://www.owasp.org/index.php/PHP_Object_Injection}
+   * vulnerabilities.
+   *
+   * Note: When dealing with user inputs, it is generally recommended to use
+   * safe, standard data interchange formats such as JSON rather than PHP's
+   * serialization format when dealing with user input.
+   *
    * @param string|NULL $string
    *
    * @return mixed
-   * @throws CRM_Core_Exception
    */
   public static function unserialize($string) {
     if (!is_string($string)) {
@@ -956,6 +966,6 @@ class CRM_Utils_String {
     catch (UnserializeFailedException $e) {
       return FALSE;
     }
-  } 
+  }
 
 }