Download the PHP package a1comms/php-gds without Composer

On this page you can find all versions of the php package a1comms/php-gds. 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?

Example code of a1comms/php-gds

Informations about the package php-gds

Build Status Coverage Status

Google Cloud Datastore Library for PHP

Library VERSION 4, October 2017

Google Cloud Datastore is a great NoSQL solution (hosted, scalable, free up to a point), but it can be tricky (i.e. there's lots of code glue needed) to get even the "Hello World" of data persistence up and running in PHP.

This library is intended to make it easier for you to get started with and to use Datastore in your applications.

Datastore API Turn Down, Sep 2016

Google turned down the older versions of the REST API on September 30th, 2016. Version v1beta1 and v1beta2 are no longer available.

Table of Contents

Examples

I find examples a great way to decide if I want to even try out a library, so here's a couple for you.

You can also use the Alternative Array Syntax for creating Entity objects, like this

Now let's fetch all the Books from the Datastore and display their titles and ISBN numbers

More about the Examples

These initial examples assume you are either running a Google AppEngine application or in a local AppEngine dev environment. In both of these cases, we can auto detect the dataset and use the default Protocol Buffer Gateway.

We use a GDS\Store to read and write GDS\Entity objects to and from Datastore.

These examples use the generic GDS\Entity class with a dynamic Schema. See Defining Your Model below for more details on custom Schemas and indexed fields.

Check out the examples folder for many more and fuller code samples.

Demo Application

A simple guest book application

Application: http://php-gds-demo.appspot.com/

Code: https://github.com/tomwalder/php-gds-demo

New in Version 4.0

Changes in Version 3.0

Using the Datastore REST API v1 (Sep 2016)

The Datastore REST API v1 went Generally Available (GA) in 2016. The previous REST API will be deprecated after September 2016.

If you are running PHP-GDS from somewhere other than App Engine, you need to use the REST API v1.

You just have to pass an instance of the RESTv1 gateway into your Store objects on construction.

You might need to set an environment variable with the path to your JSON credentials file first.

You can find out more about the auth system here: Google Auth Library for PHP

You can download a service account JSON file from the Google Cloud Console API Manager > Credentials.

Changes in Version 2.0

Features in 2.0 included

Backwards Compatibility

v3 over v2

The REST API v1 implementation now follows the same datetime response formats at the ProtoBuf API. (Y-m-d H:i:s).

v2 over v1

The library is almost fully backwards compatible. And in fact, the main operations of the GDS\Store class are identical.

There is one BC-break in 2.0 - the re-ordering of construction parameters for the GDS\Store class.

GDS\Store::__construct(<Kind or Schema>, <Gateway>)

instead of

GDS\Store::__construct(<Gateway>, <Kind or Schema>)

This is because the Gateway is now optional, and has a sensible, automated, default - the new Protocol Buffer implementation.

Getting Started

Are you sitting comfortably? Before we begin, you will need:

If you want to use the JSON API from remote or non-App Engine environments, you will also need

Composer, Dependencies

To install using Composer, use this require line

"tomwalder/php-gds": "v4.*"

For older series

"tomwalder/php-gds": "v3.*"

"tomwalder/php-gds": "v2.*"

and for bleeding-edge features, dev-master

"tomwalder/php-gds": "dev-master"

Use with the GDS emulator

If you want to use it with the GDS emulator make sure the environment variable DATASTORE_EMULATOR_HOST is set with the host, for example localhost:8081

Defining Your Model

Because Datastore is schemaless, the library also supports fields/properties that are not explicitly defined. But it often makes a lot of sense to define your Entity Schema up front.

Here is how we might build the Schema for our examples, with a Datastore Entity Kind of "Book" and 3 fields.

By default, all fields are indexed. An indexed field can be used in a WHERE clause. You can explicitly configure a field to be not indexed by passing in FALSE as the second parameter to addString().

If you use a dynamic schema (i.e. do not define on, but just use the Entity name) then all fields will be indexed for that record.

Available Schema configuration methods:

Take a look at the examples folder for a fully operational set of code.

Creating Records

Alternative Array Syntax

There is an alternative to directly constructing a new GDS\Entity and setting its member data, which is to use the GDS\Store::createEntity factory method as follows.

Special Properties

Other than scalar values, there are two "object" data types supported:

DateTime

Support for DateTime object binding (also see query parameter binding below)

Geopoint

The library has recently had support added for Geopoint properties.

Then when setting data, use the Geopoint object

And when pulling geopoint data out of a result:

It is not currently possible to query Geopoint fields, although this feature is in Alpha with Google

Geopoint data is only supported using the native Protocol Buffer API. It will work well on App Engine and in development, but not via the JSON API

Queries, GQL & The Default Query

At the time of writing, the GDS\Store object uses Datastore GQL as its query language. Here is an example:

And with support for named parameter binding (strings, integers) (this is recommended)

Support for DateTime object binding

We provide a couple of helper methods for some common (root Entity) queries, single and batch (much more efficient than many individual fetch calls):

When you instantiate a store object, like BookStore in our example, it comes pre-loaded with a default GQL query of the following form (this is "The Default Query")

Which means you can quickly and easily get one or many records without needing to write any GQL, like this:

1000 Result Batch Limit

By default, this library will include a 1,000 record "batch size".

This means calling fetchAll() will only return 1,000 records.

I suggest paging your results if you need more than 1,000 records using fetchPage().

GQL on the Local Development Server

At the time of writing, the Google App Engine local development server does not support GQL. So, as of 2.0 I have included a basic GQL parser, which is only used in local development environments and should mean you can run most application scenarios locally as you can on live.

The GQL parser should be considered a "for fun" tool, rather than a production-ready service.

Feedback very much appreciated - if you have GQL queries that fail to run, just raise an issue and I'll see what I can do (or fork & PR!).

Pagination

When working with larger data sets, it can be useful to page through results in smaller batches. Here's an example paging through all Books in 50's.

Limits, Offsets & Cursors

In a standard SQL environment, the above pagination would look something like this:

Although you can use a very similar syntax with Datastore GQL, it can be unnecessarily costly. This is because each row scanned when running a query is charged for. So, doing the equivalent of LIMIT 5000, 50 will count as 5,050 reads - not just the 50 we actually get back.

This is all fixed by using Cursors. The implementation is all encapsulated within the GDS\Gateway class so you don't need to worry about it.

Bototm line: the bult-in pagination uses Cursors whenever possible for fastest & cheapest results.

Tips for LIMIT-ed fetch operations

Do not supply a LIMIT clause when calling

Pricing & Cursor References

Multi-tenant Applications & Data Namespaces

Google Datastore supports segregating data within a single "Dataset" using something called Namespaces.

Generally, this is intended for multi-tenant applications where each customer would have separate data, even within the same "Kind".

This library supports namespaces, and they are be configured per Gateway instance by passing in the optional 3rd namespace parameter.

ALL operations carried out through a Gateway with a namespace configured are done in the context of that namespace. The namespace is automatically applied to Keys when doing upsert/delete/fetch-by-key and to Requests when running GQL queries.

Further examples are included in the examples folder.

Entity Groups, Hierarchy & Ancestors

Google Datastore allows for (and encourages) Entities to be organised in a hierarchy.

The hierarchy allows for some amount of "relational" data. e.g. a ForumThread entity might have one more more ForumPosts entities as children.

Entity groups are quite an advanced topic, but can positively affect your application in a number of areas including

At the time of writing, I support working with entity groups through the following methods

Transactions

The GDS\Store supports running updates and deletes in transactions.

To start a transaction

Then, any operation that changes data will commit and consume the transaction. So an immediate call to another operation WILL NOT BE TRANSACTIONAL.

Watch out for GDS\Exception\Contention exceptions - they should be thrown by the library if you manage to hit Datastore contention locally in development or through the live Gateways.

Custom Entity Classes and Stores

Whilst you can use the GDS\Entity and GDS\Store classes directly, as per the examples above, you may find it useful to extend one or the other.

For example

This way, when you pull objects out of Datastore, they are objects of your defined Entity class.

The Schema holds the custom entity class name - this can be set directly, or via the Store object.

Re-indexing

When you change a field from non-indexed to indexed you will need to "re-index" all your existing entities before they will be returned in queries run against that index by Datastore. This is due to the way Google update their BigTable indexes.

I've included a simple example (paginated) re-index script in the examples folder, reindex.php.

Data Migrations

Using multiple Gateway classes, you can move data between namespaces

and between local and live environments.

Note: In both of these examples, the entities will be inserted with the same KeyID or KeyName

More About Google Cloud Datastore

What Google says:

"Use a managed, NoSQL, schemaless database for storing non-relational data. Cloud Datastore automatically scales as you need it and supports transactions as well as robust, SQL-like queries."

https://cloud.google.com/datastore/

Specific Topics

A few highlighted topics you might want to read up on

Unit Tests

A full suite of unit tests is in the works. Assuming you've installed php-gds and its dependencies with Composer, you can run

Click here for more details.

Footnotes

I am certainly more familiar with SQL and relational data models so I think that may end up coming across in the code - rightly so or not!

Thanks to @sjlangley for any and all input - especially around unit tests for Protocol Buffers.

Whilst I am using this library in production, it is my hope that other people find it of use. Feedback appreciated.

Other App Engine Software

If you've enjoyed this, you might be interested in my Full Text Search Library for PHP on Google App Engine

All versions of php-gds with dependencies

PHP Build Version
Package Version
Requires php Version >=5.5.0
ext-bcmath Version *
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 a1comms/php-gds contains the following files

Loading the files please wait ....