page_type	products	languages	extensions
sample	office-365 office-sp	php	contentType createdDate samples 10/7/2014 10:31:59 AM

PHP App for SharePoint sample

This sample will help you get started building an app for SharePoint that uses PHP.

SharePoint add-in model is considered as a legacy option for extending SharePoint user interface. Please see SharePoint Framework documentation and the SharePoint Framework samples for the future proven option to extend SharePoint Online. Possible backend services should be using Azure Active Directly based registration and related app models.

Table of Contents

• Overview
• Prerequisites
• Configure the sample
• Run the sample
• Project Files

Overview

The app model in SharePoint lets you build apps without tying you to a particular technology. You can use the language and tools of your preference to work on the components and pages that constitute your app.

We built this sample to get you started in building an app for SharePoint that uses PHP.

This sample is a provider-hosted app for SharePoint that gets an access token by using the OAuth 2.0 client library for PHP. A PHP page uses the token to issue an authenticated request to a REST endpoint in SharePoint.

Figure 1. PHP App for SharePoint conceptual diagram

Simple, but it illustrates the basic concepts that you need to know to start building apps for SharePoint using your favorite technology, PHP.

Prerequisites

This sample requires the following:

• Web server with PHP version 5.3 or higher.
• SharePoint site on Office 365. Join the Office 365 Developer Program and get a free 1 year subscription to Office 365.

Configure the sample

You must complete the following tasks to configure the sample:

1. Get the dependencies using composer
2. Create a web application in your web server
3. Register your app in SharePoint
4. Update the config.php file
5. Update the client_id in the app manifest
6. Deploy the app to the SharePoint site

Get the dependencies

The sample uses the OAuth 2.0 client library for PHP. You can use Composer to get the library. Follow this procedure to get the dependencies:

1. In a command prompt, go to the folder where you cloned or downloaded this project.
2. Go to the PHP folder.
3. Type composer install

Composer downloads the dependencies required by the project.

Create a web application

The sample is configured to use a web application that resolves to PHPAppWeb. To make it easier to configure your app we recommend that you use PHPAppWeb as your web application name. Follow this procedure to create the web application:

1. Create a web application on your web server with a name of PHPAppWeb.
2. Map the web application physical path to the PHP folder included in the sample.

Note: The web application must be configured to use SSL.

Register your app in SharePoint

Since you're not installing the app from the Office Store, you must register your app in SharePoint before deploying it. Follow this procedure to register the app:

1. Open a browser and go to https://yoursharepointsite/_layouts/15/appregnew.aspx
2. Fill the following fields in the page:
   • Client Id - Click the Generate button to let SharePoint create a value for you.
   • Client Secret - Click the Generate button to let SharePoint create a value for you.
   • Title - PHPAppforSharePoint
   • App Domain - localhost
   • Redirect URI - https://localhost/phpappweb/index.php
3. Copy the values and store for future reference. You'll need them to update the configuration and app manifest files.
4. Click Create.

Note: If you specify a title other than PHPAppforSharePoint you must update the Name attribute of the App element in the app manifest accordingly.

Update the configuration file

The sample requires the client_id, and client_secret values from the app registration page in the previous task. To update the values in the config.php file, follow this procedure:

1. Open the config.php file provided in this sample in a text editor.

2. Copy the client_id, and client_secret values that you got in the previous task to the placeholders in the file.

   $client_id = "<your client_id value>";
   $client_secret = "<your client_secret value>";
   

3. Save the config.php file.

Update the app manifest

The AppTemplate.app file is an app package that contains the app manifest file. You have to update the app manifest file with the client_id value obtained in the Register your app in SharePoint task. Follow this procedure to update the app manifest file:

1. Go to the root folder of the sample.

2. Rename the AppPackage.app file provided in this sample to AppPackage.zip

3. Open the zip file and extract the AppManifest.xml file.

4. Edit the AppManfest. xml file. Replace with the Client Id value from the app registration page.

   <AppPrincipal>
       <RemoteWebApplication ClientId="<your client_id value>"/>
   </AppPrincipal>
   

5. Replace the AppManifest.xml file in the zip file.

6. Rename the AppPackage.zip file back to AppPackage.app

Note: The updated AppPackage.app file must keep the same file structure as the original. Moving files or folders can invalidate your package.

Deploy the app to the SharePoint site

You can deploy the app using the app catalog that lets administrators deploy business apps to SharePoint sites in the tenant.

1. If you don't have an app catalog site in your tenant, create one. For more information, see Create an App Catalog site collection.
2. Add the AppTemplate.app file to the app catalog. For more information, see Add custom apps to the App Catalog site.
3. Go to the SharePoint site where you want to deploy the app. From the Settings menu (the gear in the top right corner of the page) choose Add an app.
4. Choose the PHP App for SharePoint app. In the consent page, choose Trust It.

Run the sample

To run the sample, simply click on the PHP App for SharePoint app in the SharePoint site contents page. To find the contents page go to your site, click on the Settings menu (the gear in the top right corner of the page), and choose Site contents.

Project Files

The sample includes the following components that help you configure and test the app in your environment.

SharePoint.php

This is a PHP class that inherits from the AbstractProvider class. The AbstractProvider class exposes a function to get a token that you can use to issue authorized requests.

The class initializes the values required to get the access token. The constructor requires the client id, client secret, SharePoint site URL, and a context token as parameters. The constructor extracts and formats the following values from the context token:

• Refresh token
• Token service URI
• Resource

After creating a SharePoint provider object, PHP pages can call the getAccessToken method of the AbstractProvider class to get a token and use it in HTTP requests.

Example page

Index.php is an example that shows you how to use the SharePoint provider class. The page does the following:

• Checks that the request is using the POST method. If the request is using GET instead it tells the user to start the app from the SharePoint site contents page.
• Initializes a SharePoint provider instance.
• Gets an access token using the getAccessToken function of the AbstractProvider class.
• Issues an authenticated request to a REST endpoint exposed by the SharePoint site.
• Prints the result to the browser.

Configuration file

The index.php page reads the following configuration values from the config.php file:

• client_id
• client_secret

You can get these values from the app registration page in SharePoint. For more information, see Update the configuration file.

Example app package

The AppPackage.app file is an app for SharePoint package that you can use to deploy and test your app.

Copyright

Copyright (c) Microsoft. All rights reserved.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.