Doc #63845 [Asn]: Misleading example code
Edit report at https://bugs.php.net/bug.php?id=63845&edit=1
ID: 63845
User updated by: kander at gmail dot com
Reported by: kander at gmail dot com
Summary: Misleading example code
Status: Assigned
Type: Documentation Problem
Package: Documentation problem
PHP Version: 5.4.10
Assigned To: googleguy
Block user comment: N
Private report: N
New Comment:
I'm not sure your comment covers the behaviour of PDO::__construct fully. You
point out that its behavior is a
combination of always throwing an exception, and observing PDO's default error
mode of PDO::ERRMODE_SILENT.
However what I'm seeing is that in addition to throwing the exception, it also
raises a regular PHP warning. This
means that the error mode is not yet respected during the construction phase.
Following the examples in the manual
(wrapping the constructor in a try/catch block) leads to these warnings not
being handled properly in case of a
connection failure.
Previous Comments:
------------------------------------------------------------------------
[2012-12-24 23:35:06] googleguy@php.net
While I can understand that you may feel the example is misleading, the information you're
asking for is
documented in the PDO::__construct() method page at http://php.net/pdo.construct.php#refsect1-pdo.construct-
errors. So it's incomplete, but not really misleading the user since the behavior is correct.
The Errors/Exceptions section of that page does state "PDO::__construct() throws a PDOException
if the
attempt to connect to the requested database fails.", which by itself may seem confusing until
coupled with
the first line of the second paragraph on the page http://php.net/pdo.error-handling where it is stated
that
PDO::ERRMODE_SILENT is the default error mode for PDO. Meaning that while the construct will always
throw an
exception if the connection fails PDO is by default not going to throw exceptions from anywhere else
unless
you specifically put it in exception mode.
This could certainly be clarified further in the "Errors and error handling" page for PDO.
I too found it a
bit confusing at first. So this is a good point. I will assign this ticket to myself and review the
page for
better examples and to reiterate that PDO will throw an exception from the construct if the
connection
fails.
------------------------------------------------------------------------
[2012-12-24 10:08:01] kander at gmail dot com
Description:
------------
---
From manual page: http://www.php.net/pdo.error-handling
---
The example presented does not match the actual behavior. Since setting the error
mode happens AFTER the construction of the object, it has no influence on what
happens during the construction of the object.
In fact, PDO always (as far as I can see) throws an exception AND emits a warning
upon connection failure. Only after that does setting the error mode influence the
behavior.
Test script:
---------------
<?php
// Literally the example as presented on the manual page, with comments.
$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';
try {
// Exception is thrown and warning is raised:
$dbh = new PDO($dsn, $user, $password);
// We never get to the next line:
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
} catch (PDOException $e) {
// Instead, we end up handling the exception.
echo 'Connection failed: ' . $e->getMessage();
}
?>
Expected result:
----------------
I expect the manual to explain that PDO::__construct() always throws an exception
and raises a warning, and that only behavior subsequent to the setAttribute call
is affected (obviously). A recommendation on how to handle connection errors would
be appreciated.
Actual result:
--------------
See the test script's comments.
------------------------------------------------------------------------
--
Edit this bug report at https://bugs.php.net/bug.php?id=63845&edit=1
Thread (5 messages)