Oihana PHP System

ExpressionTrait

A collection of utility methods for building and formatting string expressions used in dynamic query generation or structured output (e.g., AQL, JSON-like formats).

This trait provides:

  • Cleaning utilities for expression arrays
  • Syntax helpers for function calls, key-value pairs, and object-like structures
  • Predicate and logical condition composition
  • String wrapping utilities

These methods are especially useful in libraries where query composition and syntactic consistency are critical.

Requires:

  • The use of Char enum for consistent delimiters and symbols
Tags
example 
$this->betweenParentheses(['a', 'b']); // '(a b)'
$this->betweenBraces("id: 1");         // '{ id: 1 }'
$this->betweenBrackets([1, 2, 3]);     // '[1 2 3]'
$this->betweenQuotes("hello");         // "'hello'"
$this->betweenDoubleQuotes("world");   // '"world"'
$this->betweenChars("x", "<", ">");    // '<x>'

$this->compile(['x == 1', 'y == 2']);                // 'x == 1 y == 2'
$this->func('SUM', ['a', 'b']);                      // 'SUM(a,b)'
$this->key('name', 'user');                          // 'user.name'
$this->keyValue('status', '"active"');               // 'status: "active"'
$this->object([['id', 1], ['name', "'Alice'"]]);     // '{ id: 1, name: 'Alice' }'
$this->predicate('x', '==', 42);                     // 'x == 42'
$this->predicates(['a == 1', 'b > 0'], 'AND', true); // '(a == 1 AND b > 0)'
$this->wrap('field');                                // '`field`'
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Methods

betweenBraces()  : string
Encapsulates an expression between braces (`{}`).
betweenBrackets()  : string
Encapsulates an expression between brackets (`[]`).
betweenChars()  : mixed
Encapsulates an expression between specific characters.
betweenDoubleQuotes()  : mixed
Encapsulates an expression between double quotes.
betweenParentheses()  : string
Encapsulates an expression between parentheses (`()`).
betweenQuotes()  : mixed
Encapsulates an expression between single quotes or custom characters.
clean()  : array<string|int, mixed>
Clean an array by removing null values and empty strings.
compile()  : string
Compile a list of expressions into a single string using a separator.
func()  : string
Build a function expression like `NAME(arg1,arg2)`.
key()  : string
Transform a key by optionally prefixing it.
keyValue()  : string
Build a key-value expression like `key: value`.
object()  : string
Create an object expression, e.g., `{ name: 'Eka', age: 48 }`.
predicate()  : string
Generate a predicate expression.
predicates()  : string|null
Generate a complex logical expression with multiple predicates.
wrap()  : string
Wrap a string in grave accent characters.

Methods

betweenBraces()

Encapsulates an expression between braces (`{}`).

public betweenBraces([mixed $expression = Char::EMPTY ][, bool $useBraces = true ][, string $separator = Char::SPACE ]) : string
Parameters
$expression : mixed = Char::EMPTY

The expression to wrap.

$useBraces : bool = true

Whether to apply the braces or not.

$separator : string = Char::SPACE

Separator for arrays (default: space).

Tags
example 
$this->betweenBraces('id: 1');           // '{ id: 1 }'
$this->betweenBraces(['x', 'y']);        // '{ x y }'
$this->betweenBraces(['x', 'y'], false); // 'x y'
Return values
string —

The wrapped string.

betweenBrackets()

Encapsulates an expression between brackets (`[]`).

public betweenBrackets([mixed $expression = Char::EMPTY ][, bool $useBrackets = true ][, string $separator = Char::SPACE ]) : string
Parameters
$expression : mixed = Char::EMPTY

The expression to wrap.

$useBrackets : bool = true

Whether to apply the brackets.

$separator : string = Char::SPACE

Separator for arrays.

Tags
example 
$this->betweenBrackets(['a', 'b']);     // '[a b]'
$this->betweenBrackets('index: 3');     // '[index: 3]'
$this->betweenBrackets('value', false); // 'value'
Return values
string —

The wrapped string.

betweenChars()

Encapsulates an expression between specific characters.

public betweenChars([mixed $expression = null ][, string $left = Char::EMPTY ][, string|null $right = null ][, bool $flag = true ][, string $separator = Char::SPACE ]) : mixed
Parameters
$expression : mixed = null

The expression to encapsulate between two characters.

$left : string = Char::EMPTY

The left character.

$right : string|null = null

The right character. If null, uses the left character.

$flag : bool = true

Indicates whether to apply the wrapping.

$separator : string = Char::SPACE

The separator used to join arrays.

Tags
example 
$this->betweenChars('x', '<', '>');         // '<x>'
$this->betweenChars(['a', 'b'], '[', ']');  // '[a b]'
$this->betweenChars('y', '"', null, false); // 'y'
Return values
mixed —

The wrapped string or original expression.

betweenDoubleQuotes()

Encapsulates an expression between double quotes.

public betweenDoubleQuotes([mixed $expression = Char::EMPTY ][, string $char = Char::DOUBLE_QUOTE ][, bool $useQuotes = true ][, string $separator = Char::SPACE ]) : mixed
Parameters
$expression : mixed = Char::EMPTY

The expression to wrap.

$char : string = Char::DOUBLE_QUOTE

The quote character (default: ").

$useQuotes : bool = true

Whether to apply quotes.

$separator : string = Char::SPACE

Separator for arrays.

Tags
example 
$this->betweenDoubleQuotes('hello');         // '"hello"'
$this->betweenDoubleQuotes(['a', 'b']);      // '"a b"'
$this->betweenDoubleQuotes('x', '"', false); // 'x'
Return values
mixed —

The wrapped string or original.

betweenParentheses()

Encapsulates an expression between parentheses (`()`).

public betweenParentheses([mixed $expression = Char::EMPTY ][, bool $useParentheses = true ][, string $separator = Char::SPACE ]) : string
Parameters
$expression : mixed = Char::EMPTY

The expression to wrap.

$useParentheses : bool = true

Whether to apply the parentheses.

$separator : string = Char::SPACE

Separator for arrays.

Tags
example 
$this->betweenParentheses('sum: 10');       // '(sum: 10)'
$this->betweenParentheses(['a', 'b', 'c']); // '(a b c)'
$this->betweenParentheses('val', false);    // 'val'
Return values
string —

The wrapped string.

betweenQuotes()

Encapsulates an expression between single quotes or custom characters.

public betweenQuotes([mixed $expression = Char::EMPTY ][, string $char = Char::SIMPLE_QUOTE ][, bool $useQuotes = true ][, string $separator = Char::SPACE ]) : mixed
Parameters
$expression : mixed = Char::EMPTY

The expression to wrap.

$char : string = Char::SIMPLE_QUOTE

The quote character (default: ').

$useQuotes : bool = true

Whether to apply the quotes.

$separator : string = Char::SPACE

Separator for arrays.

Tags
example 
$this->betweenQuotes('world');           // '\'world\''
$this->betweenQuotes(['foo', 'bar']);    // '\'foo bar\''
$this->betweenQuotes('data', '`');       // '`data`'
$this->betweenQuotes('raw', "'", false); // 'raw'
Return values
mixed —

The wrapped string or original.

clean()

Clean an array by removing null values and empty strings.

public clean([array<string|int, mixed> $array = [] ]) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed> = []

The array to clean.

Tags
example 
$this->clean(['foo', '', null, 'bar']); // ['foo', 'bar']
Return values
array<string|int, mixed> —

The filtered array.

compile()

Compile a list of expressions into a single string using a separator.

public compile(string|array<string|int, mixed>|null $expressions[, string $separator = Char::SPACE ]) : string
Parameters
$expressions : string|array<string|int, mixed>|null

The expressions to compile.

$separator : string = Char::SPACE

The separator to use (default: Char::SPACE).

Tags
example 
$this->compile(['name = "foo"', 'age > 21']); // 'name = "foo" age > 21'
$this->compile(null);                         // ''
Return values
string —

The compiled string.

func()

Build a function expression like `NAME(arg1,arg2)`.

public func(string $name[, mixed $arguments = null ][, string $separator = Char::COMMA ]) : string
Parameters
$name : string

The function name.

$arguments : mixed = null

The arguments for the function.

$separator : string = Char::COMMA

The separator between arguments (default: Char::COMMA).

Tags
example 
$this->func('CALL', ['a', 'b']); // 'CALL(a,b)'
Return values
string —

The function expression.

key()

Transform a key by optionally prefixing it.

public key(string $key, string|null $prefix) : string
Parameters
$key : string

The key to transform.

$prefix : string|null

The prefix to prepend.

Tags
example 
$this->key('name');           // 'name'
$this->key('name', 'doc');    // 'doc.name'
Return values
string —

The transformed key.

keyValue()

Build a key-value expression like `key: value`.

public keyValue(mixed $key, mixed $value) : string
Parameters
$key : mixed

The key.

$value : mixed

The value.

Tags
example 
$this->keyValue('name', 'Eka'); // 'name: Eka'
Return values
string —

The key-value expression.

object()

Create an object expression, e.g., `{ name: 'Eka', age: 48 }`.

public object([string|array<string|int, mixed>|null $keyValues = [] ]) : string
Parameters
$keyValues : string|array<string|int, mixed>|null = []

The properties to include.

Tags
example 
$this->object([['name', "'Eka'"], ['age', 47]]);
// '{ name: 'Eka', age: 47 }'
Return values
string —

The object-like string expression.

predicate()

Generate a predicate expression.

public predicate(mixed $leftOperand[, string|null $operator = null ][, mixed $rightOperand = null ]) : string
Parameters
$leftOperand : mixed

The left-hand value.

$operator : string|null = null

The operator (e.g., '==', '!=').

$rightOperand : mixed = null

The right-hand value.

Tags
example 
$this->predicate('age', '>=', 18); // 'age >= 18'
Return values
string —

The predicate expression.

predicates()

Generate a complex logical expression with multiple predicates.

public predicates(array<string|int, mixed>|null $conditions, string $logicalOperator[, bool $useParentheses = false ]) : string|null
Parameters
$conditions : array<string|int, mixed>|null

List of predicate expressions.

$logicalOperator : string

The logical operator to join predicates (e.g., 'AND', 'OR').

$useParentheses : bool = false

Whether to wrap the result in parentheses.

Tags
example 
$predicates = [
    $this->predicate('a', '==', 1),
    $this->predicate('b', '>', 5)
];
$this->predicates( $predicates , 'AND' , true ) ; // '(a == 1 AND b > 5)'
Return values
string|null —

The combined expression or null if empty.

wrap()

Wrap a string in grave accent characters.

public wrap(string $value) : string
Parameters
$value : string

The value to wrap.

Tags
example 
$this->wrap('column'); // '`column`'
Return values
string —

The wrapped value.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results