[doc-en] master: ext/pdo_sqlite: document the PHP 8.5 additions and behaviour changes (#5818)

From: Date: Tue, 01 Sep 2026 13:42:08 +0000
Subject: [doc-en] master: ext/pdo_sqlite: document the PHP 8.5 additions and behaviour changes (#5818)
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-23689@lists.php.net to get a copy of this message
Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-01T15:42:05+02:00 Commit: https://github.com/php/doc-en/commit/eff8e0d4dd463ae6bd387f304effeaf3d5ce44d5 Raw diff: https://github.com/php/doc-en/commit/eff8e0d4dd463ae6bd387f304effeaf3d5ce44d5.diff ext/pdo_sqlite: document the PHP 8.5 additions and behaviour changes (#5818) Changed paths: A reference/pdo_sqlite/pdo/sqlite/setauthorizer.xml M reference/pdo/pdo/quote.xml M reference/pdo_sqlite/configure.xml M reference/pdo_sqlite/pdo-sqlite.xml M reference/pdo_sqlite/pdo/sqlite/createcollation.xml M reference/pdo_sqlite/versions.xml Diff: diff --git a/reference/pdo/pdo/quote.xml b/reference/pdo/pdo/quote.xml index 80f70a0d7d79..d969694d6a23 100644 --- a/reference/pdo/pdo/quote.xml +++ b/reference/pdo/pdo/quote.xml @@ -78,6 +78,31 @@ </simpara> </refsect1> + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.5.0</entry> + <entry> + When using the SQLite driver, a <exceptionname>PDOException</exceptionname> is + now thrown or a warning is emitted, depending on the error mode, if the + <parameter>string</parameter> contains a null byte; previously the + string was silently truncated at the null byte. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/pdo_sqlite/configure.xml b/reference/pdo_sqlite/configure.xml index ad4abe99e484..1c718138d52b 100644 --- a/reference/pdo_sqlite/configure.xml +++ b/reference/pdo_sqlite/configure.xml @@ -2,14 +2,15 @@ <!-- $Revision$ --> <section xml:id="ref.pdo-sqlite.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> &reftitle.install; - <para> + <simpara> The PDO_SQLITE PDO driver is enabled by default. To disable, <option role="configure">--without-pdo-sqlite[=DIR]</option> may be used, where the optional <literal>[=DIR]</literal> is the sqlite base install directory. - As of PHP 7.4.0 <link xlink:href="&url.sqlite;">libsqlite</link> ≥ 3.5.0 is required. + As of PHP 7.4.0 <link xlink:href="&url.sqlite;">libsqlite</link> ≥ 3.5.0 is required, + and as of PHP 8.5.0 libsqlite ≥ 3.7.17 is required. Formerly, the bundled libsqlite could have been used instead, and was the default, if <literal>[=DIR]</literal> has been omitted. - </para> + </simpara> <note> <title>Additional setup on Windows as of PHP 7.4.0</title> <para> diff --git a/reference/pdo_sqlite/pdo-sqlite.xml b/reference/pdo_sqlite/pdo-sqlite.xml index fde09db84d8a..f58e1aa8b3cd 100644 --- a/reference/pdo_sqlite/pdo-sqlite.xml +++ b/reference/pdo_sqlite/pdo-sqlite.xml @@ -96,6 +96,78 @@ <type>int</type> <varname linkend="pdo-sqlite.constants.attr-extended-result-codes">Pdo\Sqlite::ATTR_EXTENDED_RESULT_CODES</varname> </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.attr-busy-statement">Pdo\Sqlite::ATTR_BUSY_STATEMENT</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.attr-explain-statement">Pdo\Sqlite::ATTR_EXPLAIN_STATEMENT</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.explain-mode-prepared">Pdo\Sqlite::EXPLAIN_MODE_PREPARED</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.explain-mode-explain">Pdo\Sqlite::EXPLAIN_MODE_EXPLAIN</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.explain-mode-explain-query-plan">Pdo\Sqlite::EXPLAIN_MODE_EXPLAIN_QUERY_PLAN</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.attr-transaction-mode">Pdo\Sqlite::ATTR_TRANSACTION_MODE</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.transaction-mode-deferred">Pdo\Sqlite::TRANSACTION_MODE_DEFERRED</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.transaction-mode-immediate">Pdo\Sqlite::TRANSACTION_MODE_IMMEDIATE</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.transaction-mode-exclusive">Pdo\Sqlite::TRANSACTION_MODE_EXCLUSIVE</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.ok">Pdo\Sqlite::OK</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.deny">Pdo\Sqlite::DENY</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>const</modifier> + <type>int</type> + <varname linkend="pdo-sqlite.constants.ignore">Pdo\Sqlite::IGNORE</varname> + </fieldsynopsis> <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.pdo-sqlite')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Pdo\\Sqlite'])"/> @@ -160,8 +232,175 @@ </simpara> </listitem> </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.attr-busy-statement"> + <term><constant>Pdo\Sqlite::ATTR_BUSY_STATEMENT</constant></term> + <listitem> + <simpara> + A read-only statement attribute, retrieved with + <methodname>PDOStatement::getAttribute</methodname>, which is &true; if + the statement has been executed and still has a pending row, and &false; + otherwise. + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.attr-explain-statement"> + <term><constant>Pdo\Sqlite::ATTR_EXPLAIN_STATEMENT</constant></term> + <listitem> + <simpara> + A statement attribute controlling the explain mode, set with + <methodname>PDOStatement::setAttribute</methodname>. Possible values are + <constant>Pdo\Sqlite::EXPLAIN_MODE_PREPARED</constant>, + <constant>Pdo\Sqlite::EXPLAIN_MODE_EXPLAIN</constant>, and + <constant>Pdo\Sqlite::EXPLAIN_MODE_EXPLAIN_QUERY_PLAN</constant>. + A <exceptionname>ValueError</exceptionname> is thrown if PHP has been compiled + against a libsqlite older than 3.43.0. + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.explain-mode-prepared"> + <term><constant>Pdo\Sqlite::EXPLAIN_MODE_PREPARED</constant></term> + <listitem> + <simpara> + Value for <constant>Pdo\Sqlite::ATTR_EXPLAIN_STATEMENT</constant>: + returns the statement as prepared (no explanation). + Available as of PHP 8.5.0, when compiled against libsqlite &gt;= 3.43.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.explain-mode-explain"> + <term><constant>Pdo\Sqlite::EXPLAIN_MODE_EXPLAIN</constant></term> + <listitem> + <simpara> + Value for <constant>Pdo\Sqlite::ATTR_EXPLAIN_STATEMENT</constant>: + returns the opcodes of the virtual machine used to execute the statement + (equivalent to SQLite's <literal>EXPLAIN</literal>). + Available as of PHP 8.5.0, when compiled against libsqlite &gt;= 3.43.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.explain-mode-explain-query-plan"> + <term><constant>Pdo\Sqlite::EXPLAIN_MODE_EXPLAIN_QUERY_PLAN</constant></term> + <listitem> + <simpara> + Value for <constant>Pdo\Sqlite::ATTR_EXPLAIN_STATEMENT</constant>: + returns the query plan (equivalent to SQLite's + <literal>EXPLAIN QUERY PLAN</literal>). + Available as of PHP 8.5.0, when compiled against libsqlite &gt;= 3.43.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.attr-transaction-mode"> + <term><constant>Pdo\Sqlite::ATTR_TRANSACTION_MODE</constant></term> + <listitem> + <simpara> + A connection attribute configuring the transaction mode used by + <methodname>PDO::beginTransaction</methodname>. Possible values are + <constant>Pdo\Sqlite::TRANSACTION_MODE_DEFERRED</constant>, + <constant>Pdo\Sqlite::TRANSACTION_MODE_IMMEDIATE</constant>, and + <constant>Pdo\Sqlite::TRANSACTION_MODE_EXCLUSIVE</constant>. + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.transaction-mode-deferred"> + <term><constant>Pdo\Sqlite::TRANSACTION_MODE_DEFERRED</constant></term> + <listitem> + <simpara> + Value for <constant>Pdo\Sqlite::ATTR_TRANSACTION_MODE</constant>: + uses SQLite's DEFERRED transaction mode (the default). + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.transaction-mode-immediate"> + <term><constant>Pdo\Sqlite::TRANSACTION_MODE_IMMEDIATE</constant></term> + <listitem> + <simpara> + Value for <constant>Pdo\Sqlite::ATTR_TRANSACTION_MODE</constant>: + uses SQLite's IMMEDIATE transaction mode. + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.transaction-mode-exclusive"> + <term><constant>Pdo\Sqlite::TRANSACTION_MODE_EXCLUSIVE</constant></term> + <listitem> + <simpara> + Value for <constant>Pdo\Sqlite::ATTR_TRANSACTION_MODE</constant>: + uses SQLite's EXCLUSIVE transaction mode. + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.ok"> + <term><constant>Pdo\Sqlite::OK</constant></term> + <listitem> + <simpara> + Return value of an authorizer callback set with + <methodname>Pdo\Sqlite::setAuthorizer</methodname>, allowing the action. + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.deny"> + <term><constant>Pdo\Sqlite::DENY</constant></term> + <listitem> + <simpara> + Return value of an authorizer callback set with + <methodname>Pdo\Sqlite::setAuthorizer</methodname>, denying the action. + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="pdo-sqlite.constants.ignore"> + <term><constant>Pdo\Sqlite::IGNORE</constant></term> + <listitem> + <simpara> + Return value of an authorizer callback set with + <methodname>Pdo\Sqlite::setAuthorizer</methodname>, substituting a &null; + value for the column that would have been read. + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> </variablelist> </section> + + <section role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.5.0</entry> + <entry> + Added constants <constant>Pdo\Sqlite::ATTR_BUSY_STATEMENT</constant>, + <constant>Pdo\Sqlite::ATTR_EXPLAIN_STATEMENT</constant>, + <constant>Pdo\Sqlite::EXPLAIN_MODE_PREPARED</constant>, + <constant>Pdo\Sqlite::EXPLAIN_MODE_EXPLAIN</constant>, + <constant>Pdo\Sqlite::EXPLAIN_MODE_EXPLAIN_QUERY_PLAN</constant>, + <constant>Pdo\Sqlite::ATTR_TRANSACTION_MODE</constant>, + <constant>Pdo\Sqlite::TRANSACTION_MODE_DEFERRED</constant>, + <constant>Pdo\Sqlite::TRANSACTION_MODE_IMMEDIATE</constant>, and + <constant>Pdo\Sqlite::TRANSACTION_MODE_EXCLUSIVE</constant>, + <constant>Pdo\Sqlite::OK</constant>, + <constant>Pdo\Sqlite::DENY</constant>, and + <constant>Pdo\Sqlite::IGNORE</constant>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + </partintro> &reference.pdo-sqlite.pdo.entities.sqlite; diff --git a/reference/pdo_sqlite/pdo/sqlite/createcollation.xml b/reference/pdo_sqlite/pdo/sqlite/createcollation.xml index f913eff8ef3b..7b49bd78a295 100644 --- a/reference/pdo_sqlite/pdo/sqlite/createcollation.xml +++ b/reference/pdo_sqlite/pdo/sqlite/createcollation.xml @@ -62,6 +62,38 @@ </simpara> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + A <exceptionname>TypeError</exceptionname> is thrown if the + <parameter>callback</parameter> does not return an <type>int</type>. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.4.0</entry> + <entry> + A <exceptionname>TypeError</exceptionname> is now thrown if the + <parameter>callback</parameter> does not return an <type>int</type>; + previously the returned value was cast to <type>int</type>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <example> diff --git a/reference/pdo_sqlite/pdo/sqlite/setauthorizer.xml b/reference/pdo_sqlite/pdo/sqlite/setauthorizer.xml new file mode 100644 index 000000000000..01fd057d13df --- /dev/null +++ b/reference/pdo_sqlite/pdo/sqlite/setauthorizer.xml @@ -0,0 +1,166 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="pdo-sqlite.setauthorizer" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Pdo\Sqlite::setAuthorizer</refname> + <refpurpose>Configures a callback to be used as an authorizer to limit what a statement can do</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Pdo\\Sqlite"> + <modifier>public</modifier> <type>void</type><methodname>Pdo\Sqlite::setAuthorizer</methodname> + <methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam> + </methodsynopsis> + <simpara> + Sets a callback that will be called by SQLite every time an action is performed + (reading, deleting, updating, etc.). This is used when preparing an SQL statement + from an untrusted source to ensure that the statement does not access data it is + not allowed to see or execute malicious statements that damage the database. + </simpara> + <simpara> + The authorizer is used only during the statement preparation phase. + It may be called several times for a single statement: a + <literal>SELECT</literal> or <literal>UPDATE</literal> query calls it for every + column that would be read or updated. It runs again whenever SQLite + re-prepares a statement, which may happen while the statement is being + executed, for instance after the schema has changed. + </simpara> + <simpara> + The authorizer is called with up to five arguments. The arguments received are + described at <methodname>SQLite3::setAuthorizer</methodname>. + </simpara> + <simpara> + Only a single authorizer can be in place on a database connection at a time. + Each call to this method overrides the previous one. The authorizer is disabled + by default, and can be disabled again by setting a &null; callback. + </simpara> + <simpara> + The callback must not modify the database connection that invoked it. + </simpara> + <simpara> + More details can be found in the + <link xlink:href="&url.sqlite;c3ref/set_authorizer.html">SQLite documentation</link>. + </simpara> + <note> + <simpara> + This method is the equivalent of <methodname>SQLite3::setAuthorizer</methodname>, + except that it returns <type>void</type> instead of <type>bool</type>. + </simpara> + </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>callback</parameter></term> + <listitem> + <simpara> + The <type>callable</type> to be invoked, or &null; to disable the current + authorizer callback. + </simpara> + <simpara> + It must return one of <constant>Pdo\Sqlite::OK</constant>, + <constant>Pdo\Sqlite::DENY</constant>, or + <constant>Pdo\Sqlite::IGNORE</constant>. + When <constant>Pdo\Sqlite::DENY</constant> is returned, the statement that + triggered the authorizer fails with an error stating that access is denied. + When <constant>Pdo\Sqlite::IGNORE</constant> is returned for a read action, + the statement is prepared so that a &null; value is substituted for the + column that would have been read. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + &return.void; + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + This method itself does not throw, but if the authorizer callback does not return + an <type>int</type>, or returns an <type>int</type> which is not one of + <constant>Pdo\Sqlite::OK</constant>, <constant>Pdo\Sqlite::DENY</constant>, or + <constant>Pdo\Sqlite::IGNORE</constant>, the statement preparation throws a + <exceptionname>TypeError</exceptionname> or a <exceptionname>ValueError</exceptionname> + respectively. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><methodname>Pdo\Sqlite::setAuthorizer</methodname> example</title> + <simpara> + Only read actions are allowed on the connection. The action codes are exposed + as <classname>SQLite3</classname> class constants, which requires the + <link linkend="book.sqlite3">SQLite3</link> extension to be available; their + integer values may be used directly otherwise. + </simpara> + <programlisting role="php"> +<![CDATA[ +<?php +$db = new Pdo\Sqlite('sqlite::memory:'); +$db->exec('CREATE TABLE users (id, name)'); + +$db->setAuthorizer(function (int $action, ...$args) { + return match ($action) { + SQLite3::SELECT, SQLite3::READ => Pdo\Sqlite::OK, + default => Pdo\Sqlite::DENY, + }; +}); + +var_dump($db->query('SELECT name FROM users') instanceof PDOStatement); + +try { + $db->exec('DROP TABLE users'); +} catch (PDOException $e) { + echo $e->getMessage(), "\n"; +} +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +bool(true) +SQLSTATE[HY000]: General error: 23 not authorized +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>SQLite3::setAuthorizer</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_sqlite/versions.xml b/reference/pdo_sqlite/versions.xml index bb3e95e46bd1..a269b75d0d4d 100644 --- a/reference/pdo_sqlite/versions.xml +++ b/reference/pdo_sqlite/versions.xml @@ -8,6 +8,7 @@ <function name="pdo\sqlite::createfunction" from="PHP 8 &gt;= 8.4.0"/> <function name="pdo\sqlite::loadextension" from="PHP 8 &gt;= 8.4.0"/> <function name="pdo\sqlite::openblob" from="PHP 8 &gt;= 8.4.0"/> + <function name="pdo\sqlite::setauthorizer" from="PHP 8 &gt;= 8.5.0"/> </versions> <!-- Keep this comment at the end of the file

« previous php.doc.cvs (#23689) next »