How to perform Callbacks with GroupDocs PHP SDK

This article explains the basics of using PHP SDK callbacks. In this article I'll use the Convert API. Find information about other methods in the Swagger explorer.

Requirements

We already know how to install the Fatfree framework and prepare for creating the sample from the previous article. So lets start with the magic.

Theory

First of all let's familiarize ourselves with Callback and the logic we will implement.

Callback

A callback is something like "Action" in HTML forms, a URL that will be executed by the server when a job is done. In this article we will use the Convert API and Convert method to convert a file from DOC to PDF. One of parameters of this method is a callback URL.

The logic

  1. User enters data into the form.
  2. The data is transfered by POST to the controller.
  3. The controller processes the received data (converts the file) and writes the user ID and private key to the text file for the Callback handler. After that, the controller returns the converted file GUID to the template.
  4. After conversion, the server calls the callback handler.
  5. The callback handler reads the user ID and private key from text file and makes a request to the Storage API to download the converted file.
  6. At same time that the server calls the callback URL, the template file shows the conversion results in an iframe and sends an Ajax request to the Ajax handler.
  7. The Ajax handler checks the "downloads" folder for the downloaded file. If file is there, handler gets the file name and returns it to the template.
  8. If file was downloaded, Ajax also sends a request to the download file handler to generate the download file dialog.

Practice

Now we must create our files:

  • The first file is the template file in the template folder.
  • The second file is the controller which is saved to the inc_samples folder.
  • THe other two files live in the callbacks subfolder in the inc_samples folder.

The structure looks like this:

As you can see from screenshot we must create five files:

  1. template.htm
  2. controller.php
  3. convert_callback.php
  4. check_file.php
  5. download_file.php

So let's start in stages.

template.html

In the template folder, create the template.htm file. This file shows the page with the input form and performs an Ajax request. Now put in this code:

 

I will not explain the HTML part of this code since it is a usual HTML document. But we have a JavaScript so let's take a look at that.

First we must include a Jquery library for Ajax requests. This code in the "Head" is responsible for this:

After that we can use Ajax. Now the Ajax code:

 

As Jquery is a JavaScript library we must use the <script></script> tag's. This code starts work 5 sec. after the page is loaded. The delay is necessary in order that the iframe with results is loaded. First of all we must check if this is first time the page is loaded. For this reason we use this check:

After this check, the script shows message and receives all elements from the document. Then the script builds and sends an Ajax request to the check_file controller. When the controller returns the downloaded file name, Ajax sends it to the download_file controller.

controller.php

Now lets do the next step and see what our base controller looks like. In the inc_samples folder, create a file _controller.php file. This file gets form data from the template and makes requests to the Async API to convert the file. Also this controller creates a text file with the user ID and private key for the callback controllers because we can't send this data any other way and the callback controller will be requested only by the server by the callback URL.

Now I'll show you the controller.php code. Put it in:

 

I won't go through the code in detail: each line is explained in the comments. But I'll explain briefly what the code doing.

We have two functions, Convert and delFolder, which do all the work. First of all, we receive POST data from the template and check if all the required fields are filled in. If they are, the controller creates a text file and writes the user ID and private key to it. After that follows the creation of the GroupDocsRequestSigner, APIClient and Async API objects so that we can send request to the API. So we have created all the objects and now we can convert the file. To do this we only need to call the convert method and transfer to it the:

  • user ID,
  • GUID of the file in the GroupDocs account which will be converted
  • callback URL
  • format to convert the file to.

Now we have converted the file but we need the GUID of the converted file and only the job ID is returned from the converted method. No problem, lets take 5 sec. to rest. The 5 sec. delay is necessary so that the inquiry can be be processed. After the delay, we take the returned job ID and make new request to the Async API but now with GetJobDocuments which returns all the info we need by job ID. Now we have the GUID for the converted file and can give this GUID to the iframe URL and return the URL to the template which will use it in the iframe source.

The second function checks the downloads folder for old files and deletes them.

convert_callback.php

Next, let's take a look at the callback controller, convert_callback.php. This file gets the callback from server, takes the data the server sends and downloads the converted file.

This controller reads the user ID and private key from the text file. Then it gets the raw data from the server inquiry. In this raw data we have the job ID. Use this like in the previous controller to get the converted file. To do this we must create all the objects again: GroupDocsRequestSigner, APIClient and Async API. After that we can make a request using the GetJobDocuments method to get the file GUID and name. Use this data for the GetFile method to download the converted file to the downloads folder.

check_file.php

At the same time that the convert_callback controller is working, we see that the page is reloaded and shows the iframe with the converted file. When the iframe is loaded, Ajax sends its request to the check_file controller.

The check_file controller looks like this:

This controller opens the downloads folder and gets all files from it. If there are no files, the controller waits for 5 sec. and checks again. When the file is downloaded and appear in the folder, the controller get the name and returns it to Ajax which sends the file name to the download_file controller.

download_file.php

The download_file generates the download dialog.

Here we take full local path to the downloaded file and transfers it to the download dialog.

Program in action

On that we are finished! Let me show you what it looks like in action:

The input form

The input form

 

Ajax message

Ajax message

Iframe with converted file

Iframe with converted file

 

Download dialog (FireFox)

Download dialog (FireFox)

Share and Enjoy:

    Back to top