Code sniff cleanup

salesforce.install

@@ -5,6 +5,7 @@
  * Salesforce install file.
  */
 
+use Drupal\Core\Url;
 use Drupal\Component\Serialization\Json;
 use Drupal\salesforce\Entity\SalesforceAuthConfig;
 use Drupal\Core\Utility\UpdateException;
@@ -67,36 +68,36 @@ function salesforce_get_auth_provider_requirements() {
   $authMan = \Drupal::service('plugin.manager.salesforce.auth_providers');
   if (!$authMan->hasProviders()) {
     $requirements += [
-      'description' => t('No auth providers have been created. Please <a href="@href">create an auth provider</a> to connect to Salesforce.', ['@href' => \Drupal\Core\Url::fromRoute('entity.salesforce_auth.add_form')]),
-      'severity' => REQUIREMENT_WARNING
+      'description' => t('No auth providers have been created. Please <a href="@href">create an auth provider</a> to connect to Salesforce.', ['@href' => Url::fromRoute('entity.salesforce_auth.add_form')]),
+      'severity' => REQUIREMENT_WARNING,
     ];
   }
   elseif (!$authMan->getConfig()) {
     $requirements += [
-      'description' => t('Default auth provider has not been set. Please <a href="@href">choose an auth provider</a> to connect to Salesforce.', ['@href' => \Drupal\Core\Url::fromRoute('salesforce.auth_config')->toString()]),
-      'severity' => REQUIREMENT_WARNING
+      'description' => t('Default auth provider has not been set. Please <a href="@href">choose an auth provider</a> to connect to Salesforce.', ['@href' => Url::fromRoute('salesforce.auth_config')->toString()]),
+      'severity' => REQUIREMENT_WARNING,
     ];
   }
   else {
-    $failMessage = t('Salesforce authentication failed. Please <a href="@href">check your auth provider settings</a> to connect to Salesforce.', ['@href' => \Drupal\Core\Url::fromRoute('entity.salesforce_auth.edit_form', ['salesforce_auth' => $authMan->getConfig()])]);
+    $failMessage = t('Salesforce authentication failed. Please <a href="@href">check your auth provider settings</a> to connect to Salesforce.', ['@href' => Url::fromRoute('entity.salesforce_auth.edit_form', ['salesforce_auth' => $authMan->getConfig()])]);
     try {
       if (!$authMan->getToken()) {
         $requirements += [
           'description' => $failMessage,
-          'severity' => REQUIREMENT_WARNING
+          'severity' => REQUIREMENT_WARNING,
         ];
       }
     }
     catch (Exception $e) {
       $requirements += [
         'description' => $failMessage,
-        'severity' => REQUIREMENT_WARNING
+        'severity' => REQUIREMENT_WARNING,
       ];
     }
   }
   if (empty($requirements['severity'])) {
     $requirements += [
-      'severity' => REQUIREMENT_OK
+      'severity' => REQUIREMENT_OK,
     ];
   }
   return $requirements;
@@ -276,7 +277,7 @@ function salesforce_update_8005() {
   }
 
   $message = '';
-  // If auth plugin providers have not been created already, convert existing
+  // If auth plugin providers have not been created already, convert existing.
   if (SalesforceAuthConfig::load('oauth_default')) {
     // If an auth config with our name already exists, we are done here.
     $message = 'Existing "oauth_default" provider config detected. Refused to set legacy credentials.';

src/Client/HttpClientWrapper.php

@@ -2,14 +2,29 @@
 
 namespace Drupal\salesforce\Client;
 
+use GuzzleHttp\ClientInterface as GuzzleClientInterface;
 use OAuth\Common\Http\Client\ClientInterface;
 use OAuth\Common\Http\Uri\UriInterface;
 
+/**
+ * Wraps Guzzle HTTP client for an OAuth ClientInterface.
+ */
 class HttpClientWrapper implements ClientInterface {
 
+  /**
+   * Guzzle HTTP Client service.
+   *
+   * @var \GuzzleHttp\ClientInterface
+   */
   protected $httpClient;
 
-  public function __construct(\GuzzleHttp\ClientInterface $httpClient) {
+  /**
+   * HttpClientWrapper constructor.
+   *
+   * @param \GuzzleHttp\ClientInterface $httpClient
+   *   Guzzle HTTP client service, from core http_client.
+   */
+  public function __construct(GuzzleClientInterface $httpClient) {
     $this->httpClient = $httpClient;
   }
 
@@ -19,11 +34,11 @@ class HttpClientWrapper implements ClientInterface {
   public function retrieveResponse(
     UriInterface $endpoint,
     $requestBody,
-    array $extraHeaders = array(),
+    array $extraHeaders = [],
     $method = 'POST'
   ) {
     $response = $this->httpClient->request($method, $endpoint->getAbsoluteUri(), ['headers' => $extraHeaders, 'form_params' => $requestBody]);
     return $response->getBody()->getContents();
   }
 
-}
\ No newline at end of file
+}

src/Consumer/OAuthCredentials.php

@@ -2,6 +2,9 @@
 
 namespace Drupal\salesforce\Consumer;
 
+/**
+ * OAuth user agent credentials.
+ */
 class OAuthCredentials extends SalesforceCredentials {
 
   /**
@@ -11,4 +14,5 @@ class OAuthCredentials extends SalesforceCredentials {
     parent::__construct($consumerKey, $loginUrl);
     $this->consumerSecret = $consumerSecret;
   }
-}
\ No newline at end of file
+
+}

src/Consumer/SalesforceCredentials.php

@@ -5,9 +5,23 @@ namespace Drupal\salesforce\Consumer;
 use Drupal\Core\Url;
 use OAuth\Common\Consumer\Credentials;
 
+/**
+ * Salesforce credentials extension, for drupalisms.
+ */
 abstract class SalesforceCredentials extends Credentials implements SalesforceCredentialsInterface {
 
+  /**
+   * Login URL e.g. https://test.salesforce.com or https://login.salesforce.com.
+   *
+   * @var string
+   */
   protected $loginUrl;
+
+  /**
+   * Consumer key for the Salesforce connected OAuth app.
+   *
+   * @var string
+   */
   protected $consumerKey;
 
   /**
@@ -43,4 +57,4 @@ abstract class SalesforceCredentials extends Credentials implements SalesforceCr
     ])->toString();
   }
 
-}
\ No newline at end of file
+}

src/Consumer/SalesforceCredentialsInterface.php

@@ -2,10 +2,25 @@
 
 namespace Drupal\salesforce\Consumer;
 
+/**
+ * Salesforce credentials interface.
+ */
 interface SalesforceCredentialsInterface {
 
+  /**
+   * Get the consumer key for these credentials.
+   *
+   * @return string
+   *   The consumer key.
+   */
   public function getConsumerKey();
 
+  /**
+   * Get the login URL for these credentials.
+   *
+   * @return string
+   *   The login url, e.g. https://login.salesforce.com.
+   */
   public function getLoginUrl();
 
-}
\ No newline at end of file
+}

src/Entity/SalesforceAuthConfig.php

@@ -4,9 +4,6 @@ namespace Drupal\salesforce\Entity;
 
 use Drupal\Core\Config\Entity\ConfigEntityBase;
 use Drupal\Core\Entity\EntityInterface;
-use Drupal\Core\Entity\EntityStorageInterface;
-use Drupal\Core\Entity\EntityWithPluginCollectionInterface;
-use Drupal\Core\Plugin\DefaultSingleLazyPluginCollection;
 
 /**
  * Defines a Salesforce Auth entity.
@@ -53,10 +50,17 @@ class SalesforceAuthConfig extends ConfigEntityBase implements EntityInterface {
   protected $label;
 
   /**
-   * @var \Drupal\salesforce\SalesforceAuthProviderPluginInterface
+   * The auth provider for this auth config.
+   *
+   * @var string
    */
   protected $provider;
 
+  /**
+   * Provider plugin configuration settings.
+   *
+   * @var array
+   */
   protected $provider_settings = [];
 
   /**
@@ -83,7 +87,8 @@ class SalesforceAuthConfig extends ConfigEntityBase implements EntityInterface {
   /**
    * Plugin getter.
    *
-   * @return \Drupal\salesforce\SalesforceAuthProviderInterface
+   * @return \Drupal\salesforce\SalesforceAuthProviderInterface|null
+   *   The auth provider plugin, or null.
    */
   public function getPlugin() {
     $settings = $this->provider_settings ?: [];
@@ -91,6 +96,12 @@ class SalesforceAuthConfig extends ConfigEntityBase implements EntityInterface {
     return $this->provider ? $this->authManager()->createInstance($this->provider, $settings) : NULL;
   }
 
+  /**
+   * Plugin id getter.
+   *
+   * @return string|null
+   *   The auth provider plugin id, or null.
+   */
   public function getPluginId() {
     return $this->provider ?: NULL;
   }
@@ -106,6 +117,7 @@ class SalesforceAuthConfig extends ConfigEntityBase implements EntityInterface {
    * Auth manager wrapper.
    *
    * @return \Drupal\salesforce\SalesforceAuthProviderPluginManager|mixed
+   *   The auth provider plugin manager.
    */
   public function authManager() {
     if (!$this->manager) {
@@ -117,9 +129,6 @@ class SalesforceAuthConfig extends ConfigEntityBase implements EntityInterface {
   /**
    * Returns a list of plugins, for use in forms.
    *
-   * @param string $type
-   *   The plugin type to use.
-   *
    * @return array
    *   The list of plugins, indexed by ID.
    */
@@ -128,8 +137,7 @@ class SalesforceAuthConfig extends ConfigEntityBase implements EntityInterface {
     foreach ($this->authManager()->getDefinitions() as $id => $definition) {
       $options[$id] = ($definition['label']);
     }
-
     return $options;
   }
 
-}
\ No newline at end of file
+}

src/Plugin/SalesforceAuthProvider/SalesforceOAuthPlugin.php

@@ -4,22 +4,17 @@ namespace Drupal\salesforce\Plugin\SalesforceAuthProvider;
 
 use Drupal\Core\Form\FormStateInterface;
 use Drupal\Core\Routing\TrustedRedirectResponse;
-use Drupal\Core\Url;
-use Drupal\salesforce\Rest\RestResponse;
 use Drupal\salesforce\Consumer\OAuthCredentials;
-use Drupal\salesforce\Entity\SalesforceAuthConfig;
 use Drupal\salesforce\SalesforceAuthProviderPluginBase;
 use Drupal\salesforce\SalesforceOAuthPluginInterface;
 use Drupal\salesforce\Storage\SalesforceAuthTokenStorageInterface;
-use Drupal\salesforce\Token\SalesforceToken;
 use OAuth\Common\Http\Client\ClientInterface;
 use OAuth\Common\Http\Uri\Uri;
-use Psr\Http\Message\ResponseInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
-use Symfony\Component\HttpFoundation\RedirectResponse;
-use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
 
 /**
+ * Salesforce OAuth user-agent flow auth provider plugin.
+ *
  * @Plugin(
  *   id = "oauth",
  *   label = @Translation("Salesforce OAuth User-Agent")
@@ -27,34 +22,55 @@ use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
  */
 class SalesforceOAuthPlugin extends SalesforceAuthProviderPluginBase implements SalesforceOAuthPluginInterface {
 
-  /** @var \Drupal\salesforce\Consumer\OAuthCredentials */
+  /**
+   * Credentials.
+   *
+   * @var \Drupal\salesforce\Consumer\OAuthCredentials
+   */
   protected $credentials;
 
+  /**
+   * {@inheritdoc}
+   */
   const SERVICE_TYPE = 'oauth';
+
+  /**
+   * {@inheritdoc}
+   */
   const LABEL = 'OAuth';
 
   /**
    * SalesforceOAuthPlugin constructor.
    *
-   * @param $id
+   * @param string $id
+   *   The plugin id.
    * @param \Drupal\salesforce\Consumer\OAuthCredentials $credentials
+   *   The credentials.
    * @param \OAuth\Common\Http\Client\ClientInterface $httpClient
+   *   The oauth http client.
    * @param \Drupal\salesforce\Storage\SalesforceAuthTokenStorageInterface $storage
+   *   Auth token storage service.
    *
    * @throws \OAuth\OAuth2\Service\Exception\InvalidScopeException
+   *   Comment.
    */
   public function __construct($id, OAuthCredentials $credentials, ClientInterface $httpClient, SalesforceAuthTokenStorageInterface $storage) {
     parent::__construct($credentials, $httpClient, $storage, [], new Uri($credentials->getLoginUrl()));
     $this->id = $id;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
     $configuration = array_merge(self::defaultConfiguration(), $configuration);
     $cred = new OAuthCredentials($configuration['consumer_key'], $configuration['login_url'], $configuration['consumer_secret']);
     return new static($configuration['id'], $cred, $container->get('salesforce.http_client_wrapper'), $container->get('salesforce.auth_token_storage'));
   }
 
-
+  /**
+   * {@inheritdoc}
+   */
   public static function defaultConfiguration() {
     $defaults = parent::defaultConfiguration();
     return array_merge($defaults, [
@@ -71,7 +87,7 @@ class SalesforceOAuthPlugin extends SalesforceAuthProviderPluginBase implements
       '#type' => 'textfield',
       '#description' => t('Consumer key of the Salesforce remote application you want to grant access to'),
       '#required' => TRUE,
-      '#default_value' => $this->credentials->getConsumerKey()
+      '#default_value' => $this->credentials->getConsumerKey(),
     ];
 
     $form['consumer_secret'] = [
@@ -79,7 +95,7 @@ class SalesforceOAuthPlugin extends SalesforceAuthProviderPluginBase implements
       '#type' => 'textfield',
       '#description' => $this->t('Consumer secret of the Salesforce remote application.'),
       '#required' => TRUE,
-      '#default_value' => $this->credentials->getConsumerSecret()
+      '#default_value' => $this->credentials->getConsumerSecret(),
     ];
 
     $form['login_url'] = [
@@ -123,18 +139,18 @@ class SalesforceOAuthPlugin extends SalesforceAuthProviderPluginBase implements
     }
     catch (\Exception $e) {
       $this->messenger()->addError(t("Error during authorization: %message", ['%message' => $e->getMessage()]));
-      // $this->eventDispatcher->dispatch(SalesforceEvents::ERROR, new SalesforceErrorEvent($e));
     }
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function getConsumerSecret() {
     return $this->credentials->getConsumerSecret();
   }
 
   /**
-   * @return bool
-   * @throws \OAuth\Common\Http\Exception\TokenResponseException
-   * @see \Drupal\salesforce\Controller\SalesforceOAuthController
+   * {@inheritdoc}
    */
   public function finalizeOauth() {
     $token = $this->requestAccessToken(\Drupal::request()->get('code'));
@@ -151,4 +167,4 @@ class SalesforceOAuthPlugin extends SalesforceAuthProviderPluginBase implements
     return TRUE;
   }
 
-}
\ No newline at end of file
+}

src/Rest/RestClient.php

@@ -15,7 +15,6 @@ use Drupal\salesforce\SFID;
 use Drupal\salesforce\SObject;
 use Drupal\salesforce\SelectQuery;
 use Drupal\salesforce\SelectQueryResult;
-use Drupal\salesforce\Storage\SalesforceAuthTokenStorage;
 use GuzzleHttp\ClientInterface;
 use GuzzleHttp\Exception\RequestException;
 use GuzzleHttp\Psr7\Response;
@@ -136,6 +135,7 @@ class RestClient implements RestClientInterface {
    * Storage helper.
    *
    * @return \Drupal\salesforce\Storage\SalesforceAuthTokenStorage
+   *   The auth token storage service.
    *
    * @deprecated interim, do not use.
    */

src/SalesforceAuthProviderInterface.php

@@ -2,7 +2,6 @@
 
 namespace Drupal\salesforce;
 
-use Drupal\Component\Plugin\DependentPluginInterface;
 use Drupal\Component\Plugin\PluginInspectionInterface;
 use Drupal\Core\Form\FormStateInterface;
 use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
@@ -20,7 +19,7 @@ interface SalesforceAuthProviderInterface extends ServiceInterface, PluginFormIn
   const SOAP_CLASS_PATH = '/services/Soap/class/';
 
   /**
-   * Return an id for this service.
+   * Id of this service.
    *
    * @return string
    *   Id of this service.
@@ -28,47 +27,126 @@ interface SalesforceAuthProviderInterface extends ServiceInterface, PluginFormIn
   public function id();
 
   /**
-   * Return an id for this service.
+   * Label of this service.
    *
    * @return string
    *   Id of this service.
    */
   public function label();
 
+  /**
+   * Auth type id for this service, e.g. oauth, jwt, etc.
+   *
+   * @return string
+   *   Provider type for this auth provider.
+   */
   public function type();
 
+  /**
+   * Perform a refresh of the given token.
+   *
+   * @param \OAuth\Common\Token\TokenInterface $token
+   *   The token.
+   *
+   * @return \OAuth\Common\Token\TokenInterface
+   *   The refreshed token.
+   *
+   * @throws \OAuth\OAuth2\Service\Exception\MissingRefreshTokenException
+   *   Comment.
+   */
   public function refreshAccessToken(TokenInterface $token);
 
+  /**
+   * Login URL, e.g. https://login.salesforce.com, for this plugin.
+   *
+   * @return string
+   *   Login URL.
+   */
   public function getLoginUrl();
 
+  /**
+   * Consumer key for the connected OAuth app.
+   *
+   * @return string
+   *   Consumer key.
+   */
   public function getConsumerKey();
 
+  /**
+   * Consumer secret for the connected OAuth app.
+   *
+   * @return string
+   *   Consumer secret.
+   */
   public function getConsumerSecret();
 
   /**
+   * Access token for this plugin.
+   *
    * @return \OAuth\OAuth2\Token\TokenInterface
+   *   The Token.
+   *
    * @throws \OAuth\Common\Storage\Exception\TokenNotFoundException
    */
   public function getAccessToken();
 
+  /**
+   * Identify for this connection.
+   *
+   * @return array
+   *   Identity for this connection.
+   */
   public function getIdentity();
 
+  /**
+   * TRUE if the connection has a token, regardless of validity.
+   *
+   * @return bool
+   *   TRUE if the connection has a token, regardless of validity.
+   */
   public function hasAccessToken();
 
+  /**
+   * Default configuration for this plugin type.
+   *
+   * @return array
+   *   Default configuration.
+   */
   public static function defaultConfiguration();
 
+  /**
+   * Authorization URL for this plugin type.
+   *
+   * @return string
+   *   Authorization URL for this plugin type.
+   */
   public function getAuthorizationEndpoint();
 
+  /**
+   * Access token URL for this plugin type.
+   *
+   * @return string
+   *   Access token URL for this plugin type.
+   */
   public function getAccessTokenEndpoint();
 
   /**
+   * Instance URL for this connection.
+   *
    * @return string
+   *   Instance URL for this connection.
+   *
    * @throws \OAuth\Common\Storage\Exception\TokenNotFoundException
    */
   public function getInstanceUrl();
 
   /**
-   * Additional callback for configuration form, to be called after saving the config entity.
+   * Callback for configuration form after saving config entity.
+   *
+   * @param array $form
+   *   The configuration form.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The form state.
    */
   public function save(array $form, FormStateInterface $form_state);
 

src/SalesforceAuthProviderPluginBase.php

@@ -5,12 +5,14 @@ namespace Drupal\salesforce;
 use Drupal\Core\DependencyInjection\DependencySerializationTrait;
 use Drupal\Core\Form\FormStateInterface;
 use Drupal\Core\Messenger\MessengerTrait;
-use Drupal\Core\Render\Element\Form;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
 use OAuth\Common\Http\Exception\TokenResponseException;
 use OAuth\Common\Http\Uri\Uri;
 use OAuth\OAuth2\Service\Salesforce;
 
+/**
+ * Shared methods for auth providers.
+ */
 abstract class SalesforceAuthProviderPluginBase extends Salesforce implements SalesforceAuthProviderInterface {
 
   use StringTranslationTrait;
@@ -18,19 +20,36 @@ abstract class SalesforceAuthProviderPluginBase extends Salesforce implements Sa
   use MessengerTrait;
 
   /**
+   * Credentials.
+   *
    * @var \Drupal\salesforce\Consumer\SalesforceCredentials
    */
   protected $credentials;
 
-  /** @var array */
+  /**
+   * Configuration.
+   *
+   * @var array
+   */
   protected $configuration;
 
-  /** @var \Drupal\salesforce\Storage\SalesforceAuthTokenStorageInterface */
+  /**
+   * Token storage.
+   *
+   * @var \Drupal\salesforce\Storage\SalesforceAuthTokenStorageInterface
+   */
   protected $storage;
 
-  /** @var string */
+  /**
+   * Machine name identifier.
+   *
+   * @var string
+   */
   protected $id;
 
+  /**
+   * {@inheritdoc}
+   */
   public static function defaultConfiguration() {
     return [
       'consumer_key' => '',
@@ -111,14 +130,23 @@ abstract class SalesforceAuthProviderPluginBase extends Salesforce implements Sa
 
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function id() {
     return $this->id;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function type() {
     return static::SERVICE_TYPE;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function label() {
     return static::LABEL;
   }
@@ -173,16 +201,20 @@ abstract class SalesforceAuthProviderPluginBase extends Salesforce implements Sa
   }
 
   /**
-   * @param $responseBody
+   * Handle the identity response from Salesforce.
+   *
+   * @param string $responseBody
    *   JSON identity response from Salesforce.
    *
    * @return array
+   *   The identity.
+   *
    * @throws \OAuth\Common\Http\Exception\TokenResponseException
    */
   protected function parseIdentityResponse($responseBody) {
-    $data = json_decode($responseBody, true);
+    $data = json_decode($responseBody, TRUE);
 
-    if (null === $data || !is_array($data)) {
+    if (NULL === $data || !is_array($data)) {
       throw new TokenResponseException('Unable to parse response.');
     }
     elseif (isset($data['error'])) {
@@ -192,12 +224,13 @@ abstract class SalesforceAuthProviderPluginBase extends Salesforce implements Sa
   }
 
   /**
-   * Accessor to the storage adapter to be able to retrieve tokens
+   * Accessor to the storage adapter to be able to retrieve tokens.
    *
    * @return \Drupal\salesforce\Storage\SalesforceAuthTokenStorageInterface
+   *   The token storage.
    */
   public function getStorage() {
     return $this->storage;
   }
 
-}
\ No newline at end of file
+}

src/SalesforceAuthProviderPluginInterface.php

@@ -5,18 +5,25 @@ namespace Drupal\salesforce;
 use Drupal\Component\Plugin\PluginInspectionInterface;
 use Drupal\Core\Plugin\PluginFormInterface;
 
+/**
+ * Auth provider plugin interface.
+ */
 interface SalesforceAuthProviderPluginInterface extends PluginFormInterface, PluginInspectionInterface {
 
   /**
+   * The auth provider service.
+   *
    * @return \Drupal\salesforce\SalesforceAuthProviderInterface
+   *   The auth provider service.
    */
   public function service();
 
   /**
-   * Get the login URL set for this auth provider.
+   * Login URL set for this auth provider.
    *
    * @return string
+   *   Login URL set for this auth provider.
    */
   public function getLoginUrl();
 
-}
\ No newline at end of file
+}

src/SalesforceAuthProviderPluginManager.php

@@ -4,18 +4,24 @@ namespace Drupal\salesforce;
 
 use Drupal\Core\Cache\CacheBackendInterface;
 use Drupal\Core\Extension\ModuleHandlerInterface;
-use Drupal\Core\Form\FormStateInterface;
 use Drupal\Core\Plugin\DefaultPluginManager;
 
 use Drupal\Core\Entity\EntityTypeManagerInterface;
-use \Drupal\salesforce\Entity\SalesforceAuthConfig as SalesforceAuthEntity;
+use Drupal\salesforce\Entity\SalesforceAuthConfig as SalesforceAuthEntity;
 use Drupal\salesforce\Entity\SalesforceAuthConfig;
 use OAuth\Common\Storage\Exception\TokenNotFoundException;
 use OAuth\OAuth2\Token\StdOAuth2Token;
 
-
+/**
+ * Auth provider plugin manager.
+ */
 class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
 
+  /**
+   * Config from salesforce.settings.
+   *
+   * @var \Drupal\Core\Config\ImmutableConfig
+   */
   protected $config;
 
   /**
@@ -28,16 +34,13 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
   /**
    * Salesforce Auth storage.
    *
-   * @var \Drupal\Core\Entity\EntityStorageInterface
+   * @var \Drupal\Core\Config\Entity\ConfigEntityStorageInterface
    */
   protected $authStorage;
 
-
   /**
-   * Constructs a KeyPluginManager.
+   * Constructor.
    *
-   * @param string $type
-   *   The plugin type.
    * @param \Traversable $namespaces
    *   An object that implements \Traversable which contains the root paths
    *   keyed by the corresponding namespace to look for plugin implementations.
@@ -45,6 +48,8 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
    *   Cache backend instance to use.
    * @param \Drupal\Core\Extension\ModuleHandlerInterface $module_handler
    *   The module handler.
+   * @param \Drupal\Core\Entity\EntityTypeManagerInterface $etm
+   *   Entity type manager service.
    */
   public function __construct(\Traversable $namespaces, CacheBackendInterface $cache_backend, ModuleHandlerInterface $module_handler, EntityTypeManagerInterface $etm) {
     parent::__construct('Plugin/SalesforceAuthProvider', $namespaces, $module_handler, 'Drupal\salesforce\SalesforceAuthProviderInterface');
@@ -54,6 +59,8 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
   }
 
   /**
+   * Backwards-compatibility for legacy singleton auth.
+   *
    * @deprecated interim, do not use.
    */
   public static function updateAuthConfig() {
@@ -70,13 +77,15 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
   }
 
   /**
+   * Backwards-compatibility for legacy singleton auth.
+   *
    * @deprecated interim, do not use.
    */
   public static function getAuthConfig() {
     $config = \Drupal::configFactory()->getEditable('salesforce.settings');
     $auth_provider = $config->get('salesforce_auth_provider');
     if (!$auth_provider || !$oauth = SalesforceAuthConfig::load($auth_provider)) {
-      // config to new plugin config system.
+      // Config to new plugin config system.
       $values = [
         'id' => 'oauth_default',
         'label' => 'OAuth Default',
@@ -90,6 +99,15 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
     return $oauth;
   }
 
+  /**
+   * Wrapper for salesforce_auth storage service.
+   *
+   * @return \Drupal\Core\Config\Entity\ConfigEntityStorageInterface
+   *   Storage for salesforce_auth.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
+   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
+   */
   protected function authStorage() {
     if (empty($this->authStorage)) {
       $this->authStorage = $this->etm->getStorage('salesforce_auth');
@@ -97,10 +115,28 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
     return $this->authStorage;
   }
 
+  /**
+   * All Salesforce auth providers.
+   *
+   * @return \Drupal\salesforce\Entity\SalesforceAuthConfig[]
+   *   All auth provider plugins.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
+   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
+   */
   public function getProviders() {
     return $this->authStorage()->loadMultiple();
   }
 
+  /**
+   * TRUE if any auth providers are defined.
+   *
+   * @return bool
+   *   TRUE if any auth providers are defined.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
+   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
+   */
   public function hasProviders() {
     return $this->authStorage()->hasData();
   }
@@ -108,7 +144,8 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
   /**
    * Get the active auth service provider, or null if it has not been assigned.
    *
-   * @return \Drupal\salesforce\Entity\SalesforceAuthConfig
+   * @return \Drupal\salesforce\Entity\SalesforceAuthConfig|null
+   *   The active service provider, or null if it has not been assigned.
    */
   public function getConfig() {
     $provider_id = $this->config()->get('salesforce_auth_provider');
@@ -119,7 +156,10 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
   }
 
   /**
+   * The auth provider plugin of the active service provider, or null.
+   *
    * @return \Drupal\salesforce\SalesforceAuthProviderInterface|null
+   *   The auth provider plugin of the active service provider, or null.
    */
   public function getProvider() {
     if (!$this->getConfig()) {
@@ -132,6 +172,7 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
    * Get the active token, or null if it has not been assigned.
    *
    * @return \OAuth\OAuth2\Token\TokenInterface
+   *   The token of the plugin of the active config, or null.
    */
   public function getToken() {
     if (!$config = $this->getConfig()) {
@@ -152,6 +193,7 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
    * Force a refresh of the active token and return the fresh token.
    *
    * @return \OAuth\OAuth2\Token\TokenInterface|null
+   *   The token.
    */
   public function refreshToken() {
     if (!$config = $this->getConfig()) {
@@ -164,6 +206,12 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
     return $provider->refreshAccessToken($token);
   }
 
+  /**
+   * Wrapper for salesforce.settings config.
+   *
+   * @return \Drupal\Core\Config\ImmutableConfig
+   *   Salesforce settings config.
+   */
   protected function config() {
     if (!$this->config) {
       $this->config = \Drupal::config('salesforce.settings');
@@ -171,4 +219,4 @@ class SalesforceAuthProviderPluginManager extends DefaultPluginManager {
     return $this->config;
   }
 
-}
\ No newline at end of file
+}

src/SalesforceOAuthPluginInterface.php

@@ -2,10 +2,32 @@
 
 namespace Drupal\salesforce;
 
+/**
+ * OAuth user-agent plugin interface.
+ *
+ * OAuth user-agent flow requires a 2-part handshake to complete authentication.
+ * This interface exposes methods to make the handshake possible.
+ */
 interface SalesforceOAuthPluginInterface extends SalesforceAuthProviderPluginInterface {
 
+  /**
+   * Complete the OAuth user-agent handshake.
+   *
+   * @return bool
+   *   TRUE if oauth finalization was successful.
+   *
+   * @throws \OAuth\Common\Http\Exception\TokenResponseException
+   *
+   * @see \Drupal\salesforce\Controller\SalesforceOAuthController
+   */
   public function finalizeOauth();
 
+  /**
+   * Getter for consumer secret.
+   *
+   * @return string
+   *   The consumer secret.
+   */
   public function getConsumerSecret();
 
-}
\ No newline at end of file
+}

src/Storage/SalesforceAuthTokenStorage.php

@@ -8,26 +8,39 @@ use Drupal\salesforce\Token\SalesforceToken;
 use OAuth\Common\Storage\Exception\TokenNotFoundException;
 use OAuth\Common\Token\TokenInterface;
 
+/**
+ * Salesforce auth token storage.
+ */
 class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface {
 
   const TOKEN_STORAGE_PREFIX = "salesforce.auth_tokens";
   const AUTH_STATE_STORAGE_PREFIX = "salesforce.auth_state";
   const IDENTITY_STORAGE_PREFIX = "salesforce.auth_identity";
 
+  /**
+   * State kv storage.
+   *
+   * @var \Drupal\Core\State\StateInterface
+   */
   protected $state;
 
   /**
-   * @deprecated interim, do not use.
+   * SalesforceAuthTokenStorage constructor.
+   *
+   * @param \Drupal\Core\State\StateInterface $state
+   *   State service.
    */
-  private $client;
-
   public function __construct(StateInterface $state) {
     $this->state = $state;
   }
 
   /**
-   * @deprecated interim, do not use.
+   * Backwards-compatibility for legacy singleton auth.
+   *
    * @return string
+   *   Id of the active oauth.
+   *
+   * @deprecated interim, do not use.
    */
   private function service() {
     $oauth = SalesforceAuthProviderPluginManager::getAuthConfig();
@@ -35,6 +48,8 @@ class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface
   }
 
   /**
+   * Backwards-compatibility for legacy singleton auth.
+   *
    * @deprecated interim, do not use.
    */
   public function updateToken() {
@@ -46,6 +61,8 @@ class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface
   }
 
   /**
+   * Backwards-compatibility for legacy singleton auth.
+   *
    * @deprecated interim, do not use.
    */
   public function updateIdentity() {
@@ -53,20 +70,38 @@ class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface
     return $this;
   }
 
+  /**
+   * Token storage key for given service.
+   *
+   * @return string
+   *   Token storage key for given service.
+   */
   protected static function getTokenStorageId($service) {
     return self::TOKEN_STORAGE_PREFIX . '.' . $service;
   }
 
+  /**
+   * Auth state storage key for given service.
+   *
+   * @return string
+   *   Auth state storage key for given service.
+   */
   protected static function getAuthStateStorageId($service) {
     return self::AUTH_STATE_STORAGE_PREFIX . '.' . $service;
   }
 
+  /**
+   * Identity storage key for given service.
+   *
+   * @return string
+   *   Identity storage key for given service.
+   */
   protected static function getIdentityStorageId($service) {
     return self::IDENTITY_STORAGE_PREFIX . '.' . $service;
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function retrieveAccessToken($service) {
     if ($token = $this->state->get(self::getTokenStorageId($service))) {
@@ -76,7 +111,7 @@ class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function storeAccessToken($service, TokenInterface $token) {
     $this->state->set(self::getTokenStorageId($service), $token);
@@ -84,7 +119,7 @@ class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function hasAccessToken($service) {
     try {
@@ -96,23 +131,22 @@ class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
-
   public function clearToken($service) {
     $this->state->delete(self::getTokenStorageId($service));
     return $this;
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function clearAllTokens() {
     // noop. We don't do this. Only here to satisfy interface.
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function storeAuthorizationState($service, $state) {
     $this->state->set(self::getAuthStateStorageId($service), $state);
@@ -120,21 +154,21 @@ class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function hasAuthorizationState($service) {
     return !empty($this->retrieveAuthorizationState($service));
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function retrieveAuthorizationState($service) {
     return $this->state->get(self::getAuthStateStorageId($service));
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function clearAuthorizationState($service) {
     $this->state->delete(self::getAuthStateStorageId($service));
@@ -142,14 +176,14 @@ class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function clearAllAuthorizationStates() {
     // noop. only here to satisfy interface. Use clearAuthorizationState().
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function storeIdentity($service, $identity) {
     $this->state->set(self::getIdentityStorageId($service), $identity);
@@ -157,21 +191,21 @@ class SalesforceAuthTokenStorage implements SalesforceAuthTokenStorageInterface
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function hasIdentity($service) {
     return !empty($this->retrieveIdentity($service));
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function retrieveIdentity($service) {
     return $this->state->get(self::getIdentityStorageId($service));
   }
 
   /**
-   *{@inheritdoc}
+   * {@inheritdoc}
    */
   public function clearIdentity($service) {
     $this->state->delete(self::getIdentityStorageId($service));

src/Storage/SalesforceAuthTokenStorageInterface.php

@@ -5,7 +5,7 @@ namespace Drupal\salesforce\Storage;
 use OAuth\Common\Storage\TokenStorageInterface;
 
 /**
- * Interface SalesforceAuthTokenStorageInterface adds identity handling to token storage.
+ * Add identity handling to token storage.
  *
  * @package Drupal\salesforce\Storage
  */
@@ -13,21 +13,31 @@ interface SalesforceAuthTokenStorageInterface extends TokenStorageInterface {
 
   /**
    * Setter for identity storage.
+   *
+   * @return $this
    */
   public function storeIdentity($service, $identity);
 
   /**
    * Return boolean indicating whether this service has an identity.
+   *
+   * @return bool
+   *   TRUE if the service has an identity.
    */
   public function hasIdentity($service);
 
   /**
-   * Getter for identity.
+   * Identity for the given service.
+   *
+   * @return array
+   *   Identity.
    */
   public function retrieveIdentity($service);
 
   /**
    * Clear identity for service.
+   *
+   * @return $this
    */
   public function clearIdentity($service);
 

src/Token/SalesforceToken.php

@@ -4,6 +4,9 @@ namespace Drupal\salesforce\Token;
 
 use OAuth\OAuth2\Token\StdOAuth2Token;
 
+/**
+ * Salesforce auth token.
+ */
 class SalesforceToken extends StdOAuth2Token {