Download the PHP package bf-dsf/php-dynamodb-odm without Composer

On this page you can find all versions of the php package bf-dsf/php-dynamodb-odm. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package php-dynamodb-odm

Object Data Mapping component for DynamoDb

The bf-dsf/php-dynamodb-odm is an ODM (object data mapping) library for easy use of AWS' powerful key-value database: DynamoDb.

NOTE: this document assumes you have some understanding of what DynamoDB is and the difference between DynamoDB and traditional RDBMS (e.g. MySQL). Some terms and ideas discussed in this document are DynamoDB specific and will not be explained in this documentation. To study DynamoDB, please refer to the official dev guide

Installation & Configuration

To get bf-dsf/php-dynamodb-odm, you can simple require it via composer:

Class Loading

Autoloading for DynamoDb ODM is taken care of by composer. You just need to include the composer autoload file in your project:

Obtaining an ItemManager

Once you have prepared the class loading, you acquire an ItemManager instance. The ItemManager class is the primary access point to ODM functionality provided by the library.

The explanation of each argument can be found below:

argument description default value
awsConfig configuration array for aws SDK, profile and region are mandatory. mandatory
tablePrefix a prefix to table names mandatory
cacheDir cache direcotry to store metadata mandatory
isDev is development environment or not. Under dev environment, changes to Item class will automatically invalidate cached metadata. Under production environment, this has to be done manually. true
itemSrcDir a source directory under which Item classes can be found mandatory
itemNamespace the base namespace for the managed Item classes source directory mandatory

NOTE: an Item class defines a type of item managed by ODM. Some typical examples are: User, Order, GameRoom, and Card

Setting Up Command Line Tool

DynamoDb ODM ships with a number of command line tools that are very helpful during development. You can call this command from the Composer binary directory:

You need to register your application's ItemManager to the console tool to make use of the built-in command. This is done by creating an odm-config.php file under the calling directory, with the following content:

Detailed usage can be found in later section

Mapping

The fundamental functionality of an ODM library is to map object models (i.e. classes) to database sctructure. DynamoDb ODM provides a handy way to establish this mapping with the help of annotations:

The class above declares a simple User model, wich will be mapped to DynamoDb table "users" (possibly with a prefix). The annotations are explained below:

Item

Every PHP object that you want to save to database using ODM is referred to as an "Item". To describe an object as an item, we have to describe the class of this object.

Class annotated with the @Item annotation will be managed by ItemManager. An Item accepts the following attributes:

Field

The next step after making a PHP class an Item is mapping its properties to attributes in DynamoDb.

We use @Field annotation to describe class properties which are DynamoDb attributes. The @Field annotation supports following attributes:

Partitioned Hash Key

A partitioned hash key is an extension to fields used as hash key in queries. There are circumstances that you only want to query on a single value (or very few values) for that field. The nature of DynamoDB will only utilize a fraction of the read capacity assigned, and therefore limit your system performance. However, by using a partitioned hash key for that field, each value of the originial field will have a group of mapped values in the partitioned hash key field. By querying those partitioned values parallelly (see Multi Query), your query performace should be significantly improved in this use case.

We use @PartitionedHashKey annotation to describe the partitioned hash key field. The supported attributes are:

Index

When declaring different indexes, we can use the @Index annotation to make the docblock more readable. An @Index is composited with two keys:

Below is the User class declaration when we add a global secondary index to it:

Check and Set

A field and be declared as a check-and-set field, using the "cas" attribute of the @Field annotation.

A check-and-set field is a field ODM uses to make sure no single item is updated/inserted more than once by different workers at the same time.

The value of the "cas" property can be one of the following:

NOTE: Check-and-set validation is done only when you call ItemManger#flush(). Failure to meet the check and set condition(s) will lead to an BF\Mlib\ODM\Dynamodb\Exceptions\DataConsistencyException being thrown.

Working with Objects

All objects (items) in ODM are managed. Operations on objects are managed like object-level transaction. Once an object is managed, either by persisted as a new object or fetched from database, its managed state is stored in the ItemManager. Any change to the object will be recorded in memory. Changes to object can then be commited by invoking the ItemManager#flush() method on the ItemManager.

The ItemManager can be manually cleared by calling ItemManager#clear(). However, any changes that are not committed yet will be lost.

NOTE: it is very important to understand, that only ItemManager#flush() will cause write operations against the database. Any other methods such as ItemManager#persist($item) or ItemManager#remove($item) only notify the ItemManager to perform these operations during flush. Not calling ItemManager#flush() will lead to all changes during that request being lost.

Persisting Item

An item can be made persistent by passing it to the ItemManager#persist($item) method. By applying the persist operation on some item, that item becomes MANAGED, which means that its persistence is from now on managed by an ItemManager. As a result the persistent state of such an item will subsequently be properly synchronized with the database when ItemManager#flush() is invoked.

Example:

Removing Item

An item can be removed from persistent storage by passing it to the ItemManager#remove($item) method. By applying the remove operation on some item, that item becomes REMOVED, which means that its persistent state will be deleted once ItemManager#flush() is invoked.

Example:

Detaching Item

An item is detached from an ItemManager and thus no longer managed by invoking the ItemManager#detach($item) method on it. Changes made to the detached item, if any (including removal of the item), will not be synchronized to the database after the item has been detached.

DynamoDb ODM will not hold on to any references to a detached item.

Example:

Synchronization with the Database

The state of persistent items is synchronized with the database on flush() of an ItemManager. The synchronization involves writing any updates to persistent items to the database. When ItemManager#flush() is called, ODM inspects all managed, new and removed items and will perform the following operations:

Fetching Item(s)

DynamoDb ODM provides the following ways, in increasing level of power and flexibility, to fetch persistent object(s). You should always start with the simplest one that suits your needs.

By Primary Index

The most basic way to fetch a persistent object is by its primary index using the ItemManager#get($itemClass, $primayKeys) method. Here is an example:

The return value is either the found item instance or null if no instance could be found with the given identifier.

Essentially, ItemManager#get() is just a shortcut for the following:

By Simple Conditions on Queriable Index

To query for one or more items based on simple conditions, use the ItemManager#query() and ItemManager#queryAndRun() methods on a repository as follows:

NOTE: a simple condition is a condition that uses one and only one index. If the used index contains both hash key and range key, the range key may only be used when hash key is also presented in the condition. Furthermore, only equal test operation can be performed against the hash key.

By Using Multi Query on Partitioned Hash Key

To query for one or more items based on a PartitionedHashKey, use ItemManager#multiQueryAndRun() methods on a repository as follows:

By Filters on Non-Queriable Index

To query for one or more items which has no associated index, use the ItemManager#scan() and ItemManager#scanAndRun() methods on a repository as follows:

Using the Command Line Tool

DynamoDb ODM ships an executable tool together with the library. After installation, there are following built-commands which helps you manage the database schema for the items:

Create

The create command will iterate all managed items and create tables correspondingly. All primary index, LSIs and GSIs are created as well.

NOTE: if a table with the same name under the same prefix already exists, an exception will be thrown. No table will be created in this case.

NOTE: if you would like to skip creating existing table (i.e. only create non-existing tables), you can use the "--skip-existing-table" option

Update

The update command is actually a more powerful (and slower too) version of create command. It checks all managed items and creates the table if it doesn't exist. Furthermore, if a table exists but have different GSIs defined, the update command will update the GSIs accordingly.

NOTE: due to the nature of DynamoDb, it is not possible to update the primary index or LSI when a table is already created. Under dev environment, it is suggested to drop the table and re-create them when needed.

NOTE: if you would like to only see the changes to database schemas without perfoming actual update, you can specify the "--dry-run" option in command line. The program will only prompts possible changes withou actually performing them.

Drop

The drop command will drop all tables associated with the managed items. DO NOT run this command in production environment!


All versions of php-dynamodb-odm with dependencies

PHP Build Version
Package Version
Requires php Version ^7.1|^8.0
doctrine/annotations Version ~1.13
bf-dsf/aws-wrappers Version ^2.14
symfony/console Version ^5.4
symfony/finder Version ^5.4
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package bf-dsf/php-dynamodb-odm contains the following files

Loading the files please wait ....