# v2 (alpha)

Connect to SurrealDB and run your first queries with version 2 (alpha) of the PHP SDK.

The PHP SDK for SurrealDB lets you connect to a database and query it from your application. This guide covers connecting, authenticating, and running your first queries with the v2 line of the SDK.

> [!IMPORTANT]
> Version 2.x is a rewrite with a fluent query builder, typed credentials, and a PSR-based transport layer. It is in **alpha** and introduces breaking changes, so pin the exact version when installing it. The current stable release is documented under [v1](/docs/reference/php/v1.md), with its [getting-started guide](/docs/languages/php.md) in the Start section.

## 1. Install the SDK

Follow the [installation guide](/docs/reference/php/v2/installation.md) to add the SDK to your project. Once installed, include the autoloader and import the classes you need.

```php
require __DIR__ . '/vendor/autoload.php';

use SurrealDB\SDK\Surreal;
use SurrealDB\SDK\Connection\ConnectOptions;
use SurrealDB\SDK\Auth\RootAuth;
use SurrealDB\SDK\Types\RecordId;
use SurrealDB\SDK\Types\Table;

$db = new Surreal();
```

## 2. Connect to SurrealDB

Use the `connect()` method with a connection string and a `ConnectOptions` object. The options carry the namespace, database, and authentication details. Passing credentials here lets the SDK re-authenticate automatically after a reconnect.

Supported connection protocols include:
- **WebSocket** (`ws://`, `wss://`) for long-lived stateful connections that support live queries
- **HTTP** (`http://`, `https://`) for short-lived stateless connections

```php
$db->connect('ws://127.0.0.1:8000/rpc', new ConnectOptions(
    namespace: 'surrealdb',
    database: 'docs',
    authentication: new RootAuth('root', 'root'),
));
```

See [Connecting to SurrealDB](/docs/reference/php/v2/concepts/connecting-to-surrealdb.md) for the full set of options.

## 3. Inserting data into SurrealDB

The `create()` method starts a `CREATE` statement. Chain `content()` to set the record data, then call `execute()` to run it. Pass a [`RecordId`](/docs/reference/php/v2/api/data-types.md#recordid) for a specific ID, or a [`Table`](/docs/reference/php/v2/api/data-types.md#table) to let SurrealDB generate one.

```php
$person = $db->create(new RecordId('person', 'tobie'))
    ->content([
        'name' => 'Tobie',
        'age' => 32,
    ])
    ->execute();

$auto = $db->create(new Table('person'))
    ->content(['name' => 'Jaime'])
    ->execute();
```

## 4. Retrieving data from SurrealDB

### Selecting records

The `select()` method reads records. Pass a `Table` to read all records, or a `RecordId` to read one. Chain `fields()`, `where()`, and `limit()` to refine the query before `execute()`.

```php
$everyone = $db->select(new Table('person'))->execute();

$tobie = $db->select(new RecordId('person', 'tobie'))->execute();

$adults = $db->select(new Table('person'))
    ->fields('name', 'age')
    ->where('age >= 18')
    ->limit(10)
    ->execute();
```

### Running SurrealQL queries

For anything the builders do not cover, `run()` executes raw [SurrealQL](/docs/reference/query-language.md). Pass bindings as the second argument to inject values safely.

```php
[$cheapest] = $db->run(
    'SELECT name, age FROM person WHERE age < $max ORDER BY age',
    ['max' => 40],
);
```

`run()` returns one result per statement, so destructure the first entry for a single-statement query.

## 5. Closing the connection

Always close the connection when you are done to release resources.

```php
$db->close();
```

## Next steps

You have learned how to install the SDK, connect to SurrealDB, create records, and retrieve data. There is a lot more you can do with the SDK, including updating and deleting records, authentication, live queries, and transactions.

- [Connection management](/docs/reference/php/v2/concepts/connecting-to-surrealdb.md) - Learn how to manage your database connections, including protocols and configuration.

- [Authentication](/docs/reference/php/v2/concepts/authentication.md) - Sign in and sign up with root, namespace, database, and record access.

- [Executing queries](/docs/reference/php/v2/concepts/executing-queries.md) - Use the query builders and the raw query API in depth.

- [API Reference](/docs/reference/php/v2/api/core.md) - Complete reference for the core client, query builders, and types.

> [!NOTE]
> This getting-started guide covers the essentials. For the complete methods, API, and concept reference, see the [PHP (v2) SDK reference](/docs/reference/php/v2.md).