PHPackages                             aiotu/terseq - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. aiotu/terseq

ActiveLibrary[Database & ORM](/categories/database)

aiotu/terseq
============

Query Builder for AWS DynamoDB

v0.2.1(11mo ago)011.1kMITPHPPHP ^8.3CI passing

Since May 11Pushed 11mo ago1 watchersCompare

[ Source](https://github.com/ishutin/terseq)[ Packagist](https://packagist.org/packages/aiotu/terseq)[ RSS](/packages/aiotu-terseq/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (18)Used By (0)

Terseq: AWS DynamoDB Query Builder
==================================

[](#terseq-aws-dynamodb-query-builder)

[![codecov](https://camo.githubusercontent.com/4e01ca6e49120c18ee2beea3eb72e83e0f21a7e82445fc6f21fdbf9311910ef3/68747470733a2f2f636f6465636f762e696f2f67682f6973687574696e2f7465727365712f67726170682f62616467652e7376673f746f6b656e3d534c5832314544484231)](https://codecov.io/gh/ishutin/terseq)

This document provides a comprehensive guide on how to utilize the Terseq library to build and execute queries on AWS DynamoDB using the AWS SDK for PHP.

Features
--------

[](#features)

### Terseq supports building queries for the following DynamoDB operations:

[](#terseq-supports-building-queries-for-the-following-dynamodb-operations)

#### Single-item operations

[](#single-item-operations)

- [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)
- [PutItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)
- [UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)
- [DeleteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html)

#### Query operations

[](#query-operations)

- [Query](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)

#### Transactions

[](#transactions)

- [TransactGetItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html)
- [TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html)

#### Batch

[](#batch)

- [BatchGetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html)
- [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html)

Why I should use this library?
------------------------------

[](#why-i-should-use-this-library)

AWS SDK for PHP is a powerful tool for working with AWS services, but it can be challenging to use due to its complexity. It requires a lot of boilerplate code to build and execute queries. Terseq simplifies this process by providing a fluent interface to build queries for DynamoDB operations. It also supports single-table design, which is a recommended practice for DynamoDB.

Installation
------------

[](#installation)

To install the Terseq package, run the following command in your project directory using Composer:

```
composer require aiotu/terseq
```

Usage
-----

[](#usage)

### Initialize

[](#initialize)

#### Create client by AWS SDK and DatabaseManager

[](#create-client-by-aws-sdk-and-databasemanager)

```
$client = new \Aws\DynamoDb\DynamoDbClient([
    'region' => 'us-west-2',
    'version' => 'latest',
]);

$manager = new \Terseq\DatabaseManager($client, new Marshaler());
```

### Operations

[](#operations)

#### GetItem

[](#getitem)

```
$manager->getItem()
    ->table(['Books', 'BookId'])
    ->pk('super-cool-id')
    ->dispatch();
```

#### PutItem

[](#putitem)

```
$manager->putItem()
    ->table(['Books', 'BookId'])
    ->item([
        'BookId' => 'super-cool-id',
        'Title' => 'Super Cool Book',
        'Author' => 'Super Cool Author',
    ])
    ->dispatch();
```

#### UpdateItem

[](#updateitem)

```
$manager->updateItem()
    ->table(['Books', 'BookId'])
    ->pk('super-cool-id')
    ->set('Title', 'Super Cool Book Updated')
    ->set('Author', 'Super Cool Author Updated')
    ->dispatch();
```

#### DeleteItem

[](#deleteitem)

```
$manager->deleteItem()
    ->table(['Books', 'BookId'])
    ->pk('super-cool-id')
    ->dispatch();
```

#### Query

[](#query)

```
$result = $manager->query()
    ->table(['Books', 'BookId'])
    ->pk('super-cool-id')
    ->consistentRead()
    ->dispatch();
```

#### TransactGetItems

[](#transactgetitems)

```
use Terseq\Builders\Operations\TransactGetItems\Operations\Get;

$manager->transactGetItems()
    ->get(
            [
                static fn (Get $get) => $get->pk('super-cool-id1'),
                static fn (Get $get) => $get->pk('super-cool-id2'),
            ],
            table: ['Books', 'BookId'],
        )
    ->dispatch();
```

#### TransactWriteItems

[](#transactwriteitems)

```
use Terseq\Builders\Operations\TransactWriteItems\Operations\Delete;
use Terseq\Builders\Operations\TransactWriteItems\Operations\Put;
use Terseq\Builders\Operations\TransactWriteItems\Operations\Update;

$manager->transactWriteItems()
    ->put(
        [
            fn (Put $put) => $put->item([
                'BookId' => 'super-book1',
                'Author' => 'Unknown',
            ]),
            fn (Put $put) => $put->item([
                'BookId' => 'super-book-2',
                'Author' => 'Incognito',
            ]),
        ],
        table: ['Books', 'BookId'],
    )
    ->update(
        fn (Update $update) => $update
            ->pk('super-book-3')
            ->set('Author', 'Incognito'),
        table: ['Books', 'BookId'],
    )
    ->delete(
        fn (Delete $delete) => $delete->pk('super-book-4'),
        table: ['Books', 'BookId'],
    )
    ->dispatch();
```

#### BatchGetItem

[](#batchgetitem)

```
use Terseq\Builders\Operations\BatchGetItem\Operations\BatchGet;

$manager->batchGetItem()
    ->get(
        fn (BatchGet $get) => $get
            ->pk('super-book-1')
            ->pk('super-book-2')
            ->composite('book-id', 'release-date'),
        table: ['Books', 'BookId'],
    )
    ->dispatch();
```

#### BatchWriteItem

[](#batchwriteitem)

```
$manager->batchWriteItem()
    ->put(
        [
            'BookId' => 'super-book-1',
            'Author' => 'Unknown',
        ],
        table: ['Books', 'BookId'],
    )
    ->put(
        [
            'BookId' => 'super-book-2',
            'Author' => 'Incognito',
        ],
        table: ['Books', 'BookId'],
    )
    ->delete(
        'super-book-3',
        table: ['Books', 'BookId'],
    )
    ->dispatch();
```

Table
-----

[](#table)

### Table as object (recommended)

[](#table-as-object-recommended)

#### Example of using table object

[](#example-of-using-table-object)

```
use Terseq\Builders\Table;
use Terseq\Builders\Keys;

class Books extends Table
{
    public function getTableName(): string
    {
        return 'Books';
    }

    public function getKeys(): Keys
    {
        return new Keys(partitionKey: 'BookId', sortKey: null);
    }
}
```

#### Example with [secondary indexes](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.SecondaryIndexes)

[](#example-with-secondary-indexes)

```
use Terseq\Builders\Table;
use Terseq\Builders\Keys;

class BooksTable extends Table
{
    /**
     * Table name
     */
    public function getTableName(): string
    {
        return 'Books';
    }

    /**
     * Partition key and sort key (optional)
     */
    public function getKeys(): Keys
    {
        return new Keys(partitionKey: 'BookId', sortKey: 'ReleaseDate');
    }

    /**
     * Secondary index map (optional) also known as GSI and LSI
     */
    public function getSecondaryIndexMap(): ?array
    {
        return [
            'AuthorIndex' => new Keys(partitionKey: 'AuthorId', sortKey: 'BornDate'),
            'GenreIndex' => new Keys(partitionKey: 'GenreId', sortKey: 'GenreName'),
            'LsiExample' => new Keys(partitionKey: 'BookId', sortKey: 'AuthorBornYear'),
        ];
    }
}
```

### Table as array

[](#table-as-array)

```
table(table: ['TableName', 'PartitionKey', 'SortKey']);
```

OR

```
table(table: ['TableName', 'PartitionKey']); // Sort key by default is null
```

OR

```
table(table: ['TableName']); // throws exception, because PartitionKey is required
```

OR

```
table(table: [
    'table' => 'TableName',
    'pk' => 'PartitionKey',
    'sk' => 'SortKey',
]);
```

Single-table design (recommended)
---------------------------------

[](#single-table-design-recommended)

Library supports [single-table design](https://aws.amazon.com/blogs/compute/creating-a-single-table-design-with-amazon-dynamodb/).

### Example of using single-table design

[](#example-of-using-single-table-design)

```
$manager = new \Terseq\DatabaseManager(
    client: $client,
    marshaler: new Marshaler(),
    singleTable: new class extends \Terseq\Builders\Table {
        public function getTableName(): string
        {
            return 'Books';
        }

        public function getKeys(): Keys
        {
            return new Keys(partitionKey: 'BookId');
        }
    },
);
```

That's all! Now you can build queries without passing table name and keys.

#### Usage

[](#usage-1)

```
// Query
$manager->getItem()->pk('super-cool-id')->dispatch();

$manager->batchWriteItem()
    ->put(
        [
            'BookId' => 'super-book-1',
            'Author' => 'Unknown',
        ],
    )
    ->put(
        [
            'BookId' => 'super-book-2',
            'Author' => 'Incognito',
        ],
    )
    ->delete('super-book-3')
    ->dispatch();
```

Comparison with AWS SDK
-----------------------

[](#comparison-with-aws-sdk)

### Example of using AWS SDK

[](#example-of-using-aws-sdk)

```
$client->updateItem(
    [
        'TableName' => 'Books',
        'UpdateExpression' => 'SET #Title = :title_0, #Author = :author_0',
        'ExpressionAttributeNames' =>
            [
                '#Title' => 'Title',
                '#Author' => 'Author',
            ],
        'ExpressionAttributeValues' =>
            [
                ':title_0' =>
                    [
                        'S' => 'Super Cool Book Updated',
                    ],
                ':author_0' =>
                    [
                        'S' => 'Super Cool Author Updated',
                    ],
            ],
        'Key' =>
            [
                'BookId' =>
                    [
                        'S' => 'super-cool-id',
                    ],
            ],
    ],
);
```

### Example of using Terseq for the same operation

[](#example-of-using-terseq-for-the-same-operation)

```
$manager->updateItem()
    ->table(['Books', 'BookId'])
    ->pk('super-cool-id')
    ->set('Title', 'Super Cool Book Updated')
    ->set('Author', 'Super Cool Author Updated')
    ->dispatch();
```

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance52

Moderate activity, may be stable

Popularity20

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~24 days

Recently: every ~57 days

Total

17

Last Release

339d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/15d781e31280a63b309807cf43e41cbc53d7486ce7d3fd07161531e3b92e5229?d=identicon)[ishutin](/maintainers/ishutin)

---

Top Contributors

[![ishutin](https://avatars.githubusercontent.com/u/1905737?v=4)](https://github.com/ishutin "ishutin (68 commits)")

---

Tags

awsdynamodbquerybuilderterseq

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/aiotu-terseq/health.svg)

```
[![Health](https://phpackages.com/badges/aiotu-terseq/health.svg)](https://phpackages.com/packages/aiotu-terseq)
```

###  Alternatives

[baopham/dynamodb

Eloquent syntax for DynamoDB

4975.7M6](/packages/baopham-dynamodb)[envms/fluentpdo

FluentPDO is a quick and light PHP library for rapid query building. It features a smart join builder, which automatically creates table joins.

925511.7k13](/packages/envms-fluentpdo)[anourvalar/eloquent-serialize

Laravel Query Builder (Eloquent) serialization

11320.2M21](/packages/anourvalar-eloquent-serialize)[lichtner/fluentpdo

FluentPDO is a quick and light PHP library for rapid query building. It features a smart join builder, which automatically creates table joins.

921274.8k6](/packages/lichtner-fluentpdo)[clancats/hydrahon

Fast & standalone PHP MySQL Query Builder library.

281205.5k5](/packages/clancats-hydrahon)[kettle/dynamodb-orm

A lightweight object-dynamodb mapper for PHP

49210.0k](/packages/kettle-dynamodb-orm)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)