Download the PHP package pdombrovsky/dyna-exp without Composer

DynaExp

Build DynamoDB expressions (ConditionExpression, FilterExpression, KeyConditionExpression, UpdateExpression, ProjectionExpression) with a small set of typed helpers. DynaExp keeps the verbose string juggling out of your application code while staying close to native DynamoDB semantics.

Requirements

• PHP >= 8.2

Installation

⚠️ The library is currently in alpha. Interfaces may change between releases until we hit the stable 1.x line.

Overview

• Nodes – small immutable objects such as Condition, Operation, Projection, Update, or PathNode. They hold the typed data that eventually becomes part of an expression string and remember everything they need (segments, traversal helpers, aliases, etc.).
• Factories – ergonomic wrappers (Path, Key, Size, IfNotExists, …) that expose DynamoDB-oriented helpers. One Path instance can create conditions, updates, projections, search expressions, and aliases without re-parsing strings.
• Builders – fluent APIs for assembling nodes (ConditionBuilder, KeyConditionBuilder, ProjectionBuilder, UpdateBuilder, ExpressionBuilder).
• Evaluator – turns nodes into DynamoDB strings, allocates deterministic ExpressionAttributeNames/ExpressionAttributeValues, and keeps alias usage consistent even when nodes are reused.
• ExpressionContext – a read-only result object with a convenient toArray() method (plus optional value transforms). You stay in control of marshalling to DynamoDB types, so the library works with any SDK or transport layer.

Quick Start

The builders never mutate state after build time, so the same nodes can be reused in different expressions.

Factories

Path

Path is the main building block for attribute access in filters, projections, key conditions, and updates. Under the hood it wraps an immutable PathNode, validates every segment, and keeps DynamoDB-specific metadata such as deterministic string representations, searchExpression() output, and alias-friendly evaluation.

A single Path object can be reused across the whole expression: the helper methods mixed in from ConditionTrait and OperationTrait let you create equality/range/containment checks, attribute existence/type predicates, arithmetic updates, list append/prepend operations, if_not_exists, size(), and more – all off the same root path.

Examples:

Notes:

• Capabilities:
  • project() exposes the underlying PathNode for projection builders or manual evaluation.
  • searchExpression($resetIndexes = false) formats a deterministic, JMESPath-compatible string.
  • parent(), child(...), isParentOf(...), and lastSegment() let you navigate the path tree safely.
• Parser rules (Path::fromString):
  • Dots split attribute segments: map.nested.attr
  • Brackets denote list indexes: list[0][10]
  • Double quotes wrap a segment to allow dots: attr1."some.nested.attribute".attr2
  • Inside quotes only \" escapes a quote; backslash is otherwise literal
  • Quotes are not allowed inside brackets
• Limitations:
  • Negative indexes and empty segments are rejected at construction time (string parser or programmatic API).
  • Quoted segments support only \" escaping; other escape sequences are treated literally.
  • Path does not marshal attribute values; combine evaluated expressions with your own DynamoDB encoder.

Key

Description:

• Factory to build key conditions (hash/range) for queries. Use with KeyConditionBuilder to combine.

Examples:

Notes:

• Other helpers on Key: beginsWith(), greaterThan(), lessThanEqual(), etc.

Size (via Path)

Description:

• Wrapper to use the DynamoDB size() function on a path, returning a factory with condition helpers.

Examples:

Notes:

• Usually created through Path::create(...)->size(); constructing directly is rarely needed.

IfNotExists (via Path)

Description:

• Wrapper for if_not_exists(path, value) to use inside SET operations or nested operations.

Examples:

Notes:

• Typically used as a nested value in set() or arithmetic operations.

Builders

ConditionBuilder

Description:

• Fluent AND/OR composition of conditions. Supports passing other builders (auto-parenthesized evaluation inside) and static constructors.

Examples:

Notes:

• If no initial condition is set, .and()/.or() require at least two arguments.

KeyConditionBuilder

Description:

• Combines left and right key conditions with AND. Left condition is required; right is optional.

Examples:

Notes:

• A AND key condition should not be nested again as AND (guarded by the builder).

ProjectionBuilder

Description:

• Aggregates projected attributes (paths) into a Projection node.

Examples:

Notes:

• Projection evaluates to a comma-separated list with aliased names.

UpdateBuilder

Description:

• Collects actions (SET/REMOVE/ADD/DELETE) and groups them by action type before rendering.

Examples:

Nested operations for SET

Notes:

• DynamoDB evaluates update expression sections internally in the order REMOVE → SET → ADD → DELETE. The service accepts any section order in your request payload and normalizes it when processing.
• listPrepend() is a convenience helper: DynamoDB supports only list_append(left, right). Implementing a prepend behaviour strictly would require introducing dedicated wrapper objects for values so callers could control argument order, which would make the public API more awkward to use; instead the helper simply swaps the arguments to preserve the mental model (list_prepend(target, payload) → list_append(payload, target)).

Complex nested update

ExpressionBuilder

Description:

• Gathers optional parts (filter/condition/key condition/update/projection), evaluates through an Evaluator, and returns ExpressionContext.

Examples:

Notes:

• Empty parts are omitted from the output map.

Supporting Types

Deterministic String Conversion (debug/tests)

Nodes that implement Stringable or contain arrays/objects use a deterministic conversion in NodesToStringTrait:

• Stringable -> __toString()
• JsonSerializable -> json-encode jsonSerialize()
• Objects with toArray() -> json-encode that array
• Arrays -> json-encode recursively (stable output)
• Scalars -> true|false|null, numbers, strings
• Other objects -> object(FQCN) marker

Note: these conversions are intended for debugging, tests and logs only. Do not use them to build wire payloads for DynamoDB; use the evaluator output and, if needed, marshal values with your SDK/adapter.

⚠️ Recursive references and cyclic structures are not supported. Attempting to serialize such data will trigger an exception. Ensure arrays and objects form a finite, acyclic graph.

Attribute value aliases

• Each call to the values aliaser produces a fresh placeholder (:0, :1, …) even if the same PHP value is passed multiple times. This avoids ambiguity for mutable or complex payloads and keeps the generated expression consistent with the generated value map.

Errors from Path::fromString

Parser provides specific messages with processed prefix for:

• Empty attribute name (including trailing dot)
• Quoted attribute inside brackets
• Unmatched quote
• Nested brackets / unmatched bracket
• Invalid index (non-digit), negative index via programmatic APIs