PHPCap Docs | PHPCap API
Overview

Namespaces

  • IU
    • PHPCap
  • PHP

Classes

  • ErrorHandler
  • FileUtil
  • RedCap
  • RedCapApiConnection
  • RedCapProject

Interfaces

  • ErrorHandlerInterface
  • RedCapApiConnectionInterface

Exceptions

  • PhpCapException
  • Overview
  • Namespace
  • Class

Class RedCapProject

REDCap project class used to retrieve data from, and modify, REDCap projects.

Namespace: IU\PHPCap
Located at RedCapProject.php
Methods summary
public
+/- __construct( string $apiUrl, string $apiToken, boolean $sslVerify = false, string $caCertificateFile = null, IU\PHPCap\ErrorHandlerInterface $errorHandler = null, IU\PHPCap\RedCapApiConnectionInterface $connection = null )

Creates a REDCapProject object for the specifed project.

Creates a REDCapProject object for the specifed project.

Example Usage:

$apiUrl = 'https://redcap.someplace.edu/api/'; # replace with your API URL
$apiToken = '11111111112222222222333333333344'; # replace with your API token
$sslVerify = true;

# See the PHPCap documentation for information on how to set this file up
$caCertificateFile = 'USERTrustRSACertificationAuthority.crt';

$project = new RedCapProject($apiUrl, $apiToken, $sslVerify, $caCertificateFile);

Parameters

$apiUrl
the URL for the API for the REDCap site that has the project.
$apiToken
the API token for this project.
$sslVerify
indicates if SSL connection to REDCap web site should be verified.
$caCertificateFile

the full path name of the CA (Certificate Authority) certificate file.

$errorHandler

the error handler used by the project. This would normally only be set if you want to override the PHPCap's default error handler.

$connection

the connection used by the project. This would normally only be set if you want to override the PHPCap's default connection. If this argument is specified, the $apiUrl, $sslVerify, and $caCertificateFile arguments will be ignored, and the values for these set in the connection will be used.

Throws

IU\PHPCap\PhpCapException
if any of the arguments are invalid
public mixed
+/- exportArms( $format = 'php', array $arms = [] )

Exports the numbers and names of the arms in the project.

Exports the numbers and names of the arms in the project.

Parameters

$format

the format used to export the arm data.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
$arms

array of integers or numeric strings that are the numbers of the arms to export. If no arms are specified, then information for all arms will be returned.

Returns

mixed

For 'php' format, array of arrays that have the following keys:

  • 'arm_num'
  • 'name'
public integer
+/- importArms( mixed $arms, string $format = 'php', boolean $override = false )

Imports the specified arms into the project.

Imports the specified arms into the project.

Parameters

$arms

the arms to import. This will be a PHP array of associative arrays if no format, or 'php' format was specified, and a string otherwise. The field names (keys) used in both cases are: arm_num, name

$format

the format for the export.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
$override
  • false - [default] don't delete existing arms; only add new arms or renames existing arms.
  • true - delete all existing arms before importing.

Returns

integer
the number of arms imported.

Throws

IU\PHPCap\PhpCapException
if an error occurs.
public integer
+/- deleteArms( array $arms )

Deletes the specified arms from the project.

Deletes the specified arms from the project.

Parameters

$arms
array of arm numbers to delete.

Returns

integer
the number of arms deleted.

Throws

IU\PHPCap\PhpCapException
if an error occurs, including if the arms array is null or empty
public array
+/- exportEvents( string $format = 'php', array $arms = [] )

Exports information about the specified events.

Exports information about the specified events.

Example usage:

#export information about all events in CSV (Comma-Separated Values) format.
$eventInfo = $project->exportEvents('csv');

# export events in XML format for arms 1 and 2.
$eventInfo = $project->exportEvents('xml', [1, 2]);

Parameters

$format

the format for the export.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
$arms

array of integers or numeric strings that are the arm numbers for which events should be exported. If no arms are specified, then all events will be returned.

Returns

array

information about the specified events. Each element of the array is an associative array with the following keys: 'event_name', 'arm_num', 'day_offset', 'offset_min', 'offset_max', 'unique_event_name', 'custom_event_label'

public integer
+/- importEvents( mixed $events, string $format = 'php', boolean $override = false )

Imports the specified events into the project.

Imports the specified events into the project.

Parameters

$events

the events to import. This will be a PHP array of associative arrays if no format, or 'php' format is specified, and a string otherwise. The field names (keys) used in both cases are: event_name, arm_num

$format

the format for the export.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
$override
  • false - [default] don't delete existing arms; only add new arms or renames existing arms.
  • true - delete all existing arms before importing.

Returns

integer
the number of events imported.

Throws

IU\PHPCap\PhpCapException
if an error occurs.
public integer
+/- deleteEvents( array $events )

Deletes the specified events from the project.

Deletes the specified events from the project.

Parameters

$events
array of event names of events to delete.

Returns

integer
the number of events deleted.

Throws

IU\PHPCap\PhpCapException
if an error occurs, including if the events array is null or empty.
public mixed
+/- exportFieldNames( string $format = 'php', string $field = null )

Exports the fields names for a project.

Exports the fields names for a project.

Parameters

$format

the format for the export.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
$field

the name of the field for which to export field name information. If no field is specified, information for all fields is exported.

Returns

mixed

information on the field specified, or all fields if no field was specified. If 'php' or no format was specified, results will be returned as a PHP array of maps (associative arrays), where the keys for the maps:

  • original_field_name
  • choice_value
  • export_field_name
public string
+/- exportFile( string $recordId, string $field, string $event = null, integer $repeatInstance = null )

Exports the specified file.

Exports the specified file.

Parameters

$recordId
the record ID for the file to be exported.
$field
the name of the field containing the file to export.
$event
name of event for file export (for longitudinal studies).
$repeatInstance

Returns

string
the contents of the file that was exported.

Throws

IU\PHPCap\PhpCapException
if an error occurs.
public
+/- importFile( string $filename, string $recordId, string $field, string $event = null, integer $repeatInstance = null )

Imports the file into the field of the record with the specified event and/or repeat istance, if any.

Imports the file into the field of the record with the specified event and/or repeat istance, if any.

Example usage:

...
$file     = '../data/consent1001.txt';
$recordId = '1001';
$field    = 'patient_document';
$event    = 'enrollment_arm_1';
$project->importFile($file, $recordId, $field, $event);
...

Parameters

$filename
the name of the file to import.
$recordId
the record ID of the record to import the file into.
$field
the field of the record to import the file into.
$event

the event of the record to import the file into (only for longitudinal studies).

$repeatInstance

the repeat instance of the record to import the file into (only for studies that have repeating events and/or instruments).

Throws

IU\PHPCap\PhpCapException
public
+/- deleteFile( string $recordId, string $field, string $event = null, integer $repeatInstance = null )

Deletes the specified file.

Deletes the specified file.

Parameters

$recordId
the record ID of the file to delete.
$field
the field name of the file to delete.
$event

the event of the file to delete (only for longitudinal studies).

$repeatInstance

repeat instance of the file to delete (only for studies that have repeating events and/or instruments).

public mixed
+/- exportInstruments( $format = 'php' )

Exports information about the instruments (data entry forms) for the project.

Exports information about the instruments (data entry forms) for the project.

Example usage:

$instruments = $project->getInstruments();
foreach ($instruments as $instrumentName => $instrumentLabel) {
    print "{$instrumentName} : {$instrumentLabel}\n";
}

Parameters

$format

format instruments are exported in:

  • 'php' - [default] returns data as a PHP array
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded data
  • 'xml' - string of XML encoded data

Returns

mixed

For the 'php' format, and array map of instrument names to instrument labels is returned. For all other formats a string is returned.

public string
+/- exportPdfFileOfInstruments( string $file = null, string $recordId = null, string $event = null, string $form = null, boolean $allRecords = null )

Exports a PDF version of the requested instruments (forms).

Exports a PDF version of the requested instruments (forms).

Parameters

$file

the name of the file (possibly with a path specified also) to store the PDF instruments in.

$recordId

if record ID is specified, the forms retrieved will be filled with values for that record. Otherwise, they will be blank.

$event

(only for longitudinal projects) a unique event name that is used when a record ID has been specified to return only forms that are in that event (for the specified records).

$form

if this is specified, only this form will be returned.

$allRecords

if this is set to true, all forms for all records will be retrieved (the $recordId, $event, and $form arguments will be ignored).

Returns

string
PDF content of requested instruments (forms).

Throws

IU\PHPCap\PhpCapException
if an error occurs.
public arrray
+/- exportInstrumentEventMappings( string $format = 'php', array $arms = [] )

Gets the instrument to event mapping for the project.

Gets the instrument to event mapping for the project.

For example, the following code:

$map = $project->exportInstrumentEventMappings();
print_r($map[0]); # print first element of map

might generate the following output:

Array
(
    [arm_num] => 1
    [unique_event_name] => enrollment_arm_1
    [form] => demographics
)

Parameters

$format

the format in which to export the records:

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
$arms

array of integers or numeric strings that are the numbers of the arms for which instrument/event mapping infomation should be exported. If no arms are specified, then information for all arms will be exported.

Returns

arrray

an array of arrays that have the following keys:

  • 'arm_num'
  • 'unique_event_name'
  • 'form'
public integer
+/- importInstrumentEventMappings( mixed $mappings, string $format = 'php' )

Imports the specified instrument-event mappings into the project.

Imports the specified instrument-event mappings into the project.

Parameters

$mappings

the mappings to import. This will be a PHP array of associative arrays if no format, or 'php' format, was specified, and a string otherwise. In all cases, the field names that are used in the mappings are: arm_num, unique_event_name, form

$format

the format for the export.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data

Returns

integer
the number of mappings imported.

Throws

IU\PHPCap\PhpCapException
if an error occurs.
public array
+/- exportMetadata( string $format = 'php', array $fields = [], array $forms = [] )

Exports metadata about the project, i.e., information about the fields in the project.

Exports metadata about the project, i.e., information about the fields in the project.

Parameters

$format

the format for the export.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
$fields
array of field names for which metadata should be exported
$forms

array of form names. Metadata will be exported for all fields in the specified forms.

Returns

array

associative array (map) of metatdata for the project, which consists of information about each field. Some examples of the information provided are: 'field_name', 'form_name', 'field_type', 'field_label'. See REDCap API documentation for more information, or use the print_r function on the results of this method.

public integer
+/- importMetadata( mixed $metadata, string $format = 'php' )

Imports the specified metadata (field information) into the project.

Imports the specified metadata (field information) into the project.

Parameters

$metadata

the metadata to import. This will be a PHP associative array if no format, or 'php' format was specified, and a string otherwise.

$format

the format for the export.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data

Returns

integer
the number of fields imported.

Throws

IU\PHPCap\PhpCapException
if an error occurs.
public array
+/- exportProjectInfo( string $format = 'php' )

Exports information about the project, e.g., project ID, project title, creation time.

Exports information about the project, e.g., project ID, project title, creation time.

Parameters

$format

the format for the export.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data

Returns

array

associative array (map) of project information. See REDCap API documentation for a list of the fields, or use the print_r function on the results of this method.

public integer
+/- importProjectInfo( mixed $projectInfo, string $format = 'php' )

Imports the specified project information into the project. The valid fields that can be imported are:

Imports the specified project information into the project. The valid fields that can be imported are:

project_title, project_language, purpose, purpose_other, project_notes, custom_record_label, secondary_unique_field, is_longitudinal, surveys_enabled, scheduling_enabled, record_autonumbering_enabled, randomization_enabled, project_irb_number, project_grant_number, project_pi_firstname, project_pi_lastname, display_today_now_button

You do not need to specify all of these fields when doing an import, only the ones that you actually want to change. For example:

...
# Set the project to be longitudinal and enable surveys
$projectInfo = ['is_longitudinal' => 1, 'surveys_enabled' => 1];
$project->importProjectInfo($projectInfo);
...

Parameters

$projectInfo

the project information to import. This will be a PHP associative array if no format, or 'php' format was specified, and a string otherwise.

$format

the format for the export.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data

Returns

integer

the number of project info values specified that were valid, whether or not each valid value actually caused an update (i.e., was different from the existing value before the method call).

Throws

IU\PHPCap\PhpCapException
if an error occurs.
public string
+/- exportProjectXml( boolean $returnMetadataOnly = false, array $recordIds = null, array $fields = null, array $events = null, array $filterLogic = null, boolean $exportSurveyFields = false, boolean $exportDataAccessGroups = false, boolean $exportFiles = false )

Exports the specified information of project in XML format.

Exports the specified information of project in XML format.

Parameters

$returnMetadataOnly

if this is set to true, only the metadata for the project is returned. If it is not set to true, the metadata and data for the project is returned.

$recordIds
array of strings with record id's that are to be retrieved.
$fields
array of field names to export
$events
array of event names for which fields should be exported
$filterLogic

logic used to restrict the records retrieved, e.g., "[last_name] = 'Smith'".

$exportSurveyFields

specifies whether survey fields should be exported.

  • true - export the following survey fields:
    • survey identifier field ('redcap_survey_identifier')
    • survey timestamp fields (instrument+'_timestamp')
  • false - [default] survey fields are not exported.
$exportDataAccessGroups

specifies whether the data access group field ('redcap_data_access_group') should be exported.

  • true - export the data access group field if there is at least one data access group, and the user calling the method (as identified by the API token) is not in a data access group.
  • false - [default] don't export the data access group field.
$exportFiles

If this is set to true, files will be exported in the XML. If it is not set to true, files will not be exported.

Returns

string
the specified information for the project in XML format.
public string
+/- generateNextRecordName( )

This method returns the next potential record ID for a project, but it does NOT actually create a new record. The record ID returned will generally be the current maximum record ID number incremented by one (but see the REDCap documentation for the case where Data Access Groups are being used). This method is intended for use with projects that have record-autonumbering enabled.

This method returns the next potential record ID for a project, but it does NOT actually create a new record. The record ID returned will generally be the current maximum record ID number incremented by one (but see the REDCap documentation for the case where Data Access Groups are being used). This method is intended for use with projects that have record-autonumbering enabled.

Returns

string
the next record name.
public mixed
+/- exportRecords( string $format = 'php', string $type = 'flat', array $recordIds = null, array $fields = null, array $forms = null, array $events = null, array $filterLogic = null, string $rawOrLabel = 'raw', string $rawOrLabelHeaders = 'raw', boolean $exportCheckboxLabel = false, boolean $exportSurveyFields = false, boolean $exportDataAccessGroups = false )

Exports the specified records.

Exports the specified records.

Example usage:

$records = $project->exportRecords($format = 'csv', $type = 'flat');
$recordIds = [1001, 1002, 1003];
$records = $project->exportRecords('xml', 'eav', $recordIds);

Parameters

$format

the format in which to export the records:

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
  • 'odm' - string with CDISC ODM XML format, specifically ODM version 1.3.1
$type

the type of records exported:

  • 'flat' - [default] exports one record per row.
  • 'eav' - exports one data point per row:, so, for non-longitudinal studies, each record will have the following fields: record_id, field_name, value. For longitudinal studies, each record will have the fields: record_id, field_name, value, redcap_event_name.
$recordIds
array of strings with record id's that are to be retrieved.
$fields
array of field names to export
$forms
array of form names for which fields should be exported
$events
array of event names for which fields should be exported
$filterLogic

logic used to restrict the records retrieved, e.g., "[last_name] = 'Smith'".

$rawOrLabel

indicates what should be exported for options of multiple choice fields:

  • 'raw' - [default] export the raw coded values
  • 'label' - export the labels
$rawOrLabelHeaders

when exporting with 'csv' format 'flat' type, indicates what format should be used for the CSV headers:

  • 'raw' - [default] export the variable/field names
  • 'label' - export the field labels
$exportCheckboxLabel

specifies the format for checkbox fields for the case where $format = 'csv', $rawOrLabel = true, and $type = 'flat'. For other cases this parameter is effectively ignored.

  • true - checked checkboxes will have a value equal to the checkbox option's label (e.g., 'Choice 1'), and unchecked checkboxes will have a blank value.
  • false - [default] checked checkboxes will have a value of 'Checked', and unchecked checkboxes will have a value of 'Unchecked'.
$exportSurveyFields

specifies whether survey fields should be exported.

  • true - export the following survey fields:
    • survey identifier field ('redcap_survey_identifier')
    • survey timestamp fields (instrument+'_timestamp')
  • false - [default] survey fields are not exported.
$exportDataAccessGroups

specifies whether the data access group field ('redcap_data_access_group') should be exported.

  • true - export the data access group field if there is at least one data access group, and the user calling the method (as identified by the API token) is not in a data access group.
  • false - [default] don't export the data access group field.

Returns

mixed

If 'php' format is specified, an array of records will be returned where the format of the records depends on the 'type'parameter (see above). For other formats, a string is returned that contains the records in the specified format.

public mixed
+/- exportRecordsAp( array $arrayParameter = [] )

Export records using an array parameter, where the keys of the array passed to this method are the argument names, and the values are the argument values. The argument names to use correspond to the variable names in the exportRecords method.

Export records using an array parameter, where the keys of the array passed to this method are the argument names, and the values are the argument values. The argument names to use correspond to the variable names in the exportRecords method.

Example usage:

# return all records with last name "Smith" in CSV format
$records = $project->exportRecordsAp(['format' => 'csv', 'filterLogic' => "[last_name] = 'Smith'"]);

# export only records that have record ID 1001, 1002, or 1003
$result = $project->exportRecordsAp(['recordIds' => [1001, 1002, 1003]]);

# export only the fields on the 'lab_data' form and field 'study_id'
$records = $project->exportRecordsAp(['forms' => ['lab_data'], 'fields' => ['study_id']]);

Parameters

$arrayParameter
$argumentArray array of arguments.

Returns

mixed
the specified records.

See

IU\PHPCap\RedCapProject::exportRecords()
public mixed
+/- importRecords( mixed $records, string $format = 'php', string $type = 'flat', string $overwriteBehavior = 'normal', string $dateFormat = 'YMD', string $returnContent = 'count', boolean $forceAutoNumber = false )

Imports the specified records into the project.

Imports the specified records into the project.

Parameters

$records

If the 'php' (default) format is being used, an array of associated arrays (maps) where each key is a field name, and its value is the value to store in that field. If any other format is being used, then the records are represented by a string.

$format

One of the following formats can be specified

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
  • 'odm' - CDISC ODM XML format, specifically ODM version 1.3.1
$type
  • 'flat' - [default] each data element is a record
  • 'eav' - each data element is one value
$overwriteBehavior
  • normal - [default] blank/empty values will be ignored
  • overwrite - blank/empty values are valid and will overwrite data
$dateFormat

date format which can be one of the following:

  • 'YMD' - [default] Y-M-D format (e.g., 2016-12-31)
  • 'MDY' - M/D/Y format (e.g., 12/31/2016)
  • 'DMY' - D/M/Y format (e.g., 31/12/2016)
$returnContent

specifies what should be returned:

  • 'count' - [default] the number of records imported
  • 'ids' - an array of the record IDs imported is returned
  • 'auto_ids' - an array of comma-separated record ID pairs, with the new ID created and the corresponding ID that was sent, for the records that were imported. This can only be used if $forceAutoNumber is set to true.
$forceAutoNumber

enables automatic assignment of record IDs of imported records by REDCap. If this is set to true, and auto-numbering for records is enabled for the project, auto-numbering of imported records will be enabled.

Returns

mixed

if 'count' was specified for 'returnContent', then an integer will be returned that is the number of records imported. If 'ids' was specified, then an array of record IDs that were imported will be returned. If 'auto_ids' was specified, an array that maps newly created IDs to sent IDs will be returned.

public integer
+/- deleteRecords( array $recordIds, string $arm = null )

Deletes the specified records from the project.

Deletes the specified records from the project.

Parameters

$recordIds
array of record IDs to delete
$arm

if an arm is specified, only records that have one of the specified record IDs that are in that arm will be deleted.

Returns

integer

the number of records deleted. Note that as of REDCap version 7.0.15 (at least) the number of records deleted will not be correct for the case where an arm is specified and some of the record IDs specified are not in that arm.

Throws

IU\PHPCap\PhpCapException
public string
+/- exportRedcapVersion( )

Gets the REDCap version number of the REDCap instance being used by the project.

Gets the REDCap version number of the REDCap instance being used by the project.

Returns

string
the REDCap version number of the REDCap instance being used by the project.
public mixed
+/- exportReports( mixed $reportId, string $format = 'php', string $rawOrLabel = 'raw', string $rawOrLabelHeaders = 'raw', boolean $exportCheckboxLabel = false )

Exports the records produced by the specified report.

Exports the records produced by the specified report.

Parameters

$reportId
integer or numeric string ID of the report to use.
$format

output data format.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
$rawOrLabel

indicates what should be exported for options of multiple choice fields:

  • 'raw' - [default] export the raw coded values
  • 'label' - export the labels
$rawOrLabelHeaders

when exporting with 'csv' format 'flat' type, indicates what format should be used for the CSV headers:

  • 'raw' - [default] export the variable/field names
  • 'label' - export the field labels
$exportCheckboxLabel

specifies the format for checkbox fields for the case where $format = 'csv', $rawOrLabel = true, and $type = 'flat'. For other cases this parameter is effectively ignored.

  • true - checked checkboxes will have a value equal to the checkbox option's label (e.g., 'Choice 1'), and unchecked checkboxes will have a blank value.
  • false - [default] checked checkboxes will have a value of 'Checked', and unchecked checkboxes will have a value of 'Unchecked'.

Returns

mixed
the records generated by the specefied report in the specified format.
public string
+/- exportSurveyLink( string $recordId, string $form, string $event = null, integer $repeatInstance = null )

Exports the survey link for the specified inputs.

Exports the survey link for the specified inputs.

Parameters

$recordId
the record ID for the link.
$form
the form for the link.
$event
event for link (for longitudinal studies only).
$repeatInstance

for repeatable forms, the instance of the form to return a link for.

Returns

string
survey link.
public mixed
+/- exportSurveyParticipants( string $form, string $format = 'php', string $event = null )

Exports the list of survey participants for the specified form and, for longitudinal studies, event.

Exports the list of survey participants for the specified form and, for longitudinal studies, event.

Parameters

$form
the form for which the participants should be exported.
$format

output data format.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data
$event

the event name for which survey participants should be exported.

Returns

mixed

for the 'php' format, an array of arrays of participant information is returned, for all other formats, the data is returned in the specified format as a string.

public string
+/- exportSurveyQueueLink( string $recordId )

Exports the survey queue link for the specified record ID.

Exports the survey queue link for the specified record ID.

Parameters

$recordId
the record ID of the survey queue link that should be returned.

Returns

string
survey queue link.
public string
+/- exportSurveyReturnCode( string $recordId, string $form, string $event = null, integer $repeatInstance = null )

Exports the code for returning to a survey that was not completed.

Exports the code for returning to a survey that was not completed.

Parameters

$recordId
the record ID for the survey to return to.
$form
the form name of the survey to return to.
$event

the unique event name (for longitudinal studies) for the survey to return to.

$repeatInstance
the repeat instance (if any) for the survey to return to.

Returns

string
survey return code.
public mixed
+/- exportUsers( string $format = 'php' )

Exports the users of the project.

Exports the users of the project.

Parameters

$format

output data format.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data

Returns

mixed

a list of users. For the 'php' format an array of associative arrays is returned, where the keys are the field names and the values are the field values. For all other formats, a string is returned with the data in the specified format.

public integer
+/- importUsers( mixed $users, string $format = 'php' )

Imports the specified users into the project. This method can also be used to update user priveleges by importing a users that already exist in the project and specifying new privleges for that user in the user data that is imported.

Imports the specified users into the project. This method can also be used to update user priveleges by importing a users that already exist in the project and specifying new privleges for that user in the user data that is imported.

The available field names for user import are:

username, expiration, data_access_group, design,
user_rights, data_access_groups, data_export, reports, stats_and_charts,
manage_survey_participants, calendar, data_import_tool, data_comparison_tool,
logging, file_repository, data_quality_create, data_quality_execute,
api_export, api_import, mobile_app, mobile_app_download_data,
record_create, record_rename, record_delete,
lock_records_customization, lock_records, lock_records_all_forms,
forms

Privileges for fields above can be set as follows:

  • Data Export: 0=No Access, 2=De-Identified, 1=Full Data Set
  • Form Rights: 0=No Access, 2=Read Only, 1=View records/responses and edit records (survey responses are read-only), 3=Edit survey responses
  • Other field values: 0=No Access, 1=Access.

See the REDCap API documentation for more information, or print the results of PHPCap's exportUsers method to see what the data looks like for the current users.

Parameters

$users

for 'php' format, an array should be used that maps field names to field values. For all other formats a string should be used that has the data in the correct format.

$format

output data format.

  • 'php' - [default] array of maps of values
  • 'csv' - string of CSV (comma-separated values)
  • 'json' - string of JSON encoded values
  • 'xml' - string of XML encoded data

Returns

integer
the number of users added or updated.
public array
+/- getRecordIdBatches( integer $batchSize = null, array $filterLogic = null, $recordIdFieldName = null )

Gets an array of record ID batches.

Gets an array of record ID batches.

These can be used for batch processing of records exports to lessen memory requirements, for example:

...
# Get all the record IDs of the project in 10 batches
$recordIdBatches = $project->getRecordIdBatches(10);
foreach ($recordIdBatches as $recordIdBatch) {
    $records = $project->exportRecordsAp(['recordIds' => $recordIdBatch]);
    ...
}
...

Parameters

$batchSize

the batch size in number of record IDs. The last batch may have less record IDs. For example, if you had 500 record IDs and specified a batch size of 200, the first 2 batches would have 200 record IDs, and the last batch would have 100.

$filterLogic

logic used to restrict the records retrieved, e.g., "[last_name] = 'Smith'". This could be used for batch processing a subset of the records.

$recordIdFieldName

name of the record ID field. Specifying this is not necessary, but will speed things up, because it will eliminate the need for this method to call the REDCap API to retrieve the value.

Returns

array

an array or record ID arrays, where each record ID array is considered to be a batch. Each batch can be used as the value for the records IDs parameter for an export records method.

public string
+/- getRecordIdFieldName( )

Gets the record ID field name for the project.

Gets the record ID field name for the project.

Returns

string
the field name of the record ID field of the project.
public string
+/- getApiToken( )

Gets the API token for the project.

Gets the API token for the project.

Returns

string
the API token for the project.
public IU\PHPCap\RedCapApiConnectionInterface
+/- getConnection( )

Returns the underlying REDCap API connection being used by the project. This can be used to make calls to the REDCap API, possibly to access functionality not supported by PHPCap.

Returns the underlying REDCap API connection being used by the project. This can be used to make calls to the REDCap API, possibly to access functionality not supported by PHPCap.

Returns

IU\PHPCap\RedCapApiConnectionInterface

the underlying REDCap API connection being used by the project.

public
+/- setConnection( IU\PHPCap\RedCapApiConnectionInterface $connection )

Sets the connection used for calling the REDCap API.

Sets the connection used for calling the REDCap API.

Parameters

$connection

the connection to use for calls to the REDCap API.

public IU\PHPCap\ErrorHandlerInterface
+/- getErrorHandler( )

Gets the error handler.

Gets the error handler.

Returns

IU\PHPCap\ErrorHandlerInterface
the error handler being used.
public
+/- setErrorHandler( IU\PHPCap\ErrorHandlerInterface $errorHandler )

Sets the error handler used by the project.

Sets the error handler used by the project.

Parameters

$errorHandler
the error handler to use.
Constants summary
string JSON_RESULT_ERROR_PATTERN
+/- '/^[\s]*{"error":[\s]*"(.*)"}[\s]*$/'
PHPCap API documentation generated by ApiGen