The Google Cloud SDK and App Engine SDK for PHP each include a local development server that you can run locally to simulate your application running in production App Engine. 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 local development server also simulates the services provided by the libraries in the SDK for App Engine, including Datastore, Memcache, and Task Queues, by performing their tasks locally. Note that when your application is running in the development server, you can still make remote API calls to the production infrastructure using Google APIs HTTP endpoints.
Running the local development server
After you create the
configuration file for your app, you can start the local development server with
dev_appserver.py command to run your app locally.
To start the local development server:
Running the local development server (
To run the local development server, you can either run
specifying the full directory path or you can add
dev_appserver.py to your
PATH environment variable:
If you installed the App Engine SDK, the tool is located at
If you installed the Google Cloud SDK, the tool is located at
Tip: To add the Google Cloud SDK tools to your PATH and enable command-completion in your bash shell, you can run:
dev_appserver.pycommand as follows from the directory that contains your app's
Specify the directory path to your app, for example:
Alternatively, you can specify the configuration file of a specific service, for example:
To change the port, you include the
dev_appserver.py --port=9999 [PATH_TO_YOUR_APP]
If you're on Linux or if you want to use a custom version of
php-cgi, you need to specify the directory path to the
- Build your own version of App Engine PHP Extension on your local machine.
Start the local development server with both the
dev_appserver.py --php_executable_path=[PATH_TO_PHP_CGI] --php_gae_extension_path=[PATH_TO_APPENGINE_EXTENSION] app.yaml
--php_executable_pathis the location of the PHP interpreter you are using, and where
--php_gae_extension_pathis the location of the
gae_runtime_module.sofile that you built in the previous step.
To learn more about the
dev_appserver.pycommand options, see Local Development Server Options.
The local development server is now running and listening for requests. You
can visit http://localhost:8080/ in your
web browser to see the app in action.
If you specified a custom port with the
--portoption, remember to open your browser to that port.
To stop the local server from the command line, you press the following:
- Mac OS X or Linux: Control-C
- Windows: Control-Break
Specifying application IDs
If you want to use application IDs with the local development server, don't use
the App ID from the
APPLICATION_ID environment variable. The development
server differs from production App Engine service in that the local server
prepends the string
dev~ to the
APPLICATION_ID environment variable.
Instead, if you need to access your App ID in the local server, for example to
spoof an email address, use the
function. To get the hostname of the running app, use the
Google App Engine for PHP supports reading and writing to
Google Cloud Storage via PHP's streams
API. You can read and write to Cloud Storage by specifying a
Cloud Storage URI (
gs://) when using any PHP function that supports
PHP Streams implementation such as
The local development server emulates this functionality by reading and writing to temporary local files that are preserved between requests.
Browsing the local Datastore
If your app has written data to your local Datastore using the local development server, you can browse it in the local development console.
To browse local Datastore:
Access the Datastore Viewer in the local development console. (The URL is
View your local Datastore contents.
Using the Users service
App Engine provides a
Users Service to simplify
authentication and authorization for your application. The local development
server simulates the behavior of Google
with its own sign-in and sign-out pages. While running under the local
development server, the
functions return URLs for
/_ah/logout on the local server.
The local development server can send email for calls to the App Engine mail service using either an SMTP server or a local installation of Sendmail.
To enable mail support with an SMTP server, invoke
dev_appserver.py --smtp_host=smtp.example.com --smtp_port=25 \ --smtp_user=ajohnson --smtp_password=k1tt3ns [PATH_TO_YOUR_APP]
where you set the
--smtp_password options with your own values.
To enable mail support with Sendmail, invoke
dev_appserver.py as follows:
dev_appserver.py --enable_sendmail=yes [PATH_TO_YOUR_APP]
The local server will use the
sendmail command to send email messages with
your installation's default configuration.
Using URL Fetch
When your application uses the URL fetch API to make an HTTP request, the local development server makes the request directly from your computer. The URL Fetch behavior on the local server may differ from production App Engine if you use a proxy server for accessing websites.
Debugging locally with XDebug
If you have a debugger that is compatible with the
XDebug debugger, and you have the
installed, you can use XDebug with the local development server.
To enable XDebug on the Development Server on Linux or Mac OS X:
Export the XDEBUG_CONFIG environment variable with an idekey for your IDE to connect to
export XDEBUG_CONFIG="idekey=netbeans-xdebug remote_host=localhost"
Invoke the Development Server with