README

Bego 是一个 PHP 库，可以简化 DynamoDb 表的操作。

与模型一起工作

创建表的模型类

<?php

namespace App\MyTables;

class Music extends Bego\Model
{
    /**
     * Table name
     */
    protected $_name = 'Music';

    /**
     * Table's partition key attribute
     */
    protected $_partition = 'Artist';

    /**
     * Table's sort key attribute
     */
    protected $_sort = 'SongTitle';

    /**
     * List of indexes available for this table
     */
    protected $_indexes = [
        'My-Global-Index' => ['key' => 'Timestamp'],
        'My-Local-Index' => []
    ];
}

实例化一个表

在您的应用程序中实例化所需的表...

$config = [
    'version' => '2012-08-10',
    'region'  => 'eu-west-1',
    'credentials' => [
        'key'    => 'test',
        'secret' => 'test',
    ],
];

$db = new Bego\Database(
    new Aws\DynamoDb\DynamoDbClient($config), new Aws\DynamoDb\Marshaler()
);

$music = $db->table(new App\MyTables\Music());

与查询一起工作

您可以通过复合主键（分区键和排序键）查询任何 DynamoDb 表或二级索引

/* Query the table */
$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->filter(Condition::attribute('Year')->eq(1966))
    ->fetch(); 

/* Query a global index */
$results = $music->query('My-Global-Index')
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->filter(Condition::attribute('Year')->eq(1966))
    ->fetch(); 

/* Query a local index */
$results = $music->query('My-Local-Index')
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->filter(Condition::attribute('Year')->eq(1966))
    ->fetch(); 

键条件和过滤表达式

可以添加多个键条件/过滤表达式。DynamoDb 将键条件应用于查询，但过滤应用于查询结果

$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->beginsWith('How'))
    ->filter(Condition::attribute('Year')->in(['1966', '1967']))
    ->fetch(); 

降序排序

DynamoDb 默认按排序键值升序排序结果。要获取降序结果，可以使用 reverse() 标志

$results = $music->query()
    ->reverse()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->fetch(); 

投影属性

要仅获取一些而不是所有属性，请使用投影表达式。

$results = $music->query()
    ->key('Bob Dylan')
    ->projection(['Year', 'SongTitle'])
    ->condition(Condition::attribute('SongTitle')->beginsWith('How'))
    ->filter(Condition::attribute('Year')->eq('1966'))
    ->fetch(); 

与结果集一起工作

结果集对象实现了 Iterator 接口，并可以直接使用。它还提供了一些方便的方法。

/* Execute query and return first page of results */
$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->fetch(); 

foreach ($results as $item) {
    echo "{$item->attribute('Id')}\n";
}

echo "{$results->count()} items in result set\n";
echo "{$results->getScannedCount()} items scanned in query\n";
echo "{$results->getQueryCount()} trips to the database\n";
echo "{$results->getQueryTime()} total execution time (seconds)\n";

$item = $results->first();

$item = $results->last();

//Get the 3rd item
$item = $results->item(3); 

//Extract one attribute from all items
$allTitles = $results->attribute('SongTitle'); 

//Aggregegate one attribute for all items
$totalSales = $results->sum('Sales'); 

一致性读取

DynamoDb 默认执行最终一致性读取。对于强一致性读取，请设置 consistent() 标志

$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->consistent()
    ->fetch(); 

限制结果

DynamoDb 允许您限制返回结果中项目数。请注意，此限制仅应用于键条件。DynamoDb 将在结果集上应用过滤条件

$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->limit(100)
    ->fetch();

分页

DynanmoDb 限制结果为 1MB。因此，必须实现分页才能遍历第一页之后的页面。有两种选项可用于分页操作

$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'));

/* Option 1: Get one page orf results only (default) */
$results = $query->fetch();

/* Option 2: Execute up to 10 queries */
$results = $query->fetch(10); 

/* Option 3: Get all items in the dataset no matter the cost */
$results = $query->fetch(null);

在某些情况下，可能需要在多个跳转之间进行分页;

$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'));

/* First Hop: Get one page */
$results = $query->fetch(1);
$pointer = $results->getLastEvaluatedKey();

/* Second Hop: Get one more page, continueing from previous request */
$results = $query->fetch(1, $pointer); 

消耗的容量单位

DynamoDb 可以计算每个查询的读取容量单位总数。这可以通过 consumption() 标志启用

$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->consumption()
    ->fetch();

echo $results->getCapacityUnitsConsumed();

执行扫描

支持基本表扫描。过滤表达式、结果和分页与查询相同

/* Scan the table */
$results = $table->scan()
    ->filter('Artist', '=', $artist)
    ->consistent()
    ->consumption()
    ->limit(100)
    ->fetch();

/* Scan the secondary index */
$results = $table->scan('My-Global-Index')
    ->filter(Condition::attribute('Year')->eq(1966))
    ->fetch();

创建项目

/* Create and persist a new item */
$item = $music->put([
    'Id'        => uniqid(), 
    'Artitst'   => 'Bob Dylan',
    'SongTitle' => 'How many roads'
]);

获取项目

/* Fetch an item */
$item = $music->fetch(
    'Bob Dylan', 'How many roads'
);

if ($item->isEmpty()) {
    throw new \Exception("Requested record could not be found");
}

if ($item->isSet('hit')) {
    echo "{$item->attribute('SongTitle')} is a hit";
}

echo $item->attribute('Id');

/* Perform a consistent read */
$item = $music->fetch(
    'Bob Dylan', 'How many roads', true
);

if ($item->isEmpty()) {
    throw new \Exception("Requested record could not be found");
}

echo $item->attribute('Id');

与项目属性值一起工作

/* Return value if attribute exists, otherwise NULL */
echo $item->attribute('Artist');
echo $item->Artist; //shorthand

/* Return value if attribute exists, otherwise throw exception */
echo $item->ping('Artist');

/* Checking if an attribute exists and not empty */
echo $item->isSet('Artist') ? 'Yes' : 'No';
echo isset($item->Artist) ? 'Yes' : 'No'; //shorthand

更新项目

/* Update an item */
$item->set('Year', 1966);
$item->Year = 1966; //shorthand

$result = $music->update($item);

$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->filter(Condition::attribute('Year')->eq(1966))
    ->fetch(); 

foreach ($results as $item) {
    $item->set('Year', $item->attribute('Year') + 1);
    $music->update($item);
}

使用项目的魔术属性而不是 set() 和 attribute()

/* Update an item */
$item->Year = 1966;

$result = $music->update($item);

$results = $music->query()
    ->key('Bob Dylan')
    ->condition(Condition::attribute('SongTitle')->eq('How many roads'))
    ->filter(Condition::attribute('Year')->eq(1966))
    ->fetch(); 

foreach ($results as $item) {
    $item->Year = $item->Year + 1;
    $music->update($item);
}

条件更新

use Bego\Condition;

$conditions = [
    Condition::attribute('Year')->beginsWith('19')
    Condition::attribute('Year')->exists()
    Condition::attribute('Year')->eq(1966)
    Condition::attribute('Year')->in([1966, 1967])
];

$result = $music->update($item, $conditions);

if ($result) {
    echo 'Item updated successfully'
}

删除项目

$music->delete($item);

创建表（实验性）

$spec = [
    'types'     => [
        'partition' => 'S',
        'sort'      => 'S',
    ],
    'capacity'  => ['read' => 5, 'write' => 5],
    'indexes'   => [
        'My-Global-Index' => [
            'type'     => 'global',
            'keys' => [
                ['name' => 'Year', 'types' => ['key' => 'HASH', 'attribute' => 'N']],
                ['name' => 'Artist', 'types' => ['key' => 'RANGE', 'attribute' => 'S']],
            ],
            'capacity' => ['read' => 5, 'write' => 5]
        ],
    ],
];

$music->create($spec);