moxio / sqlite-extended-api

Exposes SQLite APIs that are otherwise not available in PHP

moxio/sqlite-extended-api

Exposes SQLite APIs that are otherwise not available in PHP. You can connect to an SQLite database as you normally would using PHP's PDO extension, then use this library to call SQLite API methods that PDO does not offer (e.g. loading extensions).

Warning: under the hood, this library makes use of Z-Engine, which proclaims itself not ready for production until version 1.0.0. Use it at your own risk.

Requirements

This library requires PHP version 7.4 or higher with the FFI extension enabled. It only works with x64 non-thread-safe builds of PHP.

Installation

Install as a dependency using composer:

$ composer require moxio/sqlite-extended-api

Usage

If you have an existing PDO connection to an SQLite database, you can use the wrapPDO() static method on the Facade class to obtain access to extra SQLite APIs:

<?php
use Moxio\SQLiteExtendedAPI\Facade;

// Existing PDO connection
$pdo = new \PDO('sqlite::memory:');

// Wrap it using this library
$wrapped_connection = Facade::wrapPDO($pdo);

// Call extended APIs on the wrapped connection object
$wrapped_connection->loadExtension('mod_spatialite.so');

See the next section for methods available on the wrapped connection.

Exposed APIs

Below is a short overview; see WrappedConnection for details.

Loading SQLite extensions

Load additional SQLite extension libraries using loadExtension($shared_library):

$wrapped_connection->loadExtension('mod_spatialite.so');

This corresponds to the loadExtension method in PHP's SQLite3 extension, or [sqlite3_load_extension](https://sqlite.org/c3ref/load_extension.html) in the SQLite C interface. Returns true` if the extension was successfully loaded, false if it was not.

Obtaining the database filename

To obtain the full disk path of the database connected to, use getDatabaseFilename():

var_dump($wrapped_connection->getDatabaseFilename());

For an in-memory database, this returns an empty string.

How does this work?

In short: we use the awesome Z-Engine project by Alexander Lisachenko and PHP's Foreign Function Interface (FFI) to resolve your PHP variable to the raw connection pointer for the SQLite C API, then call that C API using FFI.

More details can be found in this blog post.

Versioning

This project adheres to Semantic Versioning.

Contributing

Contributions to this project are more than welcome. If there are other SQLite APIs that you would like to be able to use in PHP, feel free to send a PR or to file a feature request.

License

This project is released under the MIT license.

Treeware

This package is Treeware. If you use it in production, then we'd appreciate it if you buy the world a tree to thank us for our work. By contributing to the Treeware forest you'll be creating employment for local families and restoring wildlife habitats.

---

Made with love, coffee and fun by the Moxio team from Delft, The Netherlands. Interested in joining our awesome team? Check out our vacancies (in Dutch).

sqlite-extended-api's Issues

before on Facade::wrapPDO() : Preload mode requires that you call Core::preload

When trying to wrap a PDO instance, I get Preload mode requires that you call Core::preload before

Any pointers on how to solve that ?
On PHP 8.0.19

Thanks

i like this great project

dear sir.

my question is, can i use this wrapper to connect sqlite without pdo?

example : new SQlite3( 'db' );

"Failed loading sqlite3.so" error

Hello, thank you for this great library! It helped solving a lot of headaches in my test suite.

I'm using it to run tests from CLI in a Docker container based on the official php7.4-fpm image.
libffi-dev, libsqlite3-dev and sqlite3 are installed, as well as ffi, pdo and pdo_sqlite PHP extensions.

I encountered 2 problems while wrapping the PDO connection using Facade::wrapPDO() method:

1. Failed loading 'pdo.so' from PDO\DriverDataResolver.
   The extension_dir configuration in php.ini points correctly to /usr/local/lib/php/extensions/no-debug-non-zts-20190902 and the file pdo.so is actually there, but FFI is unable to find it.
   I'm pretty sure this is more an FFI issue, like highlighted here.
   As a workaround I added the path to the LD_LIBRARY_PATH environment variable and solved the problem ✔️
2. Failed loading 'sqlite3.so' from SQLite3\ConnectionWrapper.
   In fact, in the extension_library directory /usr/local/lib/php/extensions/no-debug-non-zts-20190902 the file is missing, but running php -i shows that the SQLite3 support is enabled. I think it depends from this: AFAIK, it should mean that SQLite3 support has been unbounded from PHP and the engine relies on the system library.
   The system library is stored in /usr/lib/x86_64-linux-gnu directory but the filename is libsqlite3.so instead of sqlite3.so and FFI cannot find it. I tried several times to rename the library, to recompile it from scratch with the sqlite3.so name and to rebuild the cache of the shared libraries with ldconfig, but with no luck: the error still appears.

The only fix that seems to work is to update the second argument of the FFI:::cdef() method in the SQLite3\ConnectionWrapper, from sqlite3.so to libsqlite3.so.

public function __construct() {
    $this->sqlite3_ffi = \FFI::cdef(file_get_contents(__DIR__ . "/sqlite3.h"), "sqlite3.so");
}

becomes

public function __construct() {
    $this->sqlite3_ffi = \FFI::cdef(file_get_contents(__DIR__ . "/sqlite3.h"), "libsqlite3.so");
}

Of course, this is not a sustainable solution. Am I doing something wrong? Do you think it is possible to make the argument configurable? Or even switch to the new filename, maybe using a fallback mechanism to keep backwards compatibility... I'm willing to open a PR if it's okay for you.

Thanks for help!