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:

Node.js (Default): Requires Node.js v18+ installed on the system.
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

Provider	Backend	Transport	Runtime
`cli`	Bundled engine	`proc_open()` / shell	`node` or `qjs`
`server`	MorphQL REST server	cURL / `file_get_contents`	—

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.

Option	Env Var	Default	Description
`provider`	`MORPHQL_PROVIDER`	`cli`	`cli` or `server`
`runtime`	`MORPHQL_RUNTIME`	`node`	`node` or `qjs`
`cli_path`	`MORPHQL_CLI_PATH`	(auto)	Override CLI binary path
`node_path`	`MORPHQL_NODE_PATH`	`node`	Path to Node.js binary
`qjs_path`	`MORPHQL_QJS_PATH`	(auto)	Path to QuickJS binary
`cache_dir`	`MORPHQL_CACHE_DIR`	`sys_get_temp_dir()/morphql`	CLI query cache dir
`server_url`	`MORPHQL_SERVER_URL`	`http://localhost:3000`	Server base URL
`api_key`	`MORPHQL_API_KEY`	(none)	API key for server auth
`timeout`	`MORPHQL_TIMEOUT`	`30`	Timeout in seconds

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();
}

morphql / morphql

Maintainers

Package info

Statistics

Security