PHP Quick Start

WowSQL PHP SDK — Get started in minutes

Get your API key: Use the WowSQL project dashboard to create or copy your API key. The same key works for database, auth, and storage (unified API key).

Installation

Official package: View on Packagist →

composer require WowSQL/WowSQL-sdk

Initialize Client

<?php
require 'vendor/autoload.php';

use WowSQL\Client;

// Initialize client with your API key (same key for database, auth, storage)
$client = new Client([
    'project_url' => 'myproject',
    'api_key'     => 'your_api_key_here',
]);

// Or with full URL
$clientFull = new Client([
    'project_url' => 'https://myproject.wowsqlconnect.com',
    'api_key'     => 'your_api_key',
]);

// Always use select() before get()
$users = $client->table('users')->select('*')->get();

Query Data

Basic Queries

// Get all records
$users = $client->table('users')->select('*')->get();

// With filters
$adults = $client->table('users')
    ->select('*')
    ->gte('age', 18)
    ->get();

// Select specific columns
$names = $client->table('users')
    ->select('id', 'name')
    ->get();

Advanced Queries

// Multiple filters with sorting
$activeUsers = $client->table('users')
    ->select('*')
    ->eq('status', 'active')
    ->gt('age', 18)
    ->orderBy('created_at', true)  // desc
    ->limit(20)
    ->offset(0)
    ->get();

echo "Found " . $activeUsers['count'] . " users\n";
foreach ($activeUsers['data'] as $user) {
    echo $user['name'] . "\n";
}

Filter Helper Methods

// Using helper methods
$users = $client->table('users')
    ->eq('status', 'active')
    ->gt('age', 18)
    ->like('email', '%@gmail.com')
    ->isNotNull('email_verified_at')
    ->get();

GROUP BY and Aggregates

Basic GROUP BY

// Group by category with counts
$result = $client->table('products')
    ->select('category', 'COUNT(*) as count', 'AVG(price) as avg_price')
    ->groupBy('category')
    ->get();

// Group by date
$result2 = $client->table('orders')
    ->select('DATE(created_at) as date', 'COUNT(*) as orders', 'SUM(total) as revenue')
    ->groupBy('DATE(created_at)')
    ->orderBy('date', true)
    ->get();

HAVING Clause

// Filter aggregated results
$result = $client->table('products')
    ->select('category', 'COUNT(*) as count')
    ->groupBy('category')
    ->having('COUNT(*)', 'gt', 10)
    ->get();

CRUD Operations

Create Record

$result = $client->table('users')->create([
    'name'  => 'John Doe',
    'email' => 'john@example.com',
    'age'   => 30,
]);
echo "Created user with ID: " . $result['id'] . "\n";

Update Record

$client->table('users')->update(123, [
    'email' => 'newemail@example.com',
]);
echo "User updated successfully\n";

Delete Record

$client->table('users')->delete(123);
echo "User deleted successfully\n";

Get Single Record by ID

$user = $client->table('users')->getById(123);
echo "User: " . $user['name'] . "\n";

Get First Record

$user = $client->table('users')
    ->eq('status', 'active')
    ->first();

if ($user) {
    echo "First active user: " . $user['name'] . "\n";
}

Filter Operators

Available operators for filtering data:

Error Handling

try {
    $users = $client->table('users')->select('*')->get();
    echo "Success: " . count($users['data']) . " users";
} catch (WowSQL\WowSQLException $e) {
    echo "Database error (" . $e->getStatusCode() . "): " . $e->getMessage();
} catch (WowSQL\StorageException $e) {
    echo "Storage error: " . $e->getMessage();
}

Authentication

Use the same API key for authentication. One key works for database and auth.

Sign Up & Sign In

use WowSQL\Auth;

$auth = new Auth([
    'project_url' => 'myproject',
    'api_key'     => 'your_api_key',
]);

// Sign up
$result = $auth->signUp('user@example.com', 'SecurePassword123', 'John Doe');
echo "Access token: " . $result['access_token'] . "\n";

// Sign in
$login = $auth->signIn('user@example.com', 'SecurePassword123');
echo "User ID: " . $login['user']['id'] . "\n";

Password Reset

$auth->forgotPassword('user@example.com');
$auth->resetPassword('reset_token_from_email', 'NewSecurePassword123');

OAuth Authentication

Setup checklist — do this once per provider, per project:
1. Dashboard → Project → Auth → Providers: enable the provider, paste Client ID and Client Secret (no leading/trailing spaces).
2. Copy the Redirect URI shown: https://<slug>.wowsqlconnect.com/api/auth/oauth/<provider>/callback and register it in your provider's developer console.
3. The callback URL is handled entirely by WowSQL — your app does not send an API key on it. WowSQL exchanges the code and redirects to your frontend_redirect_uri with ?access_token=&refresh_token=.

// ── Step 1: Server-side — get the authorization URL ─────────────────────────
$result = $auth->getOAuthAuthorizationUrl(
    'google',
    'https://yourapp.com/auth/callback'
);
// Redirect the browser:
// header('Location: ' . $result['authorization_url']);
// Google calls: https://<slug>.wowsqlconnect.com/api/auth/oauth/google/callback
// WowSQL exchanges the code and redirects to your frontend_redirect_uri.

// ── Step 2: Frontend — read tokens from the redirect ────────────────────────
// WowSQL redirects to: https://yourapp.com/auth/callback?access_token=...&refresh_token=...

// ── (Advanced) Manual code exchange — only if you handle the callback yourself
$authResult = $auth->exchangeOAuthCallback(
    'google',
    'authorization_code_from_callback',
    'https://yourapp.com/auth/callback'  // must match step 1
);
echo "OAuth login successful: " . $authResult['user']['id'] . "\n";

Initialize Storage

use WowSQL\Storage;

$storage = new Storage([
    'project_url' => 'myproject',
    'api_key'     => 'your_api_key',
]);

File Operations

// Upload file
$result = $storage->uploadFromPath('path/to/document.pdf', 'uploads/document.pdf', 'documents');
echo "Uploaded: " . $result['file_key'] . "\n";

// Get file URL (with metadata)
$urlData = $storage->getFileUrl('uploads/document.pdf', 3600);
echo "Download URL: " . $urlData['file_url'] . "\n";

// List files
$files = $storage->listFiles('uploads/');
foreach ($files as $file) {
    echo $file['key'] . ": " . round($file['size'] / 1024 / 1024, 2) . " MB\n";
}

// Delete file
$storage->deleteFile('uploads/document.pdf');

// Check quota
$quota = $storage->getQuota();
echo "Used: " . $quota['used_gb'] . " GB / " . $quota['quota_gb'] . " GB\n";

Download or View File

Via REST: use GET .../files/{file_key}/download for attachment download, or GET .../files/{file_key}/view to view inline in the browser.

Schema DDL (WOWSQLSchema)

UUID primary key: createTable requires the primary key column to be type UUID. Use auto_increment on that column for DEFAULT gen_random_uuid(). Raw CREATE TABLE via execute SQL cannot use SERIAL PRIMARY KEY (or similar integer PK). Existing tables are unchanged.

use WOWSQL\WOWSQLSchema;

$schema = new WOWSQLSchema('myproject', 'wowsql_service_...');
$schema->createTable('items', [
    ['name' => 'id', 'type' => 'UUID', 'auto_increment' => true],
    ['name' => 'title', 'type' => 'TEXT'],
], 'id');