[doc-en] master: PDOException::getCode(): document the int|string return type

Author: Jakub Vrana (vrana) Date: 2026-10-23T09:06:27+02:00 Commit: https://github.com/php/doc-en/commit/3aac0ba2da1e235092086965f74b9855174f9ad1 Raw diff: https://github.com/php/doc-en/commit/3aac0ba2da1e235092086965f74b9855174f9ad1.diff PDOException::getCode(): document the int|string return type It returns the SQLSTATE string, or the driver error code as int when the connection fails. Warn that it can't be passed as the code of another exception and show rethrowing with $previous instead. Based on the user note https://www.php.net/pdoexception#95812 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Changed paths: A reference/pdo/pdoexception/getcode.xml M reference/pdo/pdoexception.xml M reference/pdo/versions.xml Diff: diff --git a/reference/pdo/pdoexception.xml b/reference/pdo/pdoexception.xml index 1a3fefe4bb62..671ff801f324 100644 --- a/reference/pdo/pdoexception.xml +++ b/reference/pdo/pdoexception.xml @@ -46,6 +46,9 @@ <classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;'] and (not(@xml:id) or @xml:id != 'class.exception..code')]))"/> + <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.pdoexception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='PDOException'])"/> + <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='Exception'])"/> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Exception'])"/> @@ -68,17 +71,19 @@ <varlistentry xml:id="pdoexception.props.code"> <term><varname>code</varname></term> <listitem> - <para> - <literal>SQLSTATE</literal> error code. Use - <methodname>Exception::getCode</methodname> to access it. - </para> + <simpara> + <literal>SQLSTATE</literal> error code. + Use <methodname>PDOException::getCode</methodname> to access it. + </simpara> </listitem> </varlistentry> </variablelist> </section> </partintro> - + + &reference.pdo.entities.pdoexception; + </reference> <!-- Keep this comment at the end of the file Local variables: diff --git a/reference/pdo/pdoexception/getcode.xml b/reference/pdo/pdoexception/getcode.xml new file mode 100644 index 000000000000..6ce895b1d2c0 --- /dev/null +++ b/reference/pdo/pdoexception/getcode.xml @@ -0,0 +1,138 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> +<refentry xml:id="pdoexception.getcode" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>PDOException::getCode</refname> + <refpurpose>Gets the SQLSTATE error code</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="PDOException"> + <modifier>final</modifier> <modifier>public</modifier> <type class="union"><type>int</type><type>string</type></type><methodname>PDOException::getCode</methodname> + <void/> + </methodsynopsis> + <simpara> + Returns the exception code. + This is the inherited <methodname>Exception::getCode</methodname>, + but unlike in most other exceptions, the code is usually a <type>string</type>. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns the <literal>SQLSTATE</literal> as a five-character + <type>string</type> (for example <literal>"42S02"</literal> or + <literal>"HY000"</literal>), see <methodname>PDO::errorCode</methodname>. + </simpara> + <simpara> + If the connection fails in <methodname>PDO::__construct</methodname>, + returns the driver-specific error code as an <type>int</type> instead + (for example <literal>1045</literal> for access denied in MySQL). + </simpara> + <caution> + <simpara> + The <parameter>code</parameter> parameter of + <methodname>Exception::__construct</methodname> only accepts an + <type>int</type>, so passing this value to it when rethrowing the error as + a different exception throws a <exceptionname>TypeError</exceptionname>. + Casting it to <type>int</type> loses information + (<literal>"HY000"</literal> becomes <literal>0</literal>). + Pass the original exception as the <parameter>previous</parameter> + parameter instead. + </simpara> + </caution> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><methodname>PDOException::getCode</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$pdo = new PDO('sqlite::memory:'); + +try { + $pdo->query('SELECT * FROM missing_table'); +} catch (PDOException $e) { + var_dump($e->getCode()); +} +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +string(5) "HY000" +]]> + </screen> + </example> + <example> + <title>Rethrowing a <exceptionname>PDOException</exceptionname></title> + <programlisting role="php"> +<![CDATA[ +<?php +class DatabaseException extends RuntimeException {} + +$pdo = new PDO('sqlite::memory:'); + +try { + try { + $pdo->query('SELECT * FROM missing_table'); + } catch (PDOException $e) { + // Passing $e->getCode() as the code would throw a TypeError + throw new DatabaseException('Query failed', previous: $e); + } +} catch (DatabaseException $e) { + echo $e->getMessage(), ': ', $e->getPrevious()->getCode(), "\n"; +} +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +Query failed: HY000 +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Exception::getCode</methodname></member> + <member><methodname>Exception::getPrevious</methodname></member> + <member><methodname>PDO::errorCode</methodname></member> + <member><methodname>PDOStatement::errorCode</methodname></member> + <member><methodname>PDO::errorInfo</methodname></member> + </simplelist> + </refsect1> +</refentry> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/pdo/versions.xml b/reference/pdo/versions.xml index 55594049379d..48ebf221a441 100644 --- a/reference/pdo/versions.xml +++ b/reference/pdo/versions.xml @@ -64,6 +64,7 @@ <function name="pdostatement::setfetchmode" from="PHP 5 &gt;= 5.1.0, PHP 7, PHP 8, PECL pdo &gt;= 0.2.0"/> <function name="pdoexception" from="PHP 5 &gt;= 5.1.0, PHP 7, PHP 8"/> + <function name="pdoexception::getcode" from="PHP 5 &gt;= 5.1.0, PHP 7, PHP 8"/> <function name="pdo_cubrid dsn" from="PECL PDO_CUBRID &gt;= 8.3.0.0001"/> <function name="pdo_dblib dsn" from="PECL PDO_DBLIB &gt;= 0.9.0"/>