The current API reference for node_load says:

Return value
A fully-populated node object.

But it should really say:

Return value
A fully-populated node object representing the first matching node if one is found, or boolean true otherwise. 

In case the array form for $param is used and does not uniquely specify a node, the first matching node will be returned, and can vary from one call to the next.

Why "can vary" ? Because in case of a non-unique node specification in $param, the query used does not include any ORDER BY clause, so there is no guarantee of reproducible results.

CommentFileSizeAuthor
#4 node_load_doc.patch2.8 KBfgm
#1 comment_return_value.patch856 bytesXano
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Xano’s picture

Project: Documentation » Drupal core
Version: » 7.x-dev
Component: Documentation in CVS » node.module
Assigned: Unassigned » Xano
Priority: Normal » Minor
Status: Active » Needs review
FileSize
856 bytes

Since only core maintainers are allowed to edit core files I moved this issue to the Drupal project.

The attached patch will update the comments with the description mentioned above.

Anonymous’s picture

Status: Needs review » Needs work

The last submitted patch failed testing.

andrewfn’s picture

I wrote some code to test this and it seems that the return value is FALSE if no node is found. Inspecting the code indicates that this would be the case.
It seems rather important that this should be documented on http://api.drupal.org/api/function/node_load
Is this the right place for an issue regarding api.drupal.org?

fgm’s picture

Status: Needs work » Needs review
FileSize
2.8 KB

This is indeed FALSE, not TRUE. Dunno what I was thinking when I typed this.

Here is the updated patch.

catch’s picture

Status: Needs review » Needs work

This isn't correct. $vid defaults to array() when empty, but only a an int $vid can be put there for the conditions to be valid. Maybe we should default to NULL there though to make this clearer.

fgm’s picture

@catch: it looks like your remark relates to the implementation as pertaining to the arguments, not the result documentation, does it not ?

  $vid = isset($vid) ? array('vid' => $vid) : NULL;

should likely be:

  $vid = is_int($vid) ? array('vid' => $vid) : NULL;

but this wouldn't relate to this patch.

catch’s picture

Sorry,forgot to paste the relevant comment:

+ *   In case the array form for $param is used and does not uniquely specify a
+ *   node, the first matching node will be returned, and can vary from one call
+ *   to the next.

node_load() always gives you a unique node, or node revision - since it never, ever takes an array.

fgm’s picture

Version: 7.x-dev » 6.x-dev
Status: Needs work » Needs review

That was true in versions until 6.x, for which I created this documentation issue, but you're right: it's no longer true in 7.x: $param doesn't even exist any longer.

Resetting to 6.x since this is where the error is. Of course, the patch is not applicable.

valthebald’s picture

Status: Needs review » Needs work

I think current documentation describes $param correctly:

  elseif (is_array($param)) {
    // Turn the conditions into a query.
    foreach ($param as $key => $value) {
      $cond[] = 'n.'. db_escape_table($key) ." = '%s'";
      $arguments[] = $value;
    }
    $cond = implode(' AND ', $cond);
  }

so, $param really be an array

Xano’s picture

Assigned: Xano » Unassigned

Status: Needs work » Closed (outdated)

Automatically closed because Drupal 6 is no longer supported. If the issue verifiably applies to later versions, please reopen with details and update the version.