<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[59657] trunk/src/wp-includes: Options/Meta APIs: Document type juggling of meta data.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { white-space: pre-line; overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="https://core.trac.wordpress.org/changeset/59657">59657</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"https://core.trac.wordpress.org/changeset/59657","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>peterwilsoncc</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2025-01-17 00:10:08 +0000 (Fri, 17 Jan 2025)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>Options/Meta APIs: Document type juggling of meta data.
Document that unserialised data types are stored as strings in the database and returned as such by the meta data functions. For example, setting meta data to the integer value `1` will be returned as `"1"` when subsequently queried via `get_metadata()` and the related functions.
Props sukhendu2002, azaozz, jrf, rodrigosprimo.
Fixes ticket:61950.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludescommentphp">trunk/src/wp-includes/comment.php</a></li>
<li><a href="#trunksrcwpincludesmetaphp">trunk/src/wp-includes/meta.php</a></li>
<li><a href="#trunksrcwpincludesmssitephp">trunk/src/wp-includes/ms-site.php</a></li>
<li><a href="#trunksrcwpincludespostphp">trunk/src/wp-includes/post.php</a></li>
<li><a href="#trunksrcwpincludestaxonomyphp">trunk/src/wp-includes/taxonomy.php</a></li>
<li><a href="#trunksrcwpincludesuserphp">trunk/src/wp-includes/user.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludescommentphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/comment.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/comment.php 2025-01-16 21:03:12 UTC (rev 59656)
+++ trunk/src/wp-includes/comment.php 2025-01-17 00:10:08 UTC (rev 59657)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -432,7 +432,13 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param int $comment_id Comment ID.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $meta_key Metadata name.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and
+ * will be returned as the same type when retrieved. Other data types will
+ * be stored as strings in the database:
+ * - false is stored and retrieved as an empty string ('')
+ * - true is stored and retrieved as '1'
+ * - numbers (both integer and float) are stored and retrieved as strings
+ * Must be serializable if non-scalar.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @param bool $unique Optional. Whether the same key should not be added.
</span><span class="cx" style="display: block; padding: 0 10px"> * Default false.
</span><span class="cx" style="display: block; padding: 0 10px"> * @return int|false Meta ID on success, false on failure.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -481,6 +487,11 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * False for an invalid `$comment_id` (non-numeric, zero, or negative value).
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty array if a valid but non-existing comment ID is passed and `$single` is false.
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty string if a valid but non-existing comment ID is passed and `$single` is true.
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Note: Non-serialized values are returned as strings:
+ * - false values are returned as empty strings ('')
+ * - true values are returned as '1'
+ * - numbers are returned as strings
+ * Arrays and objects retain their original type.
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function get_comment_meta( $comment_id, $key = '', $single = false ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return get_metadata( 'comment', $comment_id, $key, $single );
</span></span></pre></div>
<a id="trunksrcwpincludesmetaphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/meta.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/meta.php 2025-01-16 21:03:12 UTC (rev 59656)
+++ trunk/src/wp-includes/meta.php 2025-01-17 00:10:08 UTC (rev 59657)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -23,7 +23,13 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * or any other object type with an associated meta table.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param int $object_id ID of the object metadata is for.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $meta_key Metadata key.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and
+ * will be returned as the same type when retrieved. Other data types will
+ * be stored as strings in the database:
+ * - false is stored and retrieved as an empty string ('')
+ * - true is stored and retrieved as '1'
+ * - numbers (both integer and float) are stored and retrieved as strings
+ * Must be serializable if non-scalar.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @param bool $unique Optional. Whether the specified metadata key should be unique for the object.
</span><span class="cx" style="display: block; padding: 0 10px"> * If true, and the object already has a value for the specified metadata key,
</span><span class="cx" style="display: block; padding: 0 10px"> * no change will be made. Default false.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -570,6 +576,11 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * or if `$meta_type` is not specified.
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty array if a valid but non-existing object ID is passed and `$single` is false.
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty string if a valid but non-existing object ID is passed and `$single` is true.
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Note: Non-serialized values are returned as strings:
+ * - false values are returned as empty strings ('')
+ * - true values are returned as '1'
+ * - numbers (both integer and float) are returned as strings
+ * Arrays and objects retain their original type.
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $value = get_metadata_raw( $meta_type, $object_id, $meta_key, $single );
</span></span></pre></div>
<a id="trunksrcwpincludesmssitephp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/ms-site.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/ms-site.php 2025-01-16 21:03:12 UTC (rev 59656)
+++ trunk/src/wp-includes/ms-site.php 2025-01-17 00:10:08 UTC (rev 59657)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -1026,7 +1026,13 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param int $site_id Site ID.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $meta_key Metadata name.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and
+ * will be returned as the same type when retrieved. Other data types will
+ * be stored as strings in the database:
+ * - false is stored and retrieved as an empty string ('')
+ * - true is stored and retrieved as '1'
+ * - numbers (both integer and float) are stored and retrieved as strings
+ * Must be serializable if non-scalar.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @param bool $unique Optional. Whether the same key should not be added.
</span><span class="cx" style="display: block; padding: 0 10px"> * Default false.
</span><span class="cx" style="display: block; padding: 0 10px"> * @return int|false Meta ID on success, false on failure.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -1071,6 +1077,11 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * False for an invalid `$site_id` (non-numeric, zero, or negative value).
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty array if a valid but non-existing site ID is passed and `$single` is false.
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty string if a valid but non-existing site ID is passed and `$single` is true.
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Note: Non-serialized values are returned as strings:
+ * - false values are returned as empty strings ('')
+ * - true values are returned as '1'
+ * - numbers (both integer and float) are returned as strings
+ * Arrays and objects retain their original type.
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function get_site_meta( $site_id, $key = '', $single = false ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return get_metadata( 'blog', $site_id, $key, $single );
</span></span></pre></div>
<a id="trunksrcwpincludespostphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/post.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/post.php 2025-01-16 21:03:12 UTC (rev 59656)
+++ trunk/src/wp-includes/post.php 2025-01-17 00:10:08 UTC (rev 59657)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -2558,7 +2558,13 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param int $post_id Post ID.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $meta_key Metadata name.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and
+ * will be returned as the same type when retrieved. Other data types will
+ * be stored as strings in the database:
+ * - false is stored and retrieved as an empty string ('')
+ * - true is stored and retrieved as '1'
+ * - numbers (both integer and float) are stored and retrieved as strings
+ * Must be serializable if non-scalar.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @param bool $unique Optional. Whether the same key should not be added.
</span><span class="cx" style="display: block; padding: 0 10px"> * Default false.
</span><span class="cx" style="display: block; padding: 0 10px"> * @return int|false Meta ID on success, false on failure.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -2615,6 +2621,11 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * False for an invalid `$post_id` (non-numeric, zero, or negative value).
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty array if a valid but non-existing post ID is passed and `$single` is false.
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty string if a valid but non-existing post ID is passed and `$single` is true.
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Note: Non-serialized values are returned as strings:
+ * - false values are returned as empty strings ('')
+ * - true values are returned as '1'
+ * - numbers (both integer and float) are returned as strings
+ * Arrays and objects retain their original type.
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function get_post_meta( $post_id, $key = '', $single = false ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return get_metadata( 'post', $post_id, $key, $single );
</span></span></pre></div>
<a id="trunksrcwpincludestaxonomyphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/taxonomy.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/taxonomy.php 2025-01-16 21:03:12 UTC (rev 59656)
+++ trunk/src/wp-includes/taxonomy.php 2025-01-17 00:10:08 UTC (rev 59657)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -1386,7 +1386,13 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param int $term_id Term ID.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $meta_key Metadata name.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and
+ * will be returned as the same type when retrieved. Other data types will
+ * be stored as strings in the database:
+ * - false is stored and retrieved as an empty string ('')
+ * - true is stored and retrieved as '1'
+ * - numbers (both integer and float) are stored and retrieved as strings
+ * Must be serializable if non-scalar.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @param bool $unique Optional. Whether the same key should not be added.
</span><span class="cx" style="display: block; padding: 0 10px"> * Default false.
</span><span class="cx" style="display: block; padding: 0 10px"> * @return int|false|WP_Error Meta ID on success, false on failure.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -1432,6 +1438,11 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * False for an invalid `$term_id` (non-numeric, zero, or negative value).
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty array if a valid but non-existing term ID is passed and `$single` is false.
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty string if a valid but non-existing term ID is passed and `$single` is true.
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Note: Non-serialized values are returned as strings:
+ * - false values are returned as empty strings ('')
+ * - true values are returned as '1'
+ * - numbers are returned as strings
+ * Arrays and objects retain their original type.
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function get_term_meta( $term_id, $key = '', $single = false ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return get_metadata( 'term', $term_id, $key, $single );
</span></span></pre></div>
<a id="trunksrcwpincludesuserphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/user.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/user.php 2025-01-16 21:03:12 UTC (rev 59656)
+++ trunk/src/wp-includes/user.php 2025-01-17 00:10:08 UTC (rev 59657)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -1151,7 +1151,13 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param int $user_id User ID.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $meta_key Metadata name.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param mixed $meta_value Metadata value. Arrays and objects are stored as serialized data and
+ * will be returned as the same type when retrieved. Other data types will
+ * be stored as strings in the database:
+ * - false is stored and retrieved as an empty string ('')
+ * - true is stored and retrieved as '1'
+ * - numbers (both integer and float) are stored and retrieved as strings
+ * Must be serializable if non-scalar.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @param bool $unique Optional. Whether the same key should not be added.
</span><span class="cx" style="display: block; padding: 0 10px"> * Default false.
</span><span class="cx" style="display: block; padding: 0 10px"> * @return int|false Meta ID on success, false on failure.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -1200,6 +1206,11 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * False for an invalid `$user_id` (non-numeric, zero, or negative value).
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty array if a valid but non-existing user ID is passed and `$single` is false.
</span><span class="cx" style="display: block; padding: 0 10px"> * An empty string if a valid but non-existing user ID is passed and `$single` is true.
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Note: Non-serialized values are returned as strings:
+ * - false values are returned as empty strings ('')
+ * - true values are returned as '1'
+ * - numbers (both integer and float) are returned as strings
+ * Arrays and objects retain their original type.
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function get_user_meta( $user_id, $key = '', $single = false ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return get_metadata( 'user', $user_id, $key, $single );
</span></span></pre>
</div>
</div>
</body>
</html>