incorrect (and confusing) DocBlock for get_page_by_title()

[pbiron]

The DocBlock of ​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 get_page_by_title() is:

$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 ​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.

[pbiron]

this was discussed in ​slack.