Google's DoubleClick for Publishers API PHP Sample Web Application
==================================================================

This directory includes a sample PHP web application that uses the DFP API PHP
client library. The application displays a quick overview of the objects in your
account, includnig names, IDs, etc. The purpose of this application is to show
an example of how web applications can be built with the client library and to
provide a slim graphical interface to the sandbox environment to aid in your
development.

This README is intended for Apache 2.2.14 and PHP 5.2.11, but may be relevant
to other versions.


Requirements
------------

  1) Apache Web Server, with support for SSL.
     Example:

     ./configure \
       --prefix=/usr/local/apache \
       --enable-so \
       --enable-ssl

  2) PHP 5.2.x or 5.3.x, with support for SoapClient, curl, and SSL.
     Example:

     ./configure \
       --prefix=/usr/local/apache/php \
       --with-apxs2=/usr/local/apache/bin/apxs \
       --with-config-file-path=/usr/local/apache/php \
       --with-curl \
       --with-openssl \
       --enable-soap

  3) The OAuth PECL package.
     Example:

     pecl install oauth


Installation
------------

  1) Ensure that the DFP API PHP Client Library in the PHP include path. This
     can be done by either modifying the property "include_path" in the php.ini
     file, or by copying the content of the client library's "src" directory to
     the PHP lib directory.

       cp -R dfp_api_php_lib/src/* /usr/local/apache/php/lib/php/

  2) Copy this webapp directory to a location where your Apache service can
     access it.

       cp -R dfp_api_php_lib/webapp /var/www/dfpwebapp

  3) In the Apache configuration file (httpd.conf), grant directory level access
     to the webapp's public subdirectory for all users.

       <Directory "/var/www/dfpwebapp/public">
           Order allow,deny
           Allow from all
       </Directory>

  4) In the Apache configuration file, create an alias to the webapp's public
     subdirectory.

       Alias /dfpwebapp /var/www/dfpwebapp/public

  5) If your environment requires a proxy or other settings then edit
     the settings.ini configuration file located in the webapp root directory.
     Settings are loaded from this file instead of the one included with the
     client library.

  6) Start (or restart) Apache.

  7) Ensure the application is installed by loading index.php in your browser.

       http://localhost/dfpwebapp/index.php


Directory structure
-------------------

This web application is organized as follows:

  /lib              Classes created for the application
  /public           Files that can be requested by the browser
  /public/css       Cascading stylesheets
  /public/get       PHP files that are loaded via JavaScript and return short
                    snippets of HTML
  /public/imgages   Images
  /public/js        JavaScript files


General best practices
----------------------

  1) Reuse services during the course of a PHP execution.

     Creating a new service has a marginal cost associated with fetching the
     WSDL and allocating resources. If possible, create the services once at
     the beginning of an execution and make them available to classes and
     functions as needed.

  2) Use paging when fetching objects.

     All of the services support a get*ByFilter() method, which allows for the
     filtering of results using PQL syntax. The LIMIT and OFFSET clauses can
     be used to split large result sets into pages, preventing time outs and
     keeping the response under the maximum size limit of 500. An example of
     paging can be found in the following class:

     src/Google/Api/Ads/Dfp/Util/ServiceUtils.php

  3) Batch update requests.

     When changing multiple objects of the same type, better performance can be
     realized by sending all of the objects in the same update*() request.
     There is a marginal overhead on the client and the server for each request,
     and batching can be an effective means of reducing the number of requests.


Web application best practices
------------------------------

  1) Store the DfpUser in the session, when appropriate.

     When creating a DfpUser an authToken is automatically
     requested from the ClientLogin service. This process has some overhead
     and excessive requests to the ClientLogin service can lead to a temporary
     lock on your account. For these reasons, we recommend storing the
     DfpUser object in the PHP session, so that it can be reused
     across multiple requests.

  2) Don't store services in the session.

     Individual services, generated by the DfpUser, can not
     be stored in the session. These services extend the internal SoapClient
     class, which is not serializable. When retrieved from the session, a
     service is returned as an instance of __PHP_Incomplete_Class.


Where do I submit bug reports and feature requests?
---------------------------------------------------

Bug reports and feature requests can be submitted to the issue tracker

  http://code.google.com/p/google-api-dfp-php/issues/list

Questions can be posted to the DFP API forum:

  http://groups.google.com/group/google-doubleclick-for-publishers-api/

Authors:
  api.arogal@gmail.com (Adam Rogal)
  api.ekoleda@gmail.com (Eric Koleda)
  api.shamjeff@gmail.com (Jeff Sham)

Maintainers:
  api.arogal@gmail.com (Adam Rogal)
  api.ekoleda@gmail.com (Eric Koleda)
  api.shamjeff@gmail.com (Jeff Sham)