README

A minimalist PHP wrapper for MorphQL — transform data with declarative queries.

PHP 5.6+ compatible · Bundled engine · Composer-ready

Installation

composer require morphql/morphql

Prerequisites

The package ships with the MorphQL engine pre-bundled. You have two options for execution:

1. Node.js (Default): Requires Node.js v18+ installed on the system.
2. QuickJS (Embedded): Self-contained, zero external dependencies. Binaries are automatically downloaded upon installation.

Quick Start

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

use MorphQL\MorphQL;

// One-shot transformation via CLI
$result = MorphQL::execute(
    'from json to json transform set greeting = "Hello, " + name',
    '{"name": "World"}'
);
// → '{"greeting":"Hello, World"}'

Usage

Static API

// PHP 8+ with named parameters
$result = MorphQL::execute(
    query: 'from json to json transform set x = a + b',
    data: '{"a": 1, "b": 2}'
);

// PHP 5.6-7.x — single options array
$result = MorphQL::execute(array(
    'query' => 'from json to json transform set x = a + b',
    'data'  => '{"a": 1, "b": 2}',
));

Reusable Instance

// Preset defaults in the constructor
$morph = new MorphQL(array(
    'provider'   => 'server',
    'server_url' => 'http://localhost:3000',
    'api_key'    => 'my-secret',
));

$result = $morph->run('from json to xml', $data);
$other  = $morph->run('from json to json transform set id = uuid', $data2);

Providers

The CLI provider auto-detects the bundled engine. By default, it uses Node.js, but it can be configured to use an embedded QuickJS runtime for a completely self-contained setup.

Node-less Runtime (QuickJS)

For a completely self-contained setup without Node.js, simply configure MorphQL to use the embedded QuickJS runtime:

$morph = new MorphQL(['runtime' => 'qjs']);

Tip

Automatic Installation: QuickJS binaries for your platform are automatically downloaded by Composer. If you need to reinstall them manually, run php bin/install-qjs.php.

Configuration

Options are resolved in priority order: call params → constructor → env vars → defaults.

Environment Variables

export MORPHQL_PROVIDER=server
export MORPHQL_SERVER_URL=http://my-morphql:3000
export MORPHQL_API_KEY=secret123

Error Handling

try {
    $result = MorphQL::execute('invalid query', '{}');
} catch (\RuntimeException $e) {
    echo 'Transform failed: ' . $e->getMessage();
} catch (\InvalidArgumentException $e) {
    echo 'Bad input: ' . $e->getMessage();
}

License

MIT © 2026 Hyperwindmill