Skip to content

Commit 32c1150

Browse files
mullen2mullen2
committed
Improved the documentation and updated the generated documentation.
1 parent cda501c commit 32c1150

14 files changed

+181
-170
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ PHPCap is a PHP API (Application Programming Interface) for REDCap.
77

88
REDCap is a web application for building and managing online surveys and databases. For information about REDCap, please see http://www.project-redcap.org.
99

10+
1011
Requirements
1112
--------------------------
1213
To use PHPCap, you need to have:

‎apigen.neon

+2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ source: [src]
77
destination: docs/api
88
title: "PHPCap"
99

10+
accessLevels: [public]
11+
1012
#exclude: [Util]
1113

1214
# generate documentation for PHP internal classes that are extended

‎docs-md/CACertificateFile.md

+7-5
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@ no CA certificate file specified, for example:
1919

2020
require('PHPCap/autoloader.php');
2121

22-
use \IU\PHPCap\RedCapProject;
22+
use IU\PHPCap\RedCapProject;
2323

24-
$apiUrl = '';
25-
$apiToken = '1234567890A1234567890B1234567890';
24+
$apiUrl = 'https://redcap.someplace.edu/api/'; # Replace with your REDCap's API URL
25+
$apiToken = '1234567890A1234567890B1234567890'; # Replace with your API token
2626

2727
$sslVerify = true;
2828
$project = RedCapProject($apiUrl, $apiToken, $sslVerify);
@@ -43,8 +43,10 @@ Creating a CA Certificate File with Firefox
4343
To use the Firefox web browser to create a CA (Certificate Authority) certificate file for use with PHPCap, use the following steps:
4444

4545
1. Access your REDCap site with Firefox.
46-
2. Click on the padlock icon, and then the connection, and then "More Information".
47-
3. Click on the "Security" tab, if it is not already selected.
46+
2. Click on the padlock icon to the left of the URL displayed in Firefox, and then the connection, and then "More Information".
47+
![Page Information](resources/secure-connection.png)
48+
3. If the previous step succeeded, a "Page Info" window should open up. In this window,
49+
click on the "Security" tab, if it is not already selected.
4850
![Page Information](resources/page-info-security.png)
4951
4. Click on the "View Certificate" button
5052
5. Click on the "Detail" tab of the "Certificate Viewer" dialog.

‎docs-md/UserTutorial.md

+70-2
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ Enter the following into the __test.php__ file, modifying the API URL and token
7070

7171
require('PHPCap/autoloader.php');
7272

73-
use \IU\PHPCap\RedCapProject;
73+
use IU\PHPCap\RedCapProject;
7474

7575
$apiUrl = 'https://redcap.xxxxx.edu/api/'; # replace this URL with your institution's
7676
# REDCap API URL.
@@ -88,6 +88,36 @@ Run the test program using the following command in your project directory:
8888
php test.php
8989

9090
You should see output generated with information about your project.
91+
It should look similar to the following, although some of the values will
92+
probably be different:
93+
94+
```php
95+
Array
96+
(
97+
[project_id] => 9639
98+
[project_title] => PHPCap Basic Demography Test
99+
[creation_time] => 2017-03-31 13:40:53
100+
[production_time] =>
101+
[in_production] => 0
102+
[project_language] => English
103+
[purpose] => 1
104+
[purpose_other] => PHPCap testing
105+
[project_notes] =>
106+
[custom_record_label] =>
107+
[secondary_unique_field] =>
108+
[is_longitudinal] => 0
109+
[surveys_enabled] => 1
110+
[scheduling_enabled] => 0
111+
[record_autonumbering_enabled] => 0
112+
[randomization_enabled] => 0
113+
[ddp_enabled] => 0
114+
[project_irb_number] =>
115+
[project_grant_number] =>
116+
[project_pi_firstname] =>
117+
[project_pi_lastname] =>
118+
[display_today_now_button] => 1
119+
)
120+
```
91121

92122
### Making your test program secure.
93123

@@ -140,7 +170,7 @@ And your test program should look similar to the following:
140170

141171
require('PHPCap/autoloader.php');
142172

143-
use \IU\PHPCap\RedCapProject;
173+
use IU\PHPCap\RedCapProject;
144174

145175
$apiUrl = 'https://redcap.xxxxx.edu/api/'; # replace this URL with your institution's
146176
# REDCap API URL.
@@ -156,3 +186,41 @@ print_r($projectInfo);
156186
```
157187

158188
If everything is working correctly, the test program should (still) output information about your project.
189+
190+
### Checking for errors.
191+
192+
In general, when an error occurs in PHPCap, it throws a PhpCapException.
193+
These exceptions can be checked and handled using "try" and "catch". For example,
194+
to handle exceptions in the sample program, it could be modified as follows:
195+
```php
196+
<?php
197+
198+
require('PHPCap/autoloader.php');
199+
200+
use IU\PHPCap\RedCapProject;
201+
use IU\PHPCap\PhpCapException;
202+
203+
$apiUrl = 'https://redcap.xxxxx.edu/api/'; # replace this URL with your institution's
204+
# REDCap API URL.
205+
206+
$apiToken = '1234567890A1234567890B1234567890'; # replace with your actual API token
207+
208+
$sslVerify = true;
209+
$caCertificateFile = 'USERTrustRSACertificationAuthority.crt';
210+
try {
211+
$project = new RedCapProject($apiUrl, $apiToken, $sslVerify, $caCertificateFile);
212+
$projectInfo = $project->exportProjectInfo();
213+
print_r($projectInfo);
214+
} catch (PhpCapException $exception) {
215+
print "The following error occurred: {$exception->getMessage()}\n";
216+
print "Here is a stack trace:\n";
217+
print $exception->getTraceAsString()."\n";
218+
}
219+
220+
221+
```
222+
Note that in addition to the "try" and "catch" that were added, an additional use statement was
223+
added for the PhpCapException class:
224+
```php
225+
use IU\PHPCap\PhpCapException;
226+
```

‎docs-md/index.md

-8
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,7 @@
11
Overview
22
=========================================
33

4-
Download PHPCap: <a href="https://github.com/aarenson/PHPCap/archive/master.zip" download="PHPCap.zip">PHPCap.zip</a>
5-
64
PHPCap is a PHP API (Application Programming Interface) for REDCap.
75

86
REDCap is a web application for building and managing online surveys and databases. For information about REDCap, please see http://www.project-redcap.org.
97

10-
11-
12-
<ul id="index" style="display: none;">
13-
<li visibility="hidden">test 1</li>
14-
<li>test 2</li>
15-
</ul>

‎docs-md/resources/secure-connection.png

67 KB
Loading

‎docs/CACertificateFile.html

+7-5
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,10 @@ <h1>CA Certificate File</h1>
4040

4141
<span class="php-keyword1">require</span>(<span class="php-quote">'PHPCap/autoloader.php'</span>);
4242

43-
<span class="php-keyword1">use</span> \IU\PHPCap\RedCapProject;
43+
<span class="php-keyword1">use</span> IU\PHPCap\RedCapProject;
4444

45-
<span class="php-var">$apiUrl</span> = <span class="php-quote">''</span>;
46-
<span class="php-var">$apiToken</span> = <span class="php-quote">'1234567890A1234567890B1234567890'</span>;
45+
<span class="php-var">$apiUrl</span> = <span class="php-quote">'https://redcap.someplace.edu/api/'</span>; <span class="php-comment"># Replace with your REDCap's API URL</span>
46+
<span class="php-var">$apiToken</span> = <span class="php-quote">'1234567890A1234567890B1234567890'</span>; <span class="php-comment"># Replace with your API token</span>
4747

4848
<span class="php-var">$sslVerify</span> = <span class="php-keyword1">true</span>;
4949
<span class="php-var">$project</span> = RedCapProject(<span class="php-var">$apiUrl</span>, <span class="php-var">$apiToken</span>, <span class="php-var">$sslVerify</span>);
@@ -58,8 +58,10 @@ <h2>Creating a CA Certificate File with Firefox</h2>
5858
<p>To use the Firefox web browser to create a CA (Certificate Authority) certificate file for use with PHPCap, use the following steps:</p>
5959
<ol>
6060
<li>Access your REDCap site with Firefox.</li>
61-
<li>Click on the padlock icon, and then the connection, and then &quot;More Information&quot;.</li>
62-
<li>Click on the &quot;Security&quot; tab, if it is not already selected.<br />
61+
<li>Click on the padlock icon to the left of the URL displayed in Firefox, and then the connection, and then &quot;More Information&quot;.
62+
<img src="resources/secure-connection.png" alt="Page Information" /> </li>
63+
<li>If the previous step succeeded, a &quot;Page Info&quot; window should open up. In this window,
64+
click on the &quot;Security&quot; tab, if it is not already selected.<br />
6365
<img src="resources/page-info-security.png" alt="Page Information" /> </li>
6466
<li>Click on the &quot;View Certificate&quot; button</li>
6567
<li>Click on the &quot;Detail&quot; tab of the &quot;Certificate Viewer&quot; dialog.<br />

‎docs/UserTutorial.html

+62-4
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ <h3>Create your first test program.</h3>
7474

7575
<span class="php-keyword1">require</span>(<span class="php-quote">'PHPCap/autoloader.php'</span>);
7676

77-
<span class="php-keyword1">use</span> \IU\PHPCap\RedCapProject;
77+
<span class="php-keyword1">use</span> IU\PHPCap\RedCapProject;
7878

7979
<span class="php-var">$apiUrl</span> = <span class="php-quote">'https://redcap.xxxxx.edu/api/'</span>; <span class="php-comment"># replace this URL with your institution's</span>
8080
<span class="php-comment"># REDCap API URL.</span>
@@ -87,7 +87,34 @@ <h3>Create your first test program.</h3>
8787
<span class="php-keyword2">print_r</span>(<span class="php-var">$projectInfo</span>);</code></pre></div>
8888
<p>Run the test program using the following command in your project directory:</p>
8989
<div class="description"><pre><code>php test.php</code></pre></div>
90-
<p>You should see output generated with information about your project.</p>
90+
<p>You should see output generated with information about your project.
91+
It should look similar to the following, although some of the values will
92+
probably be different:</p>
93+
<div class="description"><pre><code class="language-php"><span class="php-keyword1">Array</span>
94+
(
95+
[project_id] =&gt; <span class="php-num">9639</span>
96+
[project_title] =&gt; PHPCap Basic Demography Test
97+
[creation_time] =&gt; <span class="php-num">2017</span>-<span class="php-num">03</span>-<span class="php-num">31</span> <span class="php-num">13</span>:<span class="php-num">40</span>:<span class="php-num">53</span>
98+
[production_time] =&gt;
99+
[in_production] =&gt; <span class="php-num">0</span>
100+
[project_language] =&gt; English
101+
[purpose] =&gt; <span class="php-num">1</span>
102+
[purpose_other] =&gt; PHPCap testing
103+
[project_notes] =&gt;
104+
[custom_record_label] =&gt;
105+
[secondary_unique_field] =&gt;
106+
[is_longitudinal] =&gt; <span class="php-num">0</span>
107+
[surveys_enabled] =&gt; <span class="php-num">1</span>
108+
[scheduling_enabled] =&gt; <span class="php-num">0</span>
109+
[record_autonumbering_enabled] =&gt; <span class="php-num">0</span>
110+
[randomization_enabled] =&gt; <span class="php-num">0</span>
111+
[ddp_enabled] =&gt; <span class="php-num">0</span>
112+
[project_irb_number] =&gt;
113+
[project_grant_number] =&gt;
114+
[project_pi_firstname] =&gt;
115+
[project_pi_lastname] =&gt;
116+
[display_today_now_button] =&gt; <span class="php-num">1</span>
117+
)</code></pre></div>
91118
<h3>Making your test program secure.</h3>
92119
<p>The program above is not secure, because it does not use SSL verification to verify that the
93120
REDCap site accessed is the one actually intended. To make the program more secure, it
@@ -123,7 +150,7 @@ <h3>Making your test program secure.</h3>
123150

124151
<span class="php-keyword1">require</span>(<span class="php-quote">'PHPCap/autoloader.php'</span>);
125152

126-
<span class="php-keyword1">use</span> \IU\PHPCap\RedCapProject;
153+
<span class="php-keyword1">use</span> IU\PHPCap\RedCapProject;
127154

128155
<span class="php-var">$apiUrl</span> = <span class="php-quote">'https://redcap.xxxxx.edu/api/'</span>; <span class="php-comment"># replace this URL with your institution's</span>
129156
<span class="php-comment"># REDCap API URL.</span>
@@ -136,7 +163,38 @@ <h3>Making your test program secure.</h3>
136163
<span class="php-var">$projectInfo</span> = <span class="php-var">$project</span>-&gt;exportProjectInfo();
137164

138165
<span class="php-keyword2">print_r</span>(<span class="php-var">$projectInfo</span>);</code></pre></div>
139-
<p>If everything is working correctly, the test program should (still) output information about your project.</p></div>
166+
<p>If everything is working correctly, the test program should (still) output information about your project.</p>
167+
<h3>Checking for errors.</h3>
168+
<p>In general, when an error occurs in PHPCap, it throws a PhpCapException.
169+
These exceptions can be checked and handled using &quot;try&quot; and &quot;catch&quot;. For example,
170+
to handle exceptions in the sample program, it could be modified as follows:</p>
171+
<div class="description"><pre><code class="language-php"><span class="xlang">&lt;?php</span>
172+
173+
<span class="php-keyword1">require</span>(<span class="php-quote">'PHPCap/autoloader.php'</span>);
174+
175+
<span class="php-keyword1">use</span> IU\PHPCap\RedCapProject;
176+
<span class="php-keyword1">use</span> IU\PHPCap\PhpCapException;
177+
178+
<span class="php-var">$apiUrl</span> = <span class="php-quote">'https://redcap.xxxxx.edu/api/'</span>; <span class="php-comment"># replace this URL with your institution's</span>
179+
<span class="php-comment"># REDCap API URL.</span>
180+
181+
<span class="php-var">$apiToken</span> = <span class="php-quote">'1234567890A1234567890B1234567890'</span>; <span class="php-comment"># replace with your actual API token</span>
182+
183+
<span class="php-var">$sslVerify</span> = <span class="php-keyword1">true</span>;
184+
<span class="php-var">$caCertificateFile</span> = <span class="php-quote">'USERTrustRSACertificationAuthority.crt'</span>;
185+
<span class="php-keyword1">try</span> {
186+
<span class="php-var">$project</span> = <span class="php-keyword1">new</span> RedCapProject(<span class="php-var">$apiUrl</span>, <span class="php-var">$apiToken</span>, <span class="php-var">$sslVerify</span>, <span class="php-var">$caCertificateFile</span>);
187+
<span class="php-var">$projectInfo</span> = <span class="php-var">$project</span>-&gt;exportProjectInfo();
188+
<span class="php-keyword2">print_r</span>(<span class="php-var">$projectInfo</span>);
189+
} <span class="php-keyword1">catch</span> (PhpCapException <span class="php-var">$exception</span>) {
190+
<span class="php-keyword1">print</span> <span class="php-quote">&quot;The following error occurred: </span><span class="php-var">{$exception-&gt;getMessage()}</span><span class="php-quote">\n&quot;</span>;
191+
<span class="php-keyword1">print</span> <span class="php-quote">&quot;Here is a stack trace:\n&quot;</span>;
192+
<span class="php-keyword1">print</span> <span class="php-var">$exception</span>-&gt;getTraceAsString().<span class="php-quote">&quot;\n&quot;</span>;
193+
}
194+
</code></pre></div>
195+
<p>Note that in addition to the &quot;try&quot; and &quot;catch&quot; that were added, an additional use statement was
196+
added for the PhpCapException class: </p>
197+
<div class="description"><pre><code class="language-php"><span class="php-keyword1">use</span> IU\PHPCap\PhpCapException;</code></pre></div></div>
140198
<div id="footer">
141199
PHPCap documentation
142200
</div>

‎docs/api/class-Exception.html

-103
Original file line numberDiff line numberDiff line change
@@ -471,109 +471,6 @@ <h4>Direct known subclasses</h4>
471471

472472

473473

474-
<table class="summary properties" id="properties">
475-
<caption>Properties summary</caption>
476-
<tr data-order="message" id="$message">
477-
<td class="attributes"><code>
478-
protected
479-
string
480-
</code></td>
481-
482-
<td class="name">
483-
<a href="http://php.net/manual/en/class.exception.php#exception.props.message" title="Go to PHP documentation"><var>$message</var></a>
484-
485-
<div class="description short">
486-
487-
</div>
488-
489-
<div class="description detailed hidden">
490-
491-
492-
</div>
493-
</td>
494-
<td class="value">
495-
<div>
496-
<a href="#$message" title="expand/collapse" class="anchor">+/-</a>
497-
<code><span class="php-quote">''</span></code>
498-
</div>
499-
</td>
500-
</tr>
501-
<tr data-order="code" id="$code">
502-
<td class="attributes"><code>
503-
protected
504-
integer
505-
</code></td>
506-
507-
<td class="name">
508-
<a href="http://php.net/manual/en/class.exception.php#exception.props.code" title="Go to PHP documentation"><var>$code</var></a>
509-
510-
<div class="description short">
511-
512-
</div>
513-
514-
<div class="description detailed hidden">
515-
516-
517-
</div>
518-
</td>
519-
<td class="value">
520-
<div>
521-
<a href="#$code" title="expand/collapse" class="anchor">+/-</a>
522-
<code><span class="php-num">0</span></code>
523-
</div>
524-
</td>
525-
</tr>
526-
<tr data-order="file" id="$file">
527-
<td class="attributes"><code>
528-
protected
529-
530-
</code></td>
531-
532-
<td class="name">
533-
<a href="http://php.net/manual/en/class.exception.php#exception.props.file" title="Go to PHP documentation"><var>$file</var></a>
534-
535-
<div class="description short">
536-
537-
</div>
538-
539-
<div class="description detailed hidden">
540-
541-
542-
</div>
543-
</td>
544-
<td class="value">
545-
<div>
546-
<a href="#$file" title="expand/collapse" class="anchor">+/-</a>
547-
<code></code>
548-
</div>
549-
</td>
550-
</tr>
551-
<tr data-order="line" id="$line">
552-
<td class="attributes"><code>
553-
protected
554-
555-
</code></td>
556-
557-
<td class="name">
558-
<a href="http://php.net/manual/en/class.exception.php#exception.props.line" title="Go to PHP documentation"><var>$line</var></a>
559-
560-
<div class="description short">
561-
562-
</div>
563-
564-
<div class="description detailed hidden">
565-
566-
567-
</div>
568-
</td>
569-
<td class="value">
570-
<div>
571-
<a href="#$line" title="expand/collapse" class="anchor">+/-</a>
572-
<code></code>
573-
</div>
574-
</td>
575-
</tr>
576-
</table>
577474

578475

579476

0 commit comments

Comments
 (0)