Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



The PHP Development Server

The App Engine PHP SDK includes a web server application you can run on your computer that simulates your application running in the App Engine PHP runtime environment. The simulated environment enforces some sandbox restrictions, such as restricted system functions and PHP module imports, but not others, like request time-outs or quotas. The server also simulates the services by performing their tasks locally.

  1. Running your own PHP interpreter in the development server
  2. Running the development web server
  3. Application IDs in the development web server
  4. Storing data in the development web server
  5. The Users service in the development web server
  6. Using Mail
  7. Using URL Fetch
  8. Local debugging with XDebug
  9. The Development Console
  10. Command-line arguments

Running your own PHP interpreter in the Development Server

The Mac OS X and Windows PHP SDKs include binaries for the PHP 5.4 runtime so there is usually no need to install PHP separately for the purposes of developing with App Engine. However, the local development environment that is installed with the SDK is missing the enabled extensions mcrypt and gd, so if you want to simulate their use in your local development environment, you may wish to install your own PHP php-cgi interpreter.

When running the Development Server from the command line, you can specify that your custom version of the PHP execuable be used with the --php_executable flag, eg.

google_appengine/dev_appserver.py --php_executable_path=/opt/local/bin/php-cgi54 path/to/your/app

Building a custom interpreter on Mac OS X using MacPorts

On Mac OS X, you can install a custom PHP interpeter with gd and mycrypt using MacPorts . If you don't already have MacPorts installed, you should follow the installation instructions (including the installation of Xcode).

Once MacPorts is installed, you can install PHP 5.4 with the following command. (Note: This example also demonstrates how to install mcrypt along with PHP 5.4):

sudo /opt/local/bin/port install php54-cgi php54-APC php54-calendar \
php54-exif php54-gd php54-mysql php54-oauth php54-openssl php54-soap \
php54-xdebug php54-xsl php54-mcrypt

After installation, the php-cgi (the binary used by the PHP SDK) can be found at /opt/local/bin/php-cgi54 .

Running the development web server

Once you have a directory for your application and an app.yaml configuration file, you can start the development web server with the dev_appserver.py command:

google_appengine/dev_appserver.py path-to-your-app

The web server listens on port 8080 by default. You can visit the application at this URL: http://localhost:8080/ .

To change which port the web server uses, use the --port option:

google_appengine/dev_appserver.py --port=9999 path-to-your-app

To stop the web server: with Mac OS X or Unix, press Control-C or with Windows, press Control-Break in your command prompt window.

Application IDs in the development web server

If you need to access your App ID, for example to spoof an email address, use the AppIdentityService::getApplicationId function. To get the hostname of the running app, use the AppIdentityService::getDefaultVersionHostname function.

Storing data in the development web server

Google App Engine for PHP supports reading and writing to Google Cloud Storage via PHP's streams API. A developer can read to and write from an object in Google cloud storage by specifying it as a URI to any PHP function that supports PHPs Streams implementation such as fopen() , fwrite() or get_file_contents() .

In the Development Server, when a Google Cloud Storage URI is specified we emulate this functionality by reading and writing to temporary files on the user's local filesystem. These files are preserved between requests, allowing you to test the functionality on your local development environment before deploying your code to App Engine.

In the PHP development server streaming calls like fopen() , file_get_contents() on 'gs://' urls are mocked by reading and writing to the local filesystem.

The Users service in the development web server

App Engine provides a Users Service to simplify authentication and authorization for your application. The development web server simulates the behavior of Google Accounts with its own sign-in and sign-out pages. While running under the development web server, the createLoginURL and createLogoutURL functions return URLs for /_ah/login and /_ah/logout on the local server.

Using Mail

The development web server can send email for calls to the App Engine mail service. To enable email support, the web server must be given options that specify a mail server to use. The web server can use an SMTP server, or it can use a local installation of Sendmail .

To enable mail support with an SMTP server, use the --smtp_host , --smtp_port , --smtp_user and --smtp_password options with the appropriate values.

dev_appserver.py --smtp_host=smtp.example.com --smtp_port=25 \
    --smtp_user=ajohnson --smtp_password=k1tt3ns myapp

To enable mail support with Sendmail, use the --enable_sendmail option with a value of yes . The web server will use the sendmail command to send email messages with your installation's default configuration.

dev_appserver.py --enable_sendmail myapp

If mail is not enabled with either SMTP or Sendmail, then attempts to send email from the application will do nothing, and appear successful in the application.

Using URL Fetch

When your application uses the URL fetch API to make an HTTP request, the development web server makes the request directly from your computer. The behavior may differ from when your application runs on App Engine if you use a proxy server for accessing websites.

Local debugging with XDebug

If you have a debugger that is compatible with the XDebug debugger , and you have the xdebug module installed, it is possible to use XDebug with the Development Server to debug your local application. To enable XDebug on the Development Server on Linux or Mac OS X you need to perform two steps:

  1. Export the XDEBUG_CONFIG environment variable with an idekey for your IDE to connect to

    export XDEBUG_CONFIG="idekey=netbeans-xdebug remote_host=localhost"
    
  2. Invoke the Development Server with --php_remote_debugging=yes

The Development Console

The development web server includes a console web application. With the console, you can browse the local datastore, and interact with the application by submitting Python code to a web form.

To access the console, visit the URL http://localhost:8000 on your server.

Command-line arguments

The dev_appserver.py command supports the following command-line arguments:

--auto_id_policy=...

Deprecated. How the local datastore assigns automatic IDs. Options are sequential or scattered . The default is scattered .

--admin_host=ADMIN_HOST

Host name to which the local Development Console should bind (default: localhost).

--admin_port=ADMIN_PORT

Port to which the local Development Console should bind (default: 8000).

--clear_datastore=yes|no

Clears the datastore data and history files before starting the web server. The default is no .

--datastore_path=...

The path to use for the local datastore data file. The server creates this file if it does not exist.

--enable_sendmail

Uses the local computer's Sendmail installation for sending email messages.

--help

Prints a helpful message then quits.

--host=...

The host address to use for the server. You may need to set this to be able to access the development server from another computer on your network. An address of 0.0.0.0 allows both localhost access and hostname access. Default is localhost .

--log_level=...

The lowest logging level at which logging messages will be written to the console; messages of the specified logging level or higher will be output. Possible values are debug , info , warning , error , and critical .

--port=...

The port number to use for the server. Default is 8080 . If multiple servers are launched, they will be assigned subsequent ports (e.g. 8081 , 8082 , etc).

--logs_path=LOGS_FILE

By default, development server logs are stored in memory only. This option turns on disk storage of logs at the location specified by LOGS_FILE, making the logs available across server restarts. For example,

dev_appserver.py --logs_path=/home/logs/boglogs bog

--require_indexes=yes|no

Disables automatic generation of entries in the index.yaml file. Instead, when the application makes a query that requires that its index be defined in the file and the index definition is not found, an exception will be raised, similar to what would happen when running on App Engine. The default value is no .

--smtp_host=...

The hostname of the SMTP server to use for sending email messages.

--smtp_port=...

The port number of the SMTP server to use for sending email messages.

--smtp_user=...

The username to use with the SMTP server for sending email messages.

--smtp_password=...

The password to use with the SMTP server for sending email messages.

--storage_path=...

Path at which all local files (such as the Datastore, Blobstore files, Google Cloud Storage Files, logs, etc) will be stored, unless overridden by --datastore_path , --blobstore_path , --logs_path , etc.

--php_executable_path=...

Path to the php-cgi binary

--php_remote_debugging=yes|no

Set to yes to enable remote debugging with XDebug

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.