[wp-trac] [WordPress Trac] #53495: incorrect (and confusing) DocBlock for get_page_by_title()

[WordPress Trac]

#53495: incorrect (and confusing) DocBlock for get_page_by_title()
--------------------------+-----------------------------
 Reporter:  pbiron        |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  Query         |    Version:  5.3
 Severity:  normal        |   Keywords:  needs-patch
  Focuses:  docs          |
--------------------------+-----------------------------
 The DocBlock of
 [https://developer.wordpress.org/reference/functions/get_page_by_title/
 get_page_by_title()] says:

 > If more than one post uses the same title, the post with the smallest ID
 will be returned. Be careful: in case of more than one post having the
 same title, it will check the oldest publication date, not the smallest
 ID.

 That description was added in [45779].

 Besides the fact that the text after `Be careful:` seems to contradict
 that the statement that `the post with the smallest ID will be returned`,
 there actually is no guarentee that if there is more than 1 post with the
 same title that the one with the smallest ID will be returned.

 The query performed by [https://core.trac.wordpress.org/browser/trunk/src
 /wp-includes/post.php#L5534 get_page_by_title()] is:

 {{{#!php
 $sql = $wpdb->prepare(
         "
         SELECT ID
         FROM $wpdb->posts
         WHERE post_title = %s
         AND post_type = %s
 ",
         $page_title,
         $post_type
 );
 }}}

 (with a slight mod if an array of post types is passed).

 Since there is no `ORDER BY` clause in that query, if there are more than
 1 posts with the same title the order in which they are returned is not
 defined by SQL (i.e., is implemented dependent).

 The SQL-92 spec [http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt
 explicitly states]:

 > General Rules
 >
 > 1) All General Rules of Subclause 7.10, "<query expression>", apply
 > to the <direct select statement: multiple rows>.
 >
 > 2) Let Q be the result of the <query expression>.
 >
 > 3) If Q is empty, then a completion condition is raised: no data.
 >
 > 4) If an <order by clause> is not specified, then the ordering of
 > the rows of Q is implementation-dependent.

 As far as I can tell, no later revisions of the SQL spec are available for
 free on the web, so I don't know if anything has changed in the what the
 language says happens in the absense of an `ORDER BY` clause

 I've looked through the MySQL and Maria DB docs for an explicit statement
 that says as much and haven't been able to find one.

 But I think the DocBlock should be changed to say something like:

 > If more than one post uses the same title, which of the multiple posts
 is returned is not defined.

 though I'm not completely happy with that wording, and welcome other
 suggestions.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/53495>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform