Download the PHP package smadeira/ministry-platform-api without Composer

Ministry Platform API Wrapper

For Laravel 8 support you need to download v5.x of the API wrapper

For dotenv 4.x support (including Laravel 7.x) you need to download v4.x of the API wrapper.

Note for v3: This API wrapper has been updated to work with dotenv version 3.0 (July 2019) and the new Ministry Platform oAuth changes (Spring 2018)

A PHP wrapper to access the Ministry Platform (MP) REST API. This version is updated to include the new changes to oAuth authentication rolling out in early 2018. Note that using the API implies a knowledge of the MP data model. The API gives you access to each table in the database. It is up to you to pull the right data (or POST the right data) to the tables and then make any connections.

For example, you could create groups using the API and then you could create Participants using the API. After that is done, you can create Group Participants to add your participants to a group. Because Group Participants depends on the IDs of the group and the participant, the order in which you add the data is important.

Installation

Include the Package

This package is installed via Composer and the following assumes you have installed and initialized Composer for the project. Please refer to the Composer web site for help on getting composer installed and your initial composer.json created.

To add the Ministry Platform API to your project, simply require this package:

Or, you can edit your composer.json file directly to add the Ministry Platform API:

Update the package

After including the API Wrapper with composer, do a composer update to download the dependencies required for the API wrapper to function.

The update command will download all the dependencies (including the API wrapper code) to the vendor diretory. Once this is done, you are ready to start development.

Mote: It's a good idea to run "composer update" every so often to download the latest version of the API wrapper and all of its dependencies. That's the beauty of Composer. It manages all of that for you so you don't have to.

Configuration

There are a few things that need to be done to configure the API wrapper to function in your environment.

Connection Parameters

This package makes use of vlucas/phpdotenv to manage configuration variables. In the root of your project, create a .env file with the following contents. Ensure you are using the correct URIs, client ID and secret for your installation.

Loading the API Wrapper

At the top of your code you will need to do a couple things to get access to the API Wrapper. You need to include autoload capabilities and load the config settings from the .env file

This is an example of what the top of a script might look like to use the Table API and the Stored Procedures API.

Usage

Usage is straight forward for client credentials flow. Authenticate and execute your request.
NOTE: if you are using Laravel and Authorization Code flow, check the laravel documentation in the documentation folder for a working code example.

Authentication

Assuming your .env parameters are correct, this will authenticate your code.

Execute select query

The API Wrapper uses the same syntax as the swagger page. You can define the table, the select statement, filter and orderBy clauses. This will return an array of events and then dump them to the screen. Note that the data uses the familiar MP brand of SQL which is consistent with the platform.

The whole script

Here is a whole script that gets events in the next 30 days.

Gets using POST

If your GET query string is too long, you can do a GET using the POST verb to get around the length limitation. postGet() will return all rows that meets the criteria (could be thousands of rows.)

POSTing new Records

Data can be written to database via HTTP POST request. The new data is specified in the record and all required fields must be provided. The record is an array of arrays (2D array) so multiple rows can be created in one API call. Note that even if you are creating only one row of data, the record data must still be a 2D array.

This example will add two participants to an event, each with the status of 02 Registered:

Updating Records via PUT

Existing data can be updated via the HTTP PUT request. The data to be updated requires the ID for the row (Event_ID, for example) and the fields to be updated. The new data is specified in the record. The record is an array of arrays (2D array) so multiple updates can be executed in one statement. Note that even if you are updating only one row of data, the record data must still be a 2D array. This PUT will update the participation status to 03 Attended

Note that in both POSTing and PUTing, the API will return the resulting records. If you only want to get back specific fields and not the whole record(s), you can specify those fields in the select() method. Effectively, the API is doing the POST or PUT and then returning the results of a GET all in one operation.

Deleting Records

Warning: Deleting can do really bad things to your database. Test in the sandbox! Use at your own risk. Once it's gone, it's gone.

Existing table rows can be deleted by calling the delete method and passing the id of the row to delete. For example, to delete the contact with contact_id of 24599, execute this command:

Deleting Multiple Records

Existing rows can be deleted in mass with the deleteMultiple() method

Executing Procedures

Procedures can be executed using the Procedures API endpoint. This example gets the selected contacts using a custom procedure written for our PCO integration.

Files Endpoints

The API wrapper now supports the files API operations. To load the Files API wrapper, do something like this:

Listing Files For A Record

Provide the table name and the record_id to get information about each file

Downloading Files for a Record

Using the FileId or the UniqueFileId, you can download the file. The API returns the file as a stream that you can save to a local file.

Uploading A File

You can upload a file and metadata to a table/record. This example includes some extra attributes.

Modify A File

You can modify an existing file (including swapping out the image)

Delete a File

Pass in the FileID of the file and delete it