Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixing the phpDoc blocks

  • Loading branch information...
commit 772362d17720e30066ba16559f897bd5735a4dfd 1 parent ab2d46d
Kiril Angov authored

Showing 1 changed file with 121 additions and 70 deletions. Show diff stats Hide diff stats

  1. 191  src/base_facebook.php
191  src/base_facebook.php
@@ -37,7 +37,7 @@ class FacebookApiException extends Exception
37 37
   /**
38 38
    * Make a new API Exception with the given result.
39 39
    *
40  
-   * @param Array $result the result from the API server
  40
+   * @param array $result The result from the API server
41 41
    */
42 42
   public function __construct($result) {
43 43
     $this->result = $result;
@@ -63,7 +63,7 @@ public function __construct($result) {
63 63
   /**
64 64
    * Return the associated result object returned by the API server.
65 65
    *
66  
-   * @returns Array the result from the API server
  66
+   * @return array The result from the API server
67 67
    */
68 68
   public function getResult() {
69 69
     return $this->result;
@@ -73,7 +73,7 @@ public function getResult() {
73 73
    * Returns the associated type for the error. This will default to
74 74
    * 'Exception' when a type is not available.
75 75
    *
76  
-   * @return String
  76
+   * @return string
77 77
    */
78 78
   public function getType() {
79 79
     if (isset($this->result['error'])) {
@@ -95,7 +95,7 @@ public function getType() {
95 95
   /**
96 96
    * To make debugging easier.
97 97
    *
98  
-   * @returns String the string representation of the error
  98
+   * @return string The string representation of the error
99 99
    */
100 100
   public function __toString() {
101 101
     $str = $this->getType() . ': ';
@@ -109,7 +109,7 @@ public function __toString() {
109 109
 /**
110 110
  * Provides access to the Facebook Platform.  This class provides
111 111
  * a majority of the functionality needed, but the class is abstract
112  
- * because it is designed to be subclassed.  The subclass must
  112
+ * because it is designed to be sub-classed.  The subclass must
113 113
  * implement the three abstract methods listed at the bottom of
114 114
  * the file.
115 115
  *
@@ -155,16 +155,22 @@ public function __toString() {
155 155
 
156 156
   /**
157 157
    * The Application ID.
  158
+   *
  159
+   * @var string
158 160
    */
159 161
   protected $appId;
160 162
 
161 163
   /**
162 164
    * The Application API Secret.
  165
+   *
  166
+   * @var string
163 167
    */
164 168
   protected $apiSecret;
165 169
 
166 170
   /**
167 171
    * The ID of the Facebook user, or 0 if the user is logged out.
  172
+   *
  173
+   * @var integer
168 174
    */
169 175
   protected $user;
170 176
 
@@ -174,19 +180,22 @@ public function __toString() {
174 180
   protected $signedRequest;
175 181
 
176 182
   /**
177  
-   * A CSRF state variable to assist in the defense against
178  
-   * CSRF attacks.
  183
+   * A CSRF state variable to assist in the defense against CSRF attacks.
179 184
    */
180 185
   protected $state;
181 186
 
182 187
   /**
183 188
    * The OAuth access token received in exchange for a valid authorization
184 189
    * code.  null means the access token has yet to be determined.
  190
+   *
  191
+   * @var string
185 192
    */
186 193
   protected $accessToken = null;
187 194
 
188 195
   /**
189 196
    * Indicates if the CURL based @ syntax for file uploads is enabled.
  197
+   *
  198
+   * @var boolean
190 199
    */
191 200
   protected $fileUploadSupport = false;
192 201
 
@@ -198,7 +207,7 @@ public function __toString() {
198 207
    * - secret: the application secret
199 208
    * - fileUpload: (optional) boolean indicating if file uploads are enabled
200 209
    *
201  
-   * @param Array $config the application configuration
  210
+   * @param array $config The application configuration
202 211
    */
203 212
   public function __construct($config) {
204 213
     $this->setAppId($config['appId']);
@@ -216,7 +225,8 @@ public function __construct($config) {
216 225
   /**
217 226
    * Set the Application ID.
218 227
    *
219  
-   * @param String $appId the Application ID
  228
+   * @param string $appId The Application ID
  229
+   * @return BaseFacebook
220 230
    */
221 231
   public function setAppId($appId) {
222 232
     $this->appId = $appId;
@@ -226,7 +236,7 @@ public function setAppId($appId) {
226 236
   /**
227 237
    * Get the Application ID.
228 238
    *
229  
-   * @return String the Application ID
  239
+   * @return string the Application ID
230 240
    */
231 241
   public function getAppId() {
232 242
     return $this->appId;
@@ -235,7 +245,8 @@ public function getAppId() {
235 245
   /**
236 246
    * Set the API Secret.
237 247
    *
238  
-   * @param String $appId the API Secret
  248
+   * @param string $apiSecret The API Secret
  249
+   * @return BaseFacebook
239 250
    */
240 251
   public function setApiSecret($apiSecret) {
241 252
     $this->apiSecret = $apiSecret;
@@ -245,7 +256,7 @@ public function setApiSecret($apiSecret) {
245 256
   /**
246 257
    * Get the API Secret.
247 258
    *
248  
-   * @return String the API Secret
  259
+   * @return string the API Secret
249 260
    */
250 261
   public function getApiSecret() {
251 262
     return $this->apiSecret;
@@ -254,7 +265,8 @@ public function getApiSecret() {
254 265
   /**
255 266
    * Set the file upload support status.
256 267
    *
257  
-   * @param Boolean the file upload support status.
  268
+   * @param boolean $fileUploadSupport The file upload support status.
  269
+   * @return BaseFacebook
258 270
    */
259 271
   public function setFileUploadSupport($fileUploadSupport) {
260 272
     $this->fileUploadSupport = $fileUploadSupport;
@@ -264,8 +276,7 @@ public function setFileUploadSupport($fileUploadSupport) {
264 276
   /**
265 277
    * Get the file upload support status.
266 278
    *
267  
-   * @return Boolean true if and only if the server supports
268  
-   * file upload.
  279
+   * @return boolean true if and only if the server supports file upload.
269 280
    */
270 281
   public function useFileUploadSupport() {
271 282
     return $this->fileUploadSupport;
@@ -276,7 +287,8 @@ public function useFileUploadSupport() {
276 287
    * your access token by other means and just want the SDK
277 288
    * to use it.
278 289
    *
279  
-   * @param String $access_token an access token.
  290
+   * @param string $access_token an access token.
  291
+   * @return BaseFacebook
280 292
    */
281 293
   public function setAccessToken($access_token) {
282 294
     $this->accessToken = $access_token;
@@ -290,7 +302,7 @@ public function setAccessToken($access_token) {
290 302
    * access token if a valid user access token wasn't available.  Subsequent
291 303
    * calls return whatever the first call returned.
292 304
    *
293  
-   * @return String the access token
  305
+   * @return string The access token
294 306
    */
295 307
   public function getAccessToken() {
296 308
     if ($this->accessToken !== null) {
@@ -316,8 +328,8 @@ public function getAccessToken() {
316 328
    * return a valid user access token, or false if one is determined
317 329
    * to not be available.
318 330
    *
319  
-   * @return String a valid user access token, or false if one
320  
-   *         could not be determined.
  331
+   * @return string A valid user access token, or false if one
  332
+   *                could not be determined.
321 333
    */
322 334
   protected function getUserAccessToken() {
323 335
     // first, consider a signed request if it's supplied.
@@ -362,7 +374,7 @@ protected function getUserAccessToken() {
362 374
   /**
363 375
    * Get the data from a signed_request token.
364 376
    *
365  
-   * @return String the base domain
  377
+   * @return string The base domain
366 378
    */
367 379
   public function getSignedRequest() {
368 380
     if (!$this->signedRequest) {
@@ -378,7 +390,7 @@ public function getSignedRequest() {
378 390
    * Get the UID of the connected user, or 0
379 391
    * if the Facebook user is not connected.
380 392
    *
381  
-   * @return String the UID if available.
  393
+   * @return string the UID if available.
382 394
    */
383 395
   public function getUser() {
384 396
     if ($this->user !== null) {
@@ -394,8 +406,8 @@ public function getUser() {
394 406
    * requests, then considering an authorization code, and then
395 407
    * falling back to any persistent store storing the user.
396 408
    *
397  
-   * @return Integer the id of the connected Facebook user, or 0
398  
-   * if no such user exists.
  409
+   * @return integer The id of the connected Facebook user,
  410
+   *                 or 0 if no such user exists.
399 411
    */
400 412
   protected function getUserFromAvailableData() {
401 413
     // if a signed request is supplied, then it solely determines
@@ -443,8 +455,8 @@ protected function getUserFromAvailableData() {
443 455
    * - redirect_uri: the url to go to after a successful login
444 456
    * - scope: comma separated list of requested extended perms
445 457
    *
446  
-   * @param Array $params provide custom parameters
447  
-   * @return String the URL for the login flow
  458
+   * @param array $params Provide custom parameters
  459
+   * @return string The URL for the login flow
448 460
    */
449 461
   public function getLoginUrl($params=array()) {
450 462
     $this->establishCSRFTokenState();
@@ -465,8 +477,8 @@ public function getLoginUrl($params=array()) {
465 477
    * The parameters:
466 478
    * - next: the url to go to after a successful logout
467 479
    *
468  
-   * @param Array $params provide custom parameters
469  
-   * @return String the URL for the logout flow
  480
+   * @param array $params Provide custom parameters
  481
+   * @return string The URL for the logout flow
470 482
    */
471 483
   public function getLogoutUrl($params=array()) {
472 484
     return $this->getUrl(
@@ -487,8 +499,8 @@ public function getLogoutUrl($params=array()) {
487 499
    * - no_session: the URL to go to if the user is not connected
488 500
    * - no_user: the URL to go to if the user is not signed into facebook
489 501
    *
490  
-   * @param Array $params provide custom parameters
491  
-   * @return String the URL for the logout flow
  502
+   * @param array $params Provide custom parameters
  503
+   * @return string The URL for the logout flow
492 504
    */
493 505
   public function getLoginStatusUrl($params=array()) {
494 506
     return $this->getUrl(
@@ -507,8 +519,7 @@ public function getLoginStatusUrl($params=array()) {
507 519
   /**
508 520
    * Make an API call.
509 521
    *
510  
-   * @param Array $params the API call parameters
511  
-   * @return the decoded response
  522
+   * @return mixed The decoded response
512 523
    */
513 524
   public function api(/* polymorphic */) {
514 525
     $args = func_get_args();
@@ -524,8 +535,8 @@ public function api(/* polymorphic */) {
524 535
    * and otherwise return false to signal no authorization code was
525 536
    * discoverable.
526 537
    *
527  
-   * @return mixed the authorization code, or false if the authorization
528  
-   * code could not be determined.
  538
+   * @return mixed The authorization code, or false if the authorization
  539
+   *               code could not be determined.
529 540
    */
530 541
   protected function getCode() {
531 542
     if (isset($_REQUEST['code'])) {
@@ -550,11 +561,11 @@ protected function getCode() {
550 561
    * Retrieves the UID with the understanding that
551 562
    * $this->accessToken has already been set and is
552 563
    * seemingly legitimate.  It relies on Facebook's Graph API
553  
-   * to retreive user information and then extract
  564
+   * to retrieve user information and then extract
554 565
    * the user ID.
555 566
    *
556  
-   * @return Integer returns the UID of the Facebook user, or
557  
-   * 0 if the Facebook user could not be determined.
  567
+   * @return integer Returns the UID of the Facebook user, or 0
  568
+   *                 if the Facebook user could not be determined.
558 569
    */
559 570
   protected function getUserFromAccessToken() {
560 571
     try {
@@ -569,8 +580,8 @@ protected function getUserFromAccessToken() {
569 580
    * Returns the access token that should be used for logged out
570 581
    * users when no authorization code is available.
571 582
    *
572  
-   * @return String the application access token, useful for
573  
-   * gathering public information about users and applications.
  583
+   * @return string The application access token, useful for gathering
  584
+   *                public information about users and applications.
574 585
    */
575 586
   protected function getApplicationAccessToken() {
576 587
     return $this->appId.'|'.$this->apiSecret;
@@ -589,16 +600,16 @@ protected function establishCSRFTokenState() {
589 600
   }
590 601
 
591 602
   /**
592  
-   * Retreives an access token for the given authorization code
  603
+   * Retrieves an access token for the given authorization code
593 604
    * (previously generated from www.facebook.com on behalf of
594 605
    * a specific user).  The authorization code is sent to graph.facebook.com
595 606
    * and a legitimate access token is generated provided the access token
596 607
    * and the user for which it was generated all match, and the user is
597 608
    * either logged in to Facebook or has granted an offline access permission.
598 609
    *
599  
-   * @param String $code an authorization code.
600  
-   * @return mixed an access token exchanged for the authorization code, or
601  
-   * false if an access token could not be generated.
  610
+   * @param string $code An authorization code.
  611
+   * @return mixed An access token exchanged for the authorization code, or
  612
+   *               false if an access token could not be generated.
602 613
    */
603 614
   protected function getAccessTokenFromCode($code) {
604 615
     if (empty($code)) {
@@ -637,8 +648,9 @@ protected function getAccessTokenFromCode($code) {
637 648
   /**
638 649
    * Invoke the old restserver.php endpoint.
639 650
    *
640  
-   * @param Array $params method call object
641  
-   * @return the decoded response object
  651
+   * @param array $params Method call object
  652
+   *
  653
+   * @return mixed The decoded response object
642 654
    * @throws FacebookApiException
643 655
    */
644 656
   protected function _restserver($params) {
@@ -662,10 +674,11 @@ protected function _restserver($params) {
662 674
   /**
663 675
    * Invoke the Graph API.
664 676
    *
665  
-   * @param String $path the path (required)
666  
-   * @param String $method the http method (default 'GET')
667  
-   * @param Array $params the query/post data
668  
-   * @return the decoded response object
  677
+   * @param string $path The path (required)
  678
+   * @param string $method The http method (default 'GET')
  679
+   * @param array $params The query/post data
  680
+   *
  681
+   * @return mixed The decoded response object
669 682
    * @throws FacebookApiException
670 683
    */
671 684
   protected function _graph($path, $method = 'GET', $params = array()) {
@@ -691,9 +704,10 @@ protected function _graph($path, $method = 'GET', $params = array()) {
691 704
   /**
692 705
    * Make a OAuth Request.
693 706
    *
694  
-   * @param String $path the path (required)
695  
-   * @param Array $params the query/post data
696  
-   * @return the decoded response object
  707
+   * @param string $url The path (required)
  708
+   * @param array $params The query/post data
  709
+   *
  710
+   * @return string The decoded response object
697 711
    * @throws FacebookApiException
698 712
    */
699 713
   protected function _oauthRequest($url, $params) {
@@ -712,14 +726,15 @@ protected function _oauthRequest($url, $params) {
712 726
   }
713 727
 
714 728
   /**
715  
-   * Makes an HTTP request. This method can be overriden by subclasses if
  729
+   * Makes an HTTP request. This method can be overridden by subclasses if
716 730
    * developers want to do fancier things or use something other than curl to
717 731
    * make the request.
718 732
    *
719  
-   * @param String $url the URL to make the request to
720  
-   * @param Array $params the parameters to use for the POST body
721  
-   * @param CurlHandler $ch optional initialized curl handle
722  
-   * @return String the response text
  733
+   * @param string $url The URL to make the request to
  734
+   * @param array $params The parameters to use for the POST body
  735
+   * @param CurlHandler $ch Initialized curl handle
  736
+   *
  737
+   * @return string The response text
723 738
    */
724 739
   protected function makeRequest($url, $params, $ch=null) {
725 740
     if (!$ch) {
@@ -773,8 +788,8 @@ protected function makeRequest($url, $params, $ch=null) {
773 788
   /**
774 789
    * Parses a signed_request and validates the signature.
775 790
    *
776  
-   * @param String A signed token
777  
-   * @return Array the payload inside it or null if the sig is wrong
  791
+   * @param string $signed_request A signed token
  792
+   * @return array The payload inside it or null if the sig is wrong
778 793
    */
779 794
   protected function parseSignedRequest($signed_request) {
780 795
     list($encoded_sig, $payload) = explode('.', $signed_request, 2);
@@ -803,7 +818,7 @@ protected function parseSignedRequest($signed_request) {
803 818
    * Build the URL for api given parameters.
804 819
    *
805 820
    * @param $method String the method name.
806  
-   * @return String the URL for the given parameters
  821
+   * @return string The URL for the given parameters
807 822
    */
808 823
   protected function getApiUrl($method) {
809 824
     static $READ_ONLY_CALLS =
@@ -879,10 +894,11 @@ protected function getApiUrl($method) {
879 894
   /**
880 895
    * Build the URL for given domain alias, path and parameters.
881 896
    *
882  
-   * @param $name String the name of the domain
883  
-   * @param $path String optional path (without a leading slash)
884  
-   * @param $params Array optional query parameters
885  
-   * @return String the URL for the given parameters
  897
+   * @param $name string The name of the domain
  898
+   * @param $path string Optional path (without a leading slash)
  899
+   * @param $params array Optional query parameters
  900
+   *
  901
+   * @return string The URL for the given parameters
886 902
    */
887 903
   protected function getUrl($name, $path='', $params=array()) {
888 904
     $url = self::$DOMAIN_MAP[$name];
@@ -903,7 +919,7 @@ protected function getUrl($name, $path='', $params=array()) {
903 919
    * Returns the Current URL, stripping it of known FB parameters that should
904 920
    * not persist.
905 921
    *
906  
-   * @return String the current URL
  922
+   * @return string The current URL
907 923
    */
908 924
   protected function getCurrentUrl() {
909 925
     $protocol = isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on'
@@ -945,8 +961,10 @@ protected function getCurrentUrl() {
945 961
    * a brute-force search of the very small list of Facebook-specific
946 962
    * params that should be stripped out.
947 963
    *
948  
-   * @param String a key or key/value pair within a URL's query (e.g.
949  
-   *        'foo=a', 'foo=', or 'foo'.
  964
+   * @param string $param A key or key/value pair within a URL's query (e.g.
  965
+   *                     'foo=a', 'foo=', or 'foo'.
  966
+   *
  967
+   * @return boolean
950 968
    */
951 969
   protected function shouldRetainParam($param) {
952 970
     foreach (self::$DROP_QUERY_PARAMS as $drop_query_param) {
@@ -963,8 +981,8 @@ protected function shouldRetainParam($param) {
963 981
    * because the access token is no longer valid.  If that is
964 982
    * the case, then the persistent store is cleared.
965 983
    *
966  
-   * @param $result a record storing the error message returned
967  
-   *        by a failed API call.
  984
+   * @param $result array A record storing the error message returned
  985
+   *                      by a failed API call.
968 986
    */
969 987
   protected function throwAPIException($result) {
970 988
     $e = new FacebookApiException($result);
@@ -989,7 +1007,7 @@ protected function throwAPIException($result) {
989 1007
   /**
990 1008
    * Prints to the error log if you aren't in command line mode.
991 1009
    *
992  
-   * @param String log message
  1010
+   * @param string $msg Log message
993 1011
    */
994 1012
   protected static function errorLog($msg) {
995 1013
     // disable error log if we are running in a CLI environment
@@ -1008,7 +1026,8 @@ protected static function errorLog($msg) {
1008 1026
    *   - instead of +
1009 1027
    *   _ instead of /
1010 1028
    *
1011  
-   * @param String base64UrlEncodeded string
  1029
+   * @param string $input base64UrlEncoded string
  1030
+   * @return string
1012 1031
    */
1013 1032
   protected static function base64UrlDecode($input) {
1014 1033
     return base64_decode(strtr($input, '-_', '+/'));
@@ -1023,8 +1042,40 @@ protected static function base64UrlDecode($input) {
1023 1042
    *
1024 1043
    * @see Facebook
1025 1044
    */
  1045
+
  1046
+  /**
  1047
+   * Stores the given ($key, $value) pair, so that future calls to
  1048
+   * getPersistentData($key) return $value. This call may be in another request.
  1049
+   *
  1050
+   * @param string $key
  1051
+   * @param array $value
  1052
+   *
  1053
+   * @return void
  1054
+   */
1026 1055
   abstract protected function setPersistentData($key, $value);
  1056
+
  1057
+  /**
  1058
+   * Get the data for $key, persisted by BaseFacebook::setPersistentData()
  1059
+   *
  1060
+   * @param string $key The key of the data to retrieve
  1061
+   * @param boolean $default The default value to return if $key is not found
  1062
+   *
  1063
+   * @return mixed
  1064
+   */
1027 1065
   abstract protected function getPersistentData($key, $default = false);
  1066
+
  1067
+  /**
  1068
+   * Clear the data with $key from the persistent storage
  1069
+   *
  1070
+   * @param string $key
  1071
+   * @return void
  1072
+   */
1028 1073
   abstract protected function clearPersistentData($key);
  1074
+
  1075
+  /**
  1076
+   * Clear all data from the persistent storage
  1077
+   *
  1078
+   * @return void
  1079
+   */
1029 1080
   abstract protected function clearAllPersistentData();
1030 1081
 }

0 notes on commit 772362d

Please sign in to comment.
Something went wrong with that request. Please try again.