aqlValue()

Transform a PHP value into an AQL-compatible expression.

       +--------------------------+
       |      Is $val a string?   |
       +-----------+--------------+
                   |
                  No
                   |--> return $val as-is or throw (non-string)
                   |
                  Yes
                   v
       +--------------------------+
       |   Is $val in rawValues?  |
       +-----------+--------------+
                   |
               Yes |--> return $val (raw)
                   |
                  No
                   v
       +--------------------------+
       |   Matches AQL function?  |
       | CONCAT(...), DATE_NOW()  |
       +-----------+--------------+
                   |
               Yes |--> return $val (raw)
                   |
                  No
                   v
       +--------------------------+
       | Matches AQL pattern?     |
       | doc.field, @bind, col/key|
       +-----------+--------------+
                   |
               Yes |--> return $val (raw)
                   |
                  No
                  v
       +--------------------------+
       |   Regular string         |
       |   Escape and quote       |
       |   return "'val'"         |
       +--------------------------+

Parameters

$value : mixed

The PHP value to transform

$rawValues : array<string|int, mixed> = []

Optional list of specific values to treat as raw AQL expressions

Tags

throws

UnsupportedOperationException

If the value type is unsupported.

example

Basic usage

echo aqlValue('hello');
// 'hello'

echo aqlValue(42);
// 42

echo aqlValue(['name' => 'John', 'age' => 30]);
// {name:'John',age:30}

Automatic AQL function detection

echo aqlValue('CONCAT("user_", doc.id)');
// CONCAT("user_", doc.id)

echo aqlValue('LENGTH(doc.name)');
// LENGTH(doc.name)

echo aqlValue('DATE_NOW()');
// DATE_NOW()

echo aqlValue('UPPER(user.firstName)');
// UPPER(user.firstName)

Document references and bind parameters

echo aqlValue('doc._id');
// doc._id

echo aqlValue('user.name');
// user.name

echo aqlValue('@userId');
// @userId

echo aqlValue('users/12345');
// users/12345

Complex document with automatic detection

$data =
[
    '_key' => 'CONCAT("user_", doc.id)',
    '_from' => 'users/@userId',
    '_to' => 'posts/12345',
    'name' => 'Regular string',
    'length' => 'LENGTH(doc.content)',
    'createdAt' => 'DATE_NOW()',
    'reference' => 'doc.originalId'
];

echo aqlValue($data);
// {_key:CONCAT("user_", doc.id),_from:users/@userId,_to:posts/12345,name:'Regular string',length:LENGTH(doc.content),createdAt:DATE_NOW(),reference:doc.originalId}

Manual raw values for edge cases

// If a string looks like normal text but should be raw
echo aqlValue('some_custom_variable', ['some_custom_variable']);
// some_custom_variable

// Mix of auto-detection + manual raw
$data = [
    '_key' => 'CONCAT("test")',        // Auto-detected
    'customVar' => 'my_aql_variable'   // Requires rawValues
];
echo aqlValue($data, ['my_aql_variable']);
// {_key:CONCAT("test"),customVar:my_aql_variable}

What gets auto-detected as AQL

// ✅ Functions: WORD(...)
aqlValue('CONCAT("a", "b")');          // CONCAT("a", "b")
aqlValue('DATE_FORMAT(doc.date)');     // DATE_FORMAT(doc.date)

// ✅ Document/collection references: word.word
aqlValue('doc.name');                  // doc.name
aqlValue('user.profile');              // user.profile

// ✅ Bind parameters: @word
aqlValue('@userId');                   // @userId
aqlValue('@filter.name');              // @filter.name

// ✅ Collection paths: word/word
aqlValue('users/12345');               // users/12345
aqlValue('posts/abc-def');             // posts/abc-def

// ❌ Regular strings (quoted)
aqlValue('just text');                 // 'just text'
aqlValue('user name');                 // 'user name'

author

Marc Alcaraz

since

1.0.0