This guide is for people interested in developing PHPCap (i.e., actually making changes to the PHPCap code). If you just want to use PHPCap to access REDCap from PHP, please see the user guides.
-
Install PHP 5.6 or greater with the following extensions:
- cURL
- DOM/XML
- mbstring
- OpenSSL
-
(Optional) Install XDebug. This is needed for PHPUnit code coverage analysis.
-
Install Git. The code for PHPCap is stored in GitHub, and Git is required to be able to download it for development. See: https://git-scm.com/downloads
-
Get PHPCap:
git clone https://github.com/iuredcap/phpcap -
Get Composer. Composer is needed to download the development dependencies for PHPCap. See: https://getcomposer.org/download/. You can either install the composer.phar file to the root directory of PHPCap (the .gitignore file is set to ignore this file), or install it globally at the system or account level.
-
Install PHPCap's development dependencies:
# If you installed the composer.phar file in PHPCap's root directory: php composer.phar install # If you installed composer globally: composer install # The dependencies should be installed into a "vendor" directory # (which will be ignored by Git). -
Install phpDocumentor, which is used for generating API documentation from PHPDoc comments in the code. It should be set up so that it can be run from the command line using:
phpdoc
To set up PHPCap for development on Ubuntu 20, execute the following commands:
sudo apt-get install php php-curl php-xml php-mbstring
sudo apt-get install php-xdebug
sudo apt-get install git
git clone https://github.com/iuredcap/phpcap
sudo apt-get install composer
cd phpcap
composer install
# Install phpDocumentor:
wget https://phpdoc.org/phpDocumentor.phar
chmod +x phpDocumentor.phar
sudo mv phpDocumentor.phar /usr/local/bin/phpdoc
PHPCap uses PHPUnit for running automated tests. PHPUnit should get installed as a dependency for your PHPCap project when you run the "composer install" command. PHPCap has the following types of automated tests:
- unit tests
- in directory tests/unit
- don't require a REDCap instance to run
- integration tests
- in directory tests/integration
- require a REDCap instance to run
- require setup and configuration to run
You can test your PHPUnit installation by running the following in the root PHPCap directory, which will run the unit tests for PHPCap:
./vendor/bin/phpunit --testsuite unit
If the above command succeeds, you should see an "OK" message with the number of tests and assertions that were run, and you should see no errors of failures.
To run all the automated tests (the unit tests as well as the integration tests), setup steps needs to be completed. Some of the integration tests are considered optional. If you don't do the setup steps for these optional tests, they will not be run. But if you don't do the setup steps for the non-optional integration tests, phpunit will fail when you try to run them.
Running all the automated tests, or all the integration tests, will fail unless the following setup steps are completed:
- Log in to your REDCap site.
- Create an empty project in REDCap.
- Create a project in REDCap for the "Basic Demography," "DAG," and "Longitudinal Data" test projects in directory tests/projects/, and import each of those test project files into the REDCap project created for it.
- In REDCap, request API tokens for the empty project and the projects imported in the step above. Make sure that user setting for each project allow API import and export.
- Once you have your tokens, copy the "config-example.ini" file to a file named "config.ini" and then set the URL in that file to be the URL for the API of your REDCap instance, and set the tokens to be the tokens requested in the previous step.
- In the Control Center in REDCap, download the "Date Calculated Fields" external module and then enable it.
- In REDCap, enable the "Date Calculated Fields" external module for the "Basic Demography" project.
- In REDCap, add a test user to the DAG project, assigning only default, basic permissions.
- Add the test user to the 'group1' DAG
- Using the "DAG Switcher" in REDCap, assign the test user access to DAGs 'group1' and 'group2'
- Create an API token for the test user with export/import/update permission for the DAG project
- Set the dags.test.user.api.token property in your test config.ini file to the value for the API token created in the previous step
To run the optional tests involving the CA certificate file, you will need to set up a valid CA certificate file, and set the ca.certificate.file property in the config.ini file to the path to that file. If this property isn't set, the tests for this will be skipped. See CA Certificate File Info for more information on how to do this.
To run all of the optional report tests, you will need to manually set up 2 reports.
You need to set up a report for the basic demography project. and then set the basic.demography.report.id property in your tests/config.ini file to the ID of the report. If the ID property is not set, then the tests that use the report will not be run. You need to set up an "Exercise" report as follows: * Include these fields in this order: record_id, bmi
You need to set up a report for the longitudinal data project and then set the longitudinal.data.report.id property in your tests/config.ini file to the ID of the report. If the ID property is not set, then the tests that use the report will not be run. You need to set up an "Exercise" report as follows: * Include these fields in this order: study_id, age, ethnicity, race, sex, gym, aerobics * Filter (only) by the following events: "Enrollment (Arm 1: Drug A)", "Enrollment (Arm 2: Drug B)"
To run the survey tests, use the following steps:
-
In REDCap, create a project for the "Repeatable Survey" project test file in the tests/projects directory, and import the project test file into that project.
-
In the "Project Setup" tab for the project created in the step above, click on the Enable button for "Use surveys for this project?"
-
In the "Project Setup" tab, click on the Designer button
-
In the "Online Designer" tab, click on the Enable button for instrument "Basic Information", and then:
- Select "Yes" for "Allow 'Save & Return Later' option for respondents?"
- Click on the Save Changes button
-
In the "Online Designer" tab, click on the Enable button for instrument "Weight", and then:
- Select "Yes" for "Allow 'Save & Return Later' option for respondents?"
- Check the box for "(Optional) Allow respondents to repeat the survey"
- Click on the Save Changes button
-
In the "Online Designer" tab, click on the "Survey Queue" button
-
In the "Set up Survey Queue" dialog:
- Click on the Activate button for "Weight"
- Check "When the following survey is completed:"
- In the selection below "When the following survey is completed:", select "Basic Information"
- Click on the Save button
-
Click on the "Manage Survey Participants" or "Survey Distribution Tools" link on the left (depending on your REDCap version)
-
Go to the "Participant List" tab
-
Click on the Add participants button
-
Add an e-mail that you have access to and click on the Add participants button
-
Click on the Enable button for participant identifiers, and confirm this action
-
Enter an identifier for the participant for the e-mail that you entered above and then click on the Save button
-
Click on the Compose Survey Invitations button
-
In the "Send a Survey Invitation to Participants" dialog:
- Make sure that "Immediately" is selected for when the e-mail should be sent
- Make sure that the participant you create above is selected
- Click on the Send Invitations button
-
Open the e-mail that should have been sent (you may need to wait a few minutes to receive it)
-
Click on the "Basic Information" link in the e-mail and fill out the survey, and then at least one "Weight" survey
-
In your project window in REDCap, click on the "API" link on the left and request (or create if you are an admin) an API token with at least API Export rights
-
Once you have your API token, use it and the e-mail and identifier entered earlier to set the following properties in the config.ini file in the tests directory:
repeatable.survey.api.token survey.participant.email survey.participant.identifier
To run the repeating forms tests, use the following steps:
-
In REDCap, create a project for the "Repeating Forms" project test file in the tests/projects directory, and import the project test file into that project.
-
In your project window in REDCap, click on the "API" link on the left and request (or create if you are an admin) an API token with at least API Export rights
-
Once you have your API token, use it to set the following property in the config.ini file in the tests directory:
repeating.forms.api.token
To set up the optional tests for project creation, you need to uncomment and set the super.token to a valid super token value. Note that the tests for project creation have no way to delete the projects that are created, so they will need to be deleted manually.
Set the timezone property in the config.ini file.
Note: the .gitignore file in PHPCap is set to ignore the tests/config.ini file, so that your personal API tokens will not be committed to Git.
To run the automated tests, execute the following command in the top-level directory of your downloaded version of PHPCap:
./vendor/bin/phpunit
The above command will run all the unit tests, and all the integration tests, except for the optional test that were not set up.
Note: PHPUnit uses the phpunit.xml configuration file in the root directory of PHPCap. See this file for a list of the test suites and files. This file will need to be modified to make changes to the test suites and/or files.
You can run just the integration tests using:
./vendor/bin/phpunit --testsuite integration
You can run a specific test class by specifying the path to its file, for example:
./vendor/bin/phpunit tests/unit/PhpCapExceptionTest.php
You can use the --filter option to run specific test methods, for example, the following would run only tests methods that contain 'Unreadable' in their name:
./vendor/bin/phpunit --filter 'Unreadable'
And you can combine class files and filters together. For example, the following command would only run methods with 'Curl' in their name that belong to the PhpCapExceptionTest class:
./vendor/bin/phpunit tests/unit/PhpCapExceptionTest.php --filter 'Curl'
If XDebug has been installed (and PHP is configured to use it), code coverage for the automated tests can be calculated by running the following commands in the root directory of PHPCap:
XDEBUG_MODE=coverage
export XDEBUG_MODE
./vendor/bin/phpunit --coverage-html tests/coverage
To see the results, open the file tests/coverage/index.html with a web browser. The .gitignore file is set to ignore the tests/coverage directory.
Note that when writing code, it is sometimes necessary to use the @codeCoverageIgnore annotation to reach 100% line coverage. The one problem that has come up is that the code coverage check will mark the closing bracket after a method that throws an exception as a line that was not covered. To avoid this, you can add the @codeCoverageIgnore annotation as shown in the example below.
if ($required) {
$message = 'No field was specified.';
$this->errorHandler->throwException($message, ErrorHandlerInterface::INVALID_ARGUMENT);
} // @codeCoverageIgnorePHPStan can be used to run a static analysis of the PHPCap code. Use the following command in the top-level directory:
./vendor/bin/phpstan
The configuration for PHPStan is in the following file in the top-level directory:
phpstan.neon
The directory tests/local/ has been set up so that all files in it, except for the README file, will be ignored by Git. This directory is intended as a place for developers to places tests for changes they are working on.
PHPCap follows the PSR-1 and PSR-2 coding standards. See:
To check for compliance for the PHPCap source code, execute the following command in the root directory of PHPCap:
./vendor/bin/phpcs src
To check compliance for the automated tests, use:
./vendor/bin/phpcs tests/unit tests/integration
To check for compliance for the PHPCap source code and the tests, use the default settings (defined in the top-level phpcs.xml file):
./vendor/bin/phpcs
You can check specific files for compliance by specifying the path to the file, for example:
./vendor/bin/phpcs src/RedCapProject.php
Note that if you are working on Windows and have the git property core.autocrlf set to true, you may see errors similar to the following:
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
1 | ERROR | [x] End of line character is invalid; expected "\n" but
| | found "\r\n"
----------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------
These errors are not important, because the issue should be fixed when you commit your code.
PHPCap also follows the PSR-4 (Autoloader) standard, see: http://www.php-fig.org/psr/psr-4/
Documentation consists of the following:
- Top-level README.md file
- Markdown documents that have been manually created in the docs-md/ directory
- HTML API documentation generated from the PHPDoc comments in the code, which are stored in the docs/api/ directory
- HTML versions of the Markdown documentation in the docs-md/ directory, which are generated programmatically, stored in the docs/ directory.
Since all documentation in the docs/ directory (except for the README.md file) is automatically generated, these files should not be edited manually.
To generate the API documentation (stored in ./docs/api), execute the following command in PHPCap's root directory:
phpdoc
Note: For this command to work, phpDocumentor needs to have been installed as command "phpdoc". The configuration file used by this command is phpdoc.xml in the root directory of PHPCap.
The API documentation is stored in Git to eliminate the need for non-developer users to install Composer and the developer dependencies.
Unfortunately, phpDocumentor creates 2 files with the same name that only differ in how they are capitalized. This causes issues when a zip file download of PHPCap is done on some systems. Running the HTML document generation script below will fix this issue, so it should always be run after the phpdoc command is run.
To generate an HTML version for the Markdown documents in the docs-md/ directory, execute the following command in PHPCap's root directory:
php generate-html-docs.php
Releases should be tagged in accordance with semantic versioning: http://semver.org/
PHPCap uses a few development dependencies.
To check for out of date dependencies, use:
composer outdated --direct
The "--direct" option above only checks dependencies directly used by PHPCap (i.e., specified in the composer.json file).