Doc #52997 [NEW]: SQLite3::querySingle omits return type information

From: Operating system: PHP version: 5.3.3 Package: Documentation problem Bug Type: Documentation Problem Bug description:SQLite3::querySingle omits return type information Description: ------------ The PHP documentation for SQLite3::querySingle states querySingle will return the value of the first column for the first row/entire first row for the query or FALSE otherwise. In reality, if the query returns an empty set, either NULL (in case $entire_row = false) or an empty array is returned (in case $entire_row = true). This should be clarified, since one may infer the boolean FALSE is always returned if the value of the first column/entire first row cannot be returned for some reason. This is not true. FALSE is only returned in case there is an error executing the query. Test script: --------------- $db = new SQLite3('./test.sqlite', SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE); $db->exec('CREATE TABLE IF NOT EXISTS test (test1 TEXT, test2 TEXT, PRIMARY KEY(test1))'); $row = $db->querySingle('SELECT * FROM test'); echo "SELECT * FROM test\n"; echo 'gettype($row) : ' . gettype($row) . "\n"; echo '$row === FALSE?: ' . ($row === FALSE ? 'YES' : 'NO') . "\n"; echo '$row === NULL? : ' . ($row === NULL ? 'YES' : 'NO') . "\n\n"; $row = $db->querySingle('SELECT * FROM test', true); echo "SELECT * FROM test (entire_row = true)\n"; echo 'gettype($row) : ' . gettype($row) . "\n"; echo '$row === FALSE?: ' . ($row === FALSE ? 'YES' : 'NO') . "\n"; echo '$row === NULL? : ' . ($row === NULL ? 'YES' : 'NO') . "\n"; echo 'empty($row) : ' . (empty($row) ? 'YES' : 'NO') . "\n\n"; $row = $db->querySingle('SELECT * FROM footestbar'); echo "SELECT * FROM footestbar\n"; echo 'gettype($row) : ' . gettype($row) . "\n"; echo '$row === FALSE?: ' . ($row === FALSE ? 'YES' : 'NO') . "\n"; echo '$row === NULL? : ' . ($row === NULL ? 'YES' : 'NO') . "\n\n"; $row = $db->querySingle('SEL ECT * from test'); echo "SE LECT * FROM test\n"; echo 'gettype($row) : ' . gettype($row) . "\n"; echo '$row === FALSE?: ' . ($row === FALSE ? 'YES' : 'NO') . "\n"; echo '$row === NULL? : ' . ($row === NULL ? 'YES' : 'NO') . "\n"; Expected result: ---------------- Under " Return Values", the documentation should state: "Returns the value of the first column of results or an array of the entire first row (if entire_row is TRUE) or FALSE on failure. If the query doesn't return a result, either NULL (if entire_row is FALSE) or an empty array (if otherwise) is returned." or similar, to match the result of the script above. Actual result: -------------- SELECT * FROM test gettype($row) : NULL SELECT * FROM test (entire_row = true) gettype($row) : array empty($row) : YES Warning: SQLite3::querySingle(): Unable to prepare statement: 1, no such table: footestbar in /Users/mpontes/test.php on line 19 SELECT * FROM footestbar gettype($row) : boolean $row === FALSE?: YES Warning: SQLite3::querySingle(): Unable to prepare statement: 1, near "SEL": syntax error in /Users/mpontes/test.php on line 25 SE LECT * FROM test gettype($row) : boolean -- Edit bug report at http://bugs.php.net/bug.php?id=52997&edit=1 -- Try a snapshot (PHP 5.2): http://bugs.php.net/fix.php?id=52997&r=trysnapshot52 Try a snapshot (PHP 5.3): http://bugs.php.net/fix.php?id=52997&r=trysnapshot53 Try a snapshot (trunk): http://bugs.php.net/fix.php?id=52997&r=trysnapshottrunk Fixed in SVN: http://bugs.php.net/fix.php?id=52997&r=fixed Fixed in SVN and need be documented: http://bugs.php.net/fix.php?id=52997&r=needdocs Fixed in release: http://bugs.php.net/fix.php?id=52997&r=alreadyfixed Need backtrace: http://bugs.php.net/fix.php?id=52997&r=needtrace Need Reproduce Script: http://bugs.php.net/fix.php?id=52997&r=needscript Try newer version: http://bugs.php.net/fix.php?id=52997&r=oldversion Not developer issue: http://bugs.php.net/fix.php?id=52997&r=support Expected behavior: http://bugs.php.net/fix.php?id=52997&r=notwrong Not enough info: http://bugs.php.net/fix.php?id=52997&r=notenoughinfo Submitted twice: http://bugs.php.net/fix.php?id=52997&r=submittedtwice register_globals: http://bugs.php.net/fix.php?id=52997&r=globals PHP 4 support discontinued: http://bugs.php.net/fix.php?id=52997&r=php4 Daylight Savings: http://bugs.php.net/fix.php?id=52997&r=dst IIS Stability: http://bugs.php.net/fix.php?id=52997&r=isapi Install GNU Sed: http://bugs.php.net/fix.php?id=52997&r=gnused Floating point limitations: http://bugs.php.net/fix.php?id=52997&r=float No Zend Extensions: http://bugs.php.net/fix.php?id=52997&r=nozend MySQL Configuration Error: http://bugs.php.net/fix.php?id=52997&r=mysqlcfg