Merge pull request facebookarchive#120 from irazasyed/master

Updated/Added/Fixed PHPDoc Blocks.

Author: gfosco

src/base_facebook.php

@@ -31,6 +31,8 @@ class FacebookApiException extends Exception
 {
   /**
    * The result from the API server that represents the exception information.
+   *
+   * @var mixed
    */
   protected $result;
 
@@ -132,6 +134,8 @@ abstract class BaseFacebook
 
   /**
    * Default options for curl.
+   *
+   * @var array
    */
   public static $CURL_OPTS = array(
     CURLOPT_CONNECTTIMEOUT => 10,
@@ -143,6 +147,8 @@ abstract class BaseFacebook
   /**
    * List of query parameters that get automatically dropped when rebuilding
    * the current URL.
+   *
+   * @var array
    */
   protected static $DROP_QUERY_PARAMS = array(
     'code',
@@ -152,6 +158,8 @@ abstract class BaseFacebook
 
   /**
    * Maps aliases to Facebook domains.
+   *
+   * @var array
    */
   public static $DOMAIN_MAP = array(
     'api'         => 'https://api.facebook.com/',
@@ -185,11 +193,15 @@ abstract class BaseFacebook
 
   /**
    * The data from the signed_request token.
+   *
+   * @var string
    */
   protected $signedRequest;
 
   /**
    * A CSRF state variable to assist in the defense against CSRF attacks.
+   *
+   * @var string
    */
   protected $state;
 
@@ -258,6 +270,7 @@ public function __construct($config) {
    * Set the Application ID.
    *
    * @param string $appId The Application ID
+   *
    * @return BaseFacebook
    */
   public function setAppId($appId) {
@@ -278,8 +291,10 @@ public function getAppId() {
    * Set the App Secret.
    *
    * @param string $apiSecret The App Secret
+   *
    * @return BaseFacebook
    * @deprecated Use setAppSecret instead.
+   * @see setAppSecret()
    */
   public function setApiSecret($apiSecret) {
     $this->setAppSecret($apiSecret);
@@ -290,6 +305,7 @@ public function setApiSecret($apiSecret) {
    * Set the App Secret.
    *
    * @param string $appSecret The App Secret
+   *
    * @return BaseFacebook
    */
   public function setAppSecret($appSecret) {
@@ -301,7 +317,9 @@ public function setAppSecret($appSecret) {
    * Get the App Secret.
    *
    * @return string the App Secret
+   *
    * @deprecated Use getAppSecret instead.
+   * @see getAppSecret()
    */
   public function getApiSecret() {
     return $this->getAppSecret();
@@ -320,6 +338,7 @@ public function getAppSecret() {
    * Set the file upload support status.
    *
    * @param boolean $fileUploadSupport The file upload support status.
+   *
    * @return BaseFacebook
    */
   public function setFileUploadSupport($fileUploadSupport) {
@@ -340,7 +359,9 @@ public function getFileUploadSupport() {
    * Get the file upload support status.
    *
    * @return boolean true if and only if the server supports file upload.
+   *
    * @deprecated Use getFileUploadSupport instead.
+   * @see getFileUploadSupport()
    */
   public function useFileUploadSupport() {
     return $this->getFileUploadSupport();
@@ -352,6 +373,7 @@ public function useFileUploadSupport() {
    * to use it.
    *
    * @param string $access_token an access token.
+   *
    * @return BaseFacebook
    */
   public function setAccessToken($access_token) {
@@ -680,7 +702,7 @@ protected function getSignedRequestCookieName() {
   }
 
   /**
-   * Constructs and returns the name of the coookie that potentially contain
+   * Constructs and returns the name of the cookie that potentially contain
    * metadata. The cookie is not set by the BaseFacebook class, but it may be
    * set by the JavaScript SDK.
    *
@@ -768,6 +790,8 @@ protected function establishCSRFTokenState() {
    * either logged in to Facebook or has granted an offline access permission.
    *
    * @param string $code An authorization code.
+   * @param string $redirect_uri Optional redirect URI. Default null
+   *
    * @return mixed An access token exchanged for the authorization code, or
    *               false if an access token could not be generated.
    */
@@ -1022,6 +1046,7 @@ protected function makeRequest($url, $params, $ch=null) {
    * Parses a signed_request and validates the signature.
    *
    * @param string $signed_request A signed token
+   *
    * @return array The payload inside it or null if the sig is wrong
    */
   protected function parseSignedRequest($signed_request) {
@@ -1062,7 +1087,8 @@ protected function parseSignedRequest($signed_request) {
   /**
    * Makes a signed_request blob using the given data.
    *
-   * @param array The data array.
+   * @param array $data The data array.
+   *
    * @return string The signed request.
    */
   protected function makeSignedRequest($data) {
@@ -1082,7 +1108,8 @@ protected function makeSignedRequest($data) {
   /**
    * Build the URL for api given parameters.
    *
-   * @param $method String the method name.
+   * @param string $method The method name.
+   *
    * @return string The URL for the given parameters
    */
   protected function getApiUrl($method) {
@@ -1159,9 +1186,9 @@ protected function getApiUrl($method) {
   /**
    * Build the URL for given domain alias, path and parameters.
    *
-   * @param $name string The name of the domain
-   * @param $path string Optional path (without a leading slash)
-   * @param $params array Optional query parameters
+   * @param string $name   The name of the domain
+   * @param string $path   Optional path (without a leading slash)
+   * @param array  $params Optional query parameters
    *
    * @return string The URL for the given parameters
    */
@@ -1180,6 +1207,11 @@ protected function getUrl($name, $path='', $params=array()) {
     return $url;
   }
 
+  /**
+   * Returns the HTTP Host
+   *
+   * @return string The HTTP Host
+   */
   protected function getHttpHost() {
     if ($this->trustForwarded && isset($_SERVER['HTTP_X_FORWARDED_HOST'])) {
       $forwardProxies = explode(',', $_SERVER['HTTP_X_FORWARDED_HOST']);
@@ -1190,6 +1222,11 @@ protected function getHttpHost() {
     return $_SERVER['HTTP_HOST'];
   }
 
+  /**
+   * Returns the HTTP Protocol
+   *
+   * @return string The HTTP Protocol
+   */
   protected function getHttpProtocol() {
     if ($this->trustForwarded && isset($_SERVER['HTTP_X_FORWARDED_PROTO'])) {
       if ($_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
@@ -1211,7 +1248,9 @@ protected function getHttpProtocol() {
   }
 
   /**
-   * Get the base domain used for the cookie.
+   * Returns the base domain used for the cookie.
+   *
+   * @return string The base domain
    */
   protected function getBaseDomain() {
     // The base domain is stored in the metadata cookie if not we fallback
@@ -1270,7 +1309,7 @@ protected function getCurrentUrl() {
    * params that should be stripped out.
    *
    * @param string $param A key or key/value pair within a URL's query (e.g.
-   *                     'foo=a', 'foo=', or 'foo'.
+   *                      'foo=a', 'foo=', or 'foo'.
    *
    * @return boolean
    */
@@ -1290,7 +1329,7 @@ protected function shouldRetainParam($param) {
    * because the access token is no longer valid.  If that is
    * the case, then we destroy the session.
    *
-   * @param $result array A record storing the error message returned
+   * @param array $result A record storing the error message returned
    *                      by a failed API call.
    */
   protected function throwAPIException($result) {
@@ -1339,8 +1378,9 @@ protected static function errorLog($msg) {
    *   _ instead of /
    *   No padded =
    *
-   * @param string $input base64UrlEncoded string
-   * @return string
+   * @param string $input base64UrlEncoded input
+   *
+   * @return string The decoded string
    */
   protected static function base64UrlDecode($input) {
     return base64_decode(strtr($input, '-_', '+/'));
@@ -1352,8 +1392,8 @@ protected static function base64UrlDecode($input) {
    *   - instead of +
    *   _ instead of /
    *
-   * @param string $input string
-   * @return string base64Url encoded string
+   * @param string $input The input to encode
+   * @return string The base64Url encoded input, as a string.
    */
   protected static function base64UrlEncode($input) {
     $str = strtr(base64_encode($input), '+/', '-_');
@@ -1393,7 +1433,7 @@ public function destroySession() {
   /**
    * Parses the metadata cookie that our Javascript API set
    *
-   * @return  an array mapping key to value
+   * @return array an array mapping key to value
    */
   protected function getMetadataCookie() {
     $cookie_name = $this->getMetadataCookieName();
@@ -1421,13 +1461,29 @@ protected function getMetadataCookie() {
     return $metadata;
   }
 
+  /**
+   * Finds whether the given domain is allowed or not
+   *
+   * @param string $big   The value to be checked against $small
+   * @param string $small The input string
+   *
+   * @return boolean Returns TRUE if $big matches $small
+   */
   protected static function isAllowedDomain($big, $small) {
     if ($big === $small) {
       return true;
     }
     return self::endsWith($big, '.'.$small);
   }
 
+  /**
+   * Checks if $big string ends with $small string
+   *
+   * @param string $big   The value to be checked against $small
+   * @param string $small The input string
+   *
+   * @return boolean TRUE if $big ends with $small
+   */
   protected static function endsWith($big, $small) {
     $len = strlen($small);
     if ($len === 0) {
@@ -1471,6 +1527,7 @@ abstract protected function getPersistentData($key, $default = false);
    * Clear the data with $key from the persistent storage
    *
    * @param string $key
+   *
    * @return void
    */
   abstract protected function clearPersistentData($key);