rrwitp/core

Core component of Plasma.

v0.3.0 2019-09-28 19:36 UTC

Requires

• php: >=7.1
• charlottedunois/set: ^0.1.1
• charlottedunois/validator: ^0.3.0
• evenement/evenement: ^3.0|^2.0
• react/promise: ^2.7
• react/promise-stream: ^1.1

Requires (Dev)

• clue/block-react: ^1.3
• phpunit/phpunit: ^7.0
• react/event-loop: ^1.0

Apache-2.0

• Charlotte Dunois

README

Plasma provides an asynchronous, non-blocking (data access) Database Abstraction Layer. This is the core component, defining common parts and interfaces.

The core component alone does nothing, you need a Plasma driver, which does all the handling of the DBMS.

Plasma does not aim to be a full Database Abstraction Layer. Simulating missing features is not a goal and should never be.

For a list of drivers, see the main repository.

Getting Started

As soon as you have selected a driver, you can install it using composer. For the core, the command is

composer require plasma/core

Each driver has their own dependencies, as such they have to implement a factory, which creates their driver instances correctly. For more information, see the driver project page.

But this is some little pseudo code:

$loop = \React\EventLoop\Factory::create();
$factory = new \SomeGuy\PlasmaDriver\MsSQLFactory($loop);

$client = \Plasma\Client::create($factory, 'root:1234@localhost');

$client->execute('SELECT * FROM `users`', [])
    ->then(function (\Plasma\QueryResultInterface $result) use ($client) {
        // Do something with the query result
        // Most likely for a SELECT query,
        // it will be a streaming query result
        
        $client->close()->done();
    }, function (\Throwable $error) use ($client) {
        // Oh no, an error occurred!
        echo $error.\PHP_EOL;
        
        $client->close()->done();
    });

$loop->run();

Cursors

Cursors are a powerful way to get full control over fetching rows. Cursors allow you to control when a row (or multiple) is fetched from the database and allows your application a small memory footprint while fetching millions of rows.

Cursors return a promise and resolve with the row, an array of rows or false (when no more rows). Since they return a promise, you don't need to depend on events and possibly buffer rows when passing around the result.

When combining cursors with generator coroutines (such as Recoil), you get a powerful tool you already know from PDO.

// Inside a coroutine

/** @var \Plasma\CursorInterface  $cursor */
$cursor = yield $client->createReadCursor('SELECT * FROM `my_table`');

while($row = yield $cursor->fetch()) {
    // Process row
}

Support for cursors depend on the individual drivers.

Documentation

https://plasmaphp.github.io/core/