pcbowers/php-airtable

PHP Airtable Wrapper for the Airtable API

1.1.0 2019-08-12 21:32 UTC

Requires

• php: >=5.3.3

MIT

• Chris Bowers

README

PHP Airtable Wrapper for the Airtable API

Recent Updates

NEW You can now do updates that allow elements to be removed if necessary. See updateRecords for more details.

NEW Typecast is now an option by default. New select options will be automatically created rather than throwing errors.

Getting Started

Follow these steps to successfully implement this PHP Airtable Wrapper.

NOTE: The Airtable API allows one to implement basic CRUD functions on records, but does not allow you to make changes to the schema of the tables. Use their interface to make changes to the schema

Getting your API Key and Base ID

Two tokens are required to use this wrapper: an api token, and a base id. Follow these steps to get the token:

1. Login to Airtable and click your profile picture.
2. Click on "Accounts".

1. Scroll down to "<> API".
2. Copy the personal API Key.

1. Navigate to the base you want to access with this wrapper.
2. Click on the Help icon.
3. Click on "<> API Documentation".

1. Look at the URL and find the portion of the url that begins with 'app'.
2. Copy your base ID.

Class Installation

You can either use composer or download the classes directly. To download using composer, run the following command:

composer require pcbowers/php-airtable

If you are using composer, run the autoloader to include the various classes in your project:

require 'vendor/autoload.php';

If you downloaded the classes directly, include the airtable.php file:

include('../src/airtable.php');

Initialize the Class

Use the following code snippet with your API Key and Base ID to begin using the wrapper:

use \pcbowers\Airtable\airtable;
$airtable = new Airtable(array(
    'api_key' => 'api_key',
    'base_id' => 'base_id'
));

Examples

A number of examples are placed below to help use this wrapper. The examples assume that the class has already been initiated.

getApiKey & getBaseId

Returns the API Key and Base ID respectively for a specific instance.

Code Example:

echo $airtable->getApiKey() . "<br />";
echo $airtable->getBaseId();

Result:

your_api_key
your_base_id

listRecords

Returns a list of records from a given table. Empty fields from records are not returned.

$table_name: String. Required.
$params: Array. All parameters are optional.

For more details on accepted parameters, see the airtable documentation.

A special parameter not included on the Airtable API has been added called checkOffset. This paramater defaults to true but can be set to false. It allows you to return just 1 page of results instead of looping through all of them.

This has been tested on an Airtable base with a table containing 50,000 records and 31 columns of data. Due to varying internet connections and usages of the data, speeds cannot be estimated. However, the broader the search, the slower this will run. Therefore, in some use cases, it may be important to set checkOffset to false to increase load times even though you will only get a portion of the data. Alternatively, you can set the maxRecords lower. Ideally, you want to keep your requests at a maximum of 1 page which can be calculated by maxRecords / pageSize. It is recommended that this number stay at 5 or less for optimal load speeds.

Code Template:

$airtable->listRecords($table_name, array(
    "fields" => array(strings),
    "filterByFormula" => string,
    "maxRecords" => number,
    "pageSize" => number,
    "sort" => array(objects),
    "view" => string,
    "cellFormat" => string,
    "timeZone" => string,
    "userLocale" => string,
    "checkOffset" => true
));

Code Example:

print_r($airtable->listRecords("Users", array(
    "fields" => array("First Name", "Last Name"),
    "sort" => array(array("field" => "First Name", "direction" => "asc")),
    "maxRecords" => 100
)));

Result:

Array of records. Contains:
    - up to 100 records
    - 'First Name' and 'Last Name' field
    - id of each record along with the created time
    - sorted by 'First Name ascending'

Because checkOffset was not set to false, all pages possible were returned.

retrieveRecord

Retrieves a specific record from a given table. Empty fields from record are not returned.

$table_name: String. Required.
$record_id: String. Required.

Code Template:

$airtable->retrieveRecord($table_name, $record_id);

Code Example:

print_r($airtable->retrieveRecord("Users", "recfauP0XQTTgXMQK"));

Result:

Array with all the information from one record that is not empty.

createRecord

Create a record in a given table.

$table_name: String. Required.
$data: Array. Optional (though recommended).

Code Template:

$airtable->createRecord($table_name, array(
    "field_name1" => "field_value1",
    "field_name2" => "field_value2"...
));

Code Example:

print_r($airtable->createRecord("Users", array(
    "First Name" => "Joe",
    "Last Name" => "Smith"
)));

Result:

On success, the created record is returned with the field information and id of the record.

updateRecord

Update a specific record from a given table.

$table_name: String. Required.
$record_id: String. Required.
$data: Array. Optional (though recommended).
$destructive: Boolean. Optional. Default false.
A value of false runs a PATCH update leaving data untouched if not edited.
A value of true runs a PUT update which destroys the instance and updates it with only the new data added.

**NEW** A value of "false" (not a boolean, but string "false") mixes the 2:
- A "false" value runs a PUT update which destroys the instance.
- However, unlike a normal PUT update, the new data is mixed with the old data.
- Fields left unmentioned will still remain in the record.
- Fields mentioned will be updated in the record.
- Fields mentioned and left as a blank string or array will be removed from the record.
- Fields that are not allowed to be edited must be included as empty values in $data (i.e. Formula Fields)

Code Template:

$airtable->updateRecord($table_name, $record_id, array(
    "field_name1" => "field_value1",
    "field_name2" => "field_value2"...
), $destructive);

Code Example:

print_r($airtable->updateRecord("Users", "recAkSf8l5IpITPV8", array(
    "First Name" => "Joe1",
    "Last Name" => "Smith1"
)));

Result:

On success, updated record returned with the new information.
$destructive was not set to true, so the rest of the record's information remained intact.

deleteRecord

Deletes a specific record from a given table.

$table_name: String. Required.
$record_id: String. Required.

Code Template:

$airtable->deleteRecord($table_name, $record_id);

Code Example:

print_r($airtable->deleteRecord("Users", "recU84ywe5m1md4wP"));

Result:

On success, returns the fact that it was deleted along with the id of the deleted record.

getLastLog & getLog

Error logging is supported so that your program does not crash on request errors. Any of the functions that require Curl Requests will return false on failure or the record(s) at hand on success. On top of that, each failure or success is logged within the wrapper instance. The following code shows how to access the log:

Code:

print_r($airtable->getLog());
echo "<br />";
print_r($airtable->getLastLog());

Result:

your_entire_log
last_entry_of_log