Category Archives: appengine

Getting Started with the Cloud Datastore on PHP App Engine


In this post, we’ll show how to access the Google Cloud Datastore from a PHP App Engine app.

This is the first in a series of posts on using the Cloud Datastore on PHP App Engine.
The code for the examples in this post is here: (Some of the files in this repo won’t be mentioned in this post, but will be referenced in the post that follows this one).

PHP on Google App Engine supports several alternatives as for a persistent store. One is the Cloud Datastore, a distributed, robust, fully managed, schemaless database, which supports transactions and scales automatically.
(If you have built App Engine apps for other runtimes, this is the same Datastore that you’ve used before; it now supports an HTTP interface as well).
This article assumes that you already have a basic familiarity with Datastore concepts.

There is not yet a native Datastore API for PHP on app engine. So, instead we’ll show how to use the Cloud Datastore API to connect to the Datastore from your PHP app.
First, we’ll show how to configure your app and associated Cloud Project so that your app will be able to connect to the Datastore.

Then, we’ll look at how to use the Google API client libraries as a basis for authenticating with the Datastore, sending requests, and receiving responses, and we’ll build a DatastoreService class to make connecting a bit easier.

Continue reading

App Engine 1.8.8

App Engine 1.8.8 has just been released, and the PHP runtime has some great updates:

Getting started with Laravel on PHP for App Engine


This article walks through the process of deploying a Laravel 4 app to the App Engine PHP runtime.

Laravel is a web application framework that supports common tasks used in the majority of web projects, such as authentication, routing, sessions, and caching.

The Laravel 4 Starter Kit developed by Bruno Gaspar demos a simple blog application, and is a nice example of how to use the Laravel framework itself, as well as some of its packages. It should get you started on how to define and deploy your own app. If you’re not familiar with Laravel, you will find it useful to look over its documentation as well.

We’ll look at how to deploy this ‘starter kit’ app to App Engine.

Thanks and credit to Gilles Mergoil, who authored this blog post on running Laravel on a previous release of App Engine.

Continue reading

What’s new for PHP runtime in the App Engine 1.8.3 release

Today we announced the 1.8.3 release of App Engine, which contains a bunch of spiffy new features and fixes for the PHP runtime. It’s worthwhile highlighting some of the new features and changes in this release.

Whitelisted users are now able to deploy PHP to any of their apps.

If your user account has previously been whitelisted for a PHP application, then you can now use PHP with any of your applications, including new ones. This includes applications located in the European Union.

Environment variables that are set in app.yaml are now available in the PHP runtime.

You can now pass environment variables to your application by defining them in your app.yaml file. These variables will be available using the getenv function call or from the $_SERVER superglobal.

To configure environment variables, add them to your app.yaml file using the env_variables section.

foo: 'bar'
baz: 'zoo'

Your application will then be able to read these environment variables back at runtime.

>>> echo getenv('foo');

Read-through cache for Google Cloud Storage

We’ve added a read-through cache for Google Cloud Storage files that are being accessed through our stream wrapper. By default, we cache files as you read them in memcache, and on subsequent reads we will retrieve the file from memcache and return the contents if they have not changed.

To determine if the contents of a file have changed or not, we make a request to Google Cloud Storage. So in the case of a file that has not changed, we don’t need to retrieve the contents, but we still need to incur the penalty of at least 1 round trip to Google Cloud Storage.

If you have an application where you know the files are not going to change once they’re written, or you’re prepared to occasionally be served stale file contents, then you can skip the contents change check by enabling optimistic caching of the file. With optimistic caching on, if we find the file in memcache, we will return the contents without checking that the file is still current, so no additional roundtrip call to Google Cloud Storage is performed.

You can configure read caching using the stream context options that you pass when opening the file.

$gs_options = [ 'gs' => [
      "enable_cache" => true,  // true by default, false disables all read caching
      "enable_optimistic_cache" => true,  // false by default, true enables optimistic caching
      "read_cache_expiry_seconds" => 3600,  // Number of seconds that reads are cached in memcache.

We will invalidate the read cache if you write to the file from your application, so that it is cached again on the next read. Note that we don’t invalidate the cache if the file is changed from outside of your application by directly uploading to the bucket, or on a rename.

Using the Google APIs Client Library for PHP with App Engine

Important Note: Newer releases of the Google APIs client have support for App Engine out of the box, making this article obsolete.

Download the latest version from the github repository.

The Google API Client library allows you to work with Google APIs such as Analytics, Adsense, Google+, Calendar, Drive or Games easily from your application. Recent versions of the client library include support for HTTP streams, which makes it simple to use the library from an App Engine application just by tweaking the configuration file.

Follow these steps to get the client library up and running.

  1. Download the latest release package of the client.
  2. Extract the library from the archive and copy the google-api-php-client directory to your project root.
  3. Edit the file google-api-php-client/src/config.php, and configure the client to use HTTP streams and memcache by making the following changes to the $apiConfig array.
        // Which Authentication, Storage and HTTP IO classes to use.
        'authClass'    => 'Google_OAuth2',
        'ioClass'      => 'Google_HttpStreamIO',
        'cacheClass'   => 'Google_MemcacheCache',
        // We need to configure fake values for memcache to work
        'ioMemCacheCache_host' => 'does_not_matter',
        'ioMemCacheCache_port' => '37337',
  4. Test that the client is working correctly by following the Google Plus example on the client home page.

Note that to use the API client from your application, you’ll need to follow the instructions for using OAuth 2.0 with your application.

In a follow-up post we’ll show you how to use the Google API client to access the Google Cloud Datastore from your application.

Harnessing The Power of Versions On App Engine

One powerful, but often overlooked, feature of running applications on App Engine is the ability to have multiple versions of your application deployed and running simultaneously. This feature is invaluable when it comes to being able to “smoke test” a new version of your site live in production before your users can see it. Or you can use traffic splitting to allow you to test different versions of your site against live traffic in a controlled and deterministic fashion.

The release of WordPress 3.5.2 is a great opportunity for us to demonstrate how to use versions to do a controlled upgrade of our WordPress blog to the latest version.

A Note About App Engine Versions

Before we get started on the steps for running multiple versions of your application, we should briefly describe application versions and the default version. App Engine allows you to deploy up to 10 versions of your application to the production servers. Versions are completely independent of each other, and in fact versions can even be using different runtimes – so you can deploy a PHP application and a Java application as different versions of the same appspot application and run them simultaneously. Versions are identified by the version string that you specify either in the app.yaml file or as a command line paramater when using the tool. If you specify the version as a command line option then it will override the version that is supplied in the app.yaml file.

The first time that you upload your application to the production servers, it will become the default version, and all user requests will be served using that version. If you upload a new version of your application with a new version identifier, then it will not serve any user requests until you go into the admin console and either mark it as the default version or enable traffic splitting (more detail about both are later in this post). If you use a version identifier that matches an already uploaded version, then it will overwrite the old version with the new one. If that version happens to be the default version, then it will start serving immediately.

Now we know a little about versions, we can go about using them to upgrade our version of WordPress we’re using.

Step 1: Uploading The New Version Of Your Site.

The first step to running a new version is actually uploading the updated version of your site to the production servers. The steps outlined below assume that you have setup your WordPress source code following the instructions on the Running WordPress page. We will get the latest version of WordPress and unpack it to the APPLICATION_DIRECTORY directory as mentioned in that article, using the following steps.

$ wget

You should now run the site in your development environment to ensure that it behaves as you expect it to (once again, following the instructions on the Running WordPress page).


Once you’re satisfied that the site is running as you would expect in the development environment, you can upload it to the production servers. We’ll use the --version flag of to upload the site with a new version number, that differs from the exiting version. In this example, we’ll use today’s date and the postfix “-352″ as the version identifier.

$ -R --version 20130624-352 update .

The appcfg tool will now upload a new version of your site. One interesting thing to note is that the tool will only upload files to the server that are different to existing files that you’ve previously uploaded in an existing version. This results in very fast uploads for new versions of large site that have only a small number of changes to the source.

You should see output similar to what’s shown below

10:53 AM Host:
10:53 AM Application: gae-php-tips; version: 20130624-352 (was: wp-0501)
10:53 AM Starting update of app: gae-php-tips, version: 20130624-352
10:53 AM Getting current resource limits.
10:53 AM Scanning files on local disk.
10:53 AM Checking if deployment succeeded.
10:53 AM Deployment successful.
10:53 AM Checking if updated app version is serving.
10:53 AM Completed update of app: gae-php-tips, version: 20130624-352
10:53 AM Uploading cron entries.

You can now go to the admin console for you site and view the new version that was just uploaded.

Screen Shot 2013-06-24 at 11.02.41 AM

As you can see from the screen shot, the new version has successfully uploaded, but our site is still serving live traffic from the existing version labelled “17062013”.

Step 2: Manually Testing The New Version

App Engine versions allow you to access any of the deployed versions of your site by prepending the correct version specifier to the site address. In our example here, I can access the new version of by entering the url in the address bar of my browser.

Note: We use this feature to deploy phpMyAdmin side by side with WordPress in our application. You can see a version named “phpmyadmin” in the list of deployed versions.

Step 3: Traffic Splitting Live Traffic To The New Version.

Now that we’ve deployed the new version of the site and manually tested that it serves as we expect, we can now start sending it live traffic. We have two options for serving traffic from this applcation.

  • Make the new version the default version so that it handles all requests for the site.
  • Use traffic splitting to send a percentage of users to the new version, to assess its stability before making it the default.

In this example, we’ll use traffic splitting to ensure that the new version of the site is stable before making it the default. To get started, click on the traffic splitting link on the versions page for your site. It will present the option to enable traffic splitting which will look like this.

Screen Shot 2013-06-24 at 11.17.03 AM

From here click on the “Add Traffic Split…” button to configure traffic splitting. You will be asked to select the version that you want to split traffic to, and the percentage of traffic to split to the new version. Select the version that you just uploaded and the amount of traffic you want to send it (in my case, 25%).

Screen Shot 2013-06-24 at 11.17.26 AM

Once you click on OK App Engine will enable traffic splitting using the configuration that you’ve supplied. A reminder that traffic splitting is enabled will be shown on your admin console page for the site.

Screen Shot 2013-06-24 at 11.17.42 AM

Your site is now serving a percentage of user requests with the new version of your site.

Step 4: Monitoring The New Version.

You can use the application logs to verify that the new version of your site is serving without errors. At the top of the logs page it allows you to view logs for a specific  version. Using this, you can quickly drill down if the new version of your site is serving correctly.

Screen Shot 2013-06-24 at 11.31.34 AM

You can see that these are the logs for the versions 17062013 which is currently serving 75% of the traffic for the site, while below are the logs for a new version 20130624-352 which is serving 25% of the traffic for our site.

Screen Shot 2013-06-24 at 11.30.58 AM

Step 5: Making The New Version The Default

Once we’re satisfied that the new version of the site is performing correctly, we can switch it over to be the default for all user requests.To do this, we go back to the versions page in the admin console for our site. By selecting the radio button next to the new version and pressing Make Default, the traffic split will be dropped and the new version will handle all live traffic.

Screen Shot 2013-06-24 at 11.38.29 AM

You could also roll back to the older version of the app by removing the traffic split, or change the split percentage if you want to gradually increase the traffic load on the new version over time.

Notes About Running Multiple Versions

One important thing to consider when running multiple versions of your site, is that each different version of your site requires at least one running instance to serve from. These instances are charged independently, so that if you are traffic splitting on a free site you are likely to run out of the free quota during one 24 hour billing period.

Another thing to consider when running multiple versions is that all versions share the same database. If there is a schema change to the database for a new version, the older versions may not function correctly. In our example we upgraded from WordPress 3.5.1 to 3.5.2 which uses the same schema so we could serve both versions from the same database. If you want to run multiple versions that have different schemas then you use separate databases for each version. You could use the backup and restore functionality of CloudSQL create a copy of your live database for the new version.

Announcing the Google App Engine WordPress plugin

Screen Shot 2013-06-13 at 5.23.09 PM

Today we officially launched the Google App Engine Plugin for WordPress. We’ve also put the source of the plugin on github for those of you who might be inclined to want to modify of add functionality.

The plugin wires together some code WordPress features with App Engine APIs, for now including:

  • Sending e-mail using the Mail API.
  • Uploading and serving media files to Google Cloud Storage.

Full details on how to install the plugin, as well as optimally configure your WordPress site can be found in this detailed post on


Tips For Configuring The Plugin

The plugin is very easy to configure. Currently there are only two options that you need to be concerned with, EMail Settings and Upload Settings.

Email Settings

Screen Shot 2013-06-13 at 8.19.42 PM

To enable sending of Email using the App Engine Mail API select the checkbox “Use App Engine Email Service”. By default, mail will be sent from, but you can change the address to one of the allowed sender addressed as described here.

Upload Settings

Screen Shot 2013-06-13 at 8.24.47 PM

To configure the upload settings, all you need to provide the name of a Google Cloud Storage bucket that the application has permission to write to. You can follow the instructions here to correctly associate your application to a bucket. Once you have done this, simply enter the bucket name in the correct field to enable uploads to that bucket.

When you try and save the settings, the plugin will attempt to write a test file to the bucket to ensure that your application has write permissions. If your application cannot write to the bucket you will be shown a warning at the top of the configuration screen, as shown below.

Screen Shot 2013-06-13 at 8.24.37 PM

Once your configuration settings are correct press save, and your WordPress site will be ready to send mail and handle media uploads.

What’s new for PHP in the App Engine 1.8.1 Release

Today we publicly announced the 1.8.1 release of Google App Engine, and as part of this release we’ve added a bunch of new features for the PHP runtime. The highlights of what’s new includes:

  • Three more runtime extensions:
  • The ability to include and/or require files PHP scripts from Google Cloud Storage.
  • Better support for url_stat of items in Google Cloud Storage.
  • Support for application files with ‘@’ in their name.
  • Honor the default_stream_context() when using the Google Cloud Storage stream wrapper.
  • Added the CloudStorageTools::deleteImageServiceUrl() call for the high speed image serving service.
  • Fixed a bug where $_SERVER[“PHP_SELF”] was including the query string of the URL.
  • Removed the Capabilities API.
  • Simplified the types of exceptions that can be thrown from the Users API.

Including Files From Google Cloud Storage

As mentioned, with this release we’ve made it possible to include and/or require script files from Google Cloud Storage.

To enable this feature, you must list the buckets that you want to include files from in your applications php.ini file. The bucket names can be specified as a comma separated list to the google_app_engine.allow_include_gs_buckets ini setting.

google_app_engine.allow_include_gs_buckets = "my_bucket"

Once you have configured the bucket, you can then include the files directly in your PHP application code.


require_once "gs://my_bucket/file.php";

The ideal use case for storing script files in Google Cloud Storage is for the intermediate files generated by various templating frameworks. Accessing script files from Google Cloud Storage is slower than accessing files that have been uploaded as part of you application and these files cannot take advantage of the powerful versioning system that App Engine provides.