Documentation standards updates

modules/salesforce_pull/salesforce_pull.drush.inc

@@ -2,6 +2,7 @@
 
 /**
  * @file
+ * Salesforce Pull drush 8 commands.
  */
 
 use Drupal\salesforce\SFID;
@@ -90,6 +91,7 @@ function salesforce_pull_drush_command() {
  * Queues records for pull from salesforce for the given mapping.
  *
  * @param string $name
+ *   Mapping name.
  *
  * @deprecated Support for drush 8 is deprecated and will be removed in a future release.
  */
@@ -144,7 +146,9 @@ function drush_salesforce_pull_sf_pull_query($name) {
  * Queues records for pull from Salesforce from the given file and mapping.
  *
  * @param string $file
+ *   File name with IDs.
  * @param string $name
+ *   Mapping name.
  *
  * @deprecated Support for drush 8 is deprecated and will be removed in a future release.
  */
@@ -248,7 +252,12 @@ function drush_salesforce_pull_sf_pull_file($file, $name = NULL) {
 }
 
 /**
+ * Get an array of all pull mappings, or the given mapping by name.
+ *
  * @deprecated Support for drush 8 is deprecated and will be removed in a future release.
+ *
+ * @return \Drupal\salesforce_mapping\Entity\SalesforceMappingInterface[]
+ *   Mappings.
  */
 function _salesforce_pull_load_single_mapping_array_or_all_pull_mappings($name = NULL) {
   if ($name != NULL) {
@@ -269,6 +278,8 @@ function _salesforce_pull_load_single_mapping_array_or_all_pull_mappings($name =
 }
 
 /**
+ * Reset pull time on all mappings, or the given mapping by name.
+ *
  * @deprecated Support for drush 8 is deprecated and will be removed in a future release.
  */
 function drush_salesforce_pull_sf_pull_reset($name = NULL) {
@@ -285,6 +296,8 @@ function drush_salesforce_pull_sf_pull_reset($name = NULL) {
 }
 
 /**
+ * Set pull time on all mappings, or the given mapping by name.
+ *
  * @deprecated Support for drush 8 is deprecated and will be removed in a future release.
  */
 function drush_salesforce_pull_sf_pull_set($name, $time = NULL) {

modules/salesforce_pull/src/Commands/SalesforcePullCommands.php

@@ -27,19 +27,33 @@ use Symfony\Component\Console\Output\Output;
 class SalesforcePullCommands extends SalesforceCommandsBase {
 
   /**
-   * @var \Drupal\salesforce_pull\QueueHandler*/
+   * Pull queue handler service.
+   *
+   * @var \Drupal\salesforce_pull\QueueHandler
+   */
   protected $pullQueue;
 
   /**
-   * @var \Symfony\Component\EventDispatcher\EventDispatcher*/
+   * Event dispatcher service.
+   *
+   * @var \Symfony\Component\EventDispatcher\EventDispatcher
+   */
   protected $eventDispatcher;
 
   /**
    * SalesforcePullCommands constructor.
    *
    * @param \Drupal\salesforce\Rest\RestClient $client
+   *   Salesforce client.
    * @param \Drupal\Core\Entity\EntityTypeManagerInterface $etm
+   *   Entity type manager.
    * @param \Drupal\salesforce_pull\QueueHandler $pullQueue
+   *   Pull queue handler service.
+   * @param \Drupal\Component\EventDispatcher\ContainerAwareEventDispatcher $eventDispatcher
+   *   Event dispatcher service.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
+   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
    */
   public function __construct(RestClient $client, EntityTypeManagerInterface $etm, QueueHandler $pullQueue, ContainerAwareEventDispatcher $eventDispatcher) {
     parent::__construct($client, $etm);
@@ -48,6 +62,8 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
   }
 
   /**
+   * Fetch a pull mapping interactively.
+   *
    * @hook interact salesforce_pull:pull-query
    */
   public function interactPullQuery(Input $input, Output $output) {
@@ -55,6 +71,8 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
   }
 
   /**
+   * Fetch a filename interactively.
+   *
    * @hook interact salesforce_pull:pull-file
    */
   public function interactPullFile(Input $input, Output $output) {
@@ -71,6 +89,8 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
   }
 
   /**
+   * Fetch a pull mapping interactively.
+   *
    * @hook interact salesforce_pull:pull-reset
    */
   public function interactPullReset(Input $input, Output $output) {
@@ -78,6 +98,8 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
   }
 
   /**
+   * Fetch a pull mapping interactively.
+   *
    * @hook interact salesforce_pull:pull-set
    */
   public function interactPullSet(Input $input, Output $output) {
@@ -85,9 +107,12 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
   }
 
   /**
-   * Given a mapping, enqueue records for pull from Salesforce, ignoring modification timestamp. This command is useful, for example, when seeding content for a Drupal site prior to deployment.
+   * Given a mapping, enqueue records for pull from Salesforce.
    *
-   * @param $name
+   * Ignoring modification timestamp. This command is useful, for example, when
+   * seeding content for a Drupal site prior to deployment.
+   *
+   * @param string $name
    *   Machine name of the Salesforce Mapping for which to queue pull records.
    * @param array $options
    *   An associative array of options whose values come from cli, aliases, config, etc.
@@ -114,7 +139,12 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
    * @command salesforce_pull:pull-query
    * @aliases sfpq,sfiq,sf-pull-query,salesforce_pull:query
    */
-  public function pullQuery($name, array $options = ['where' => '', 'start' => 0, 'stop' => 0, 'force-pull' => FALSE]) {
+  public function pullQuery($name, array $options = [
+    'where' => '',
+    'start' => 0,
+    'stop' => 0,
+    'force-pull' => FALSE,
+  ]) {
     $mappings = $this->getPullMappingsFromName($name);
     $start = $options['start'] ? strtotime($options['start']) : 0;
     $stop = $options['stop'] ? strtotime($options['stop']) : 0;
@@ -161,9 +191,9 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
   /**
    * Given a mapping, enqueue a list of object IDs to be pulled from a CSV file, e.g. a Salesforce report. The first column of the CSV file must be SFIDs. Additional columns will be ignored.
    *
-   * @param $file
+   * @param string $file
    *   CSV file name of 15- or 18-character Salesforce ids to be pulled.
-   * @param $name
+   * @param string $name
    *   Machine name of the Salesforce Mapping for which to queue pull records.
    *
    * @command salesforce_pull:pull-file
@@ -261,7 +291,7 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
    * Reset pull timestamps for one or all Salesforce Mappings, and set all mapped objects to be force-pulled.
    *
    * @param string $name
-   *   mapping id.
+   *   Mapping id.
    * @param array $options
    *   An associative array of options whose values come from cli, aliases, config, etc.
    *
@@ -298,10 +328,12 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
   /**
    * Set pull timestamp on a single Salesforce Mappings to a specific point in history (or now).
    *
-   * @param $name
-   *   mapping id.
+   * @param string $name
+   *   Mapping id.
    * @param int $time
-   *   timestamp.
+   *   Timestamp.
+   * @param array $options
+   *   Assoc array of options.
    *
    * @option delete
    *   Reset delete date timestamp (instead of pull date timestamp)
@@ -313,7 +345,7 @@ class SalesforcePullCommands extends SalesforceCommandsBase {
    * @command salesforce_pull:pull-set
    * @aliases sf-pull-set,salesforce_pull:set
    */
-  public function pullSet($name, $time, $options = ['delete' => NULL]) {
+  public function pullSet($name, $time, array $options = ['delete' => NULL]) {
     $mappings = $this->getPullMappingsFromName($name);
     foreach ($mappings as $mapping) {
       $mapping->setLastPullTime(NULL);

modules/salesforce_pull/src/DeleteHandler.php

@@ -74,6 +74,11 @@ class DeleteHandler {
    *   Entity Manager service.
    * @param \Drupal\Core\State\StateInterface $state
    *   State service.
+   * @param \Symfony\Component\EventDispatcher\EventDispatcherInterface $event_dispatcher
+   *   Event dispatcher service.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
+   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
    */
   public function __construct(RestClientInterface $sfapi, EntityTypeManagerInterface $entity_type_manager, StateInterface $state, EventDispatcherInterface $event_dispatcher) {
     $this->sfapi = $sfapi;

modules/salesforce_pull/src/Plugin/QueueWorker/PullBase.php

@@ -68,8 +68,11 @@ abstract class PullBase extends QueueWorkerBase implements ContainerFactoryPlugi
    *   The entity type manager.
    * @param \Drupal\salesforce\Rest\RestClientInterface $client
    *   Salesforce REST client.
-   * @param \Symfony\Component\EventDispatcher\EventDispatcherInterface $eventDispatcher
+   * @param \Symfony\Component\EventDispatcher\EventDispatcherInterface $event_dispatcher
    *   Event dispatcher service.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
+   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
    */
   public function __construct(EntityTypeManagerInterface $entity_type_manager, RestClientInterface $client, EventDispatcherInterface $event_dispatcher) {
     $this->etm = $entity_type_manager;
@@ -91,11 +94,15 @@ abstract class PullBase extends QueueWorkerBase implements ContainerFactoryPlugi
   }
 
   /**
-   * {@inheritdoc}
+   * Queue item process callback.
+   *
+   * @param \Drupal\salesforce_pull\PullQueueItem $item
+   *   Pull queue item. Note: typehint missing because we can't change the
+   *   inherited API.
    */
   public function processItem($item) {
-    $sf_object = $item->sobject;
-    $mapping = $this->mappingStorage->load($item->mapping_id);
+    $sf_object = $item->getSobject();
+    $mapping = $this->mappingStorage->load($item->getMappingId());
     if (!$mapping) {
       return;
     }
@@ -109,7 +116,7 @@ abstract class PullBase extends QueueWorkerBase implements ContainerFactoryPlugi
     // @TODO one-to-many: this is a blocker for OTM support:
     $mapped_object = current($mapped_object);
     if (!empty($mapped_object)) {
-      return $this->updateEntity($mapping, $mapped_object, $sf_object, $item->force_pull);
+      return $this->updateEntity($mapping, $mapped_object, $sf_object, $item->getForcePull());
     }
     else {
       return $this->createEntity($mapping, $sf_object);
@@ -126,7 +133,8 @@ abstract class PullBase extends QueueWorkerBase implements ContainerFactoryPlugi
    *   SF Mmapped object.
    * @param \Drupal\salesforce\SObject $sf_object
    *   Current Salesforce record array.
-   * @param bool $force
+   * @param bool $force_pull
+   *   If true, ignore entity and SF timestamps.
    */
   protected function updateEntity(SalesforceMappingInterface $mapping, MappedObjectInterface $mapped_object, SObject $sf_object, $force_pull = FALSE) {
     if (!$mapping->checkTriggers([MappingConstants::SALESFORCE_MAPPING_SYNC_SF_UPDATE])) {
@@ -209,7 +217,6 @@ abstract class PullBase extends QueueWorkerBase implements ContainerFactoryPlugi
    *   Object of field maps.
    * @param \Drupal\salesforce\SObject $sf_object
    *   Current Salesforce record array.
-   * @param bool $force_pull
    */
   protected function createEntity(SalesforceMappingInterface $mapping, SObject $sf_object) {
     if (!$mapping->checkTriggers([MappingConstants::SALESFORCE_MAPPING_SYNC_SF_CREATE])) {
@@ -276,7 +283,11 @@ abstract class PullBase extends QueueWorkerBase implements ContainerFactoryPlugi
         }
       }
 
-      $this->eventDispatcher->dispatch(SalesforceEvents::NOTICE, new SalesforceNoticeEvent(NULL, 'Created entity %id %label associated with Salesforce Object ID: %sfid', ['%id' => $entity->id(), '%label' => $entity->label(), '%sfid' => (string) $sf_object->id()]));
+      $this->eventDispatcher->dispatch(SalesforceEvents::NOTICE, new SalesforceNoticeEvent(NULL, 'Created entity %id %label associated with Salesforce Object ID: %sfid', [
+        '%id' => $entity->id(),
+        '%label' => $entity->label(),
+        '%sfid' => (string) $sf_object->id(),
+      ]));
 
       return MappingConstants::SALESFORCE_MAPPING_SYNC_SF_CREATE;
     }

modules/salesforce_pull/src/PullException.php

@@ -2,11 +2,11 @@
 
 namespace Drupal\salesforce_pull;
 
-use Symfony\Component\Serializer\Exception\Exception as SymfonyException;
+use Drupal\salesforce\Exception;
 
 /**
- *
+ * Pull exception.
  */
-class PullException extends \RuntimeException implements SymfonyException {
+class PullException extends Exception {
 
 }

modules/salesforce_pull/src/PullQueueItem.php

@@ -6,36 +6,85 @@ use Drupal\salesforce\SObject;
 use Drupal\salesforce_mapping\Entity\SalesforceMappingInterface;
 
 /**
- *
+ * A salesforce_pull_queue item.
  */
 class PullQueueItem {
 
   /**
+   * The salesforce object data.
+   *
    * @var \Drupal\salesforce\SObject
    */
-  public $sobject;
+  protected $sobject;
 
   /**
+   * The mapping id corresponding to this pull.
+   *
    * @var string
    */
-  public $mapping_id;
+  protected $mappingId;
 
   /**
    * Whether to force pull for the given record.
    *
    * @var bool
    */
-  public $force_pull;
+  protected $forcePull;
 
   /**
+   * Construct a pull queue item.
+   *
    * @param \Drupal\salesforce\SObject $sobject
+   *   Salesforce data.
    * @param \Drupal\salesforce_mapping\Entity\SalesforceMappingInterface $mapping
+   *   Mapping.
    * @param bool $force_pull
+   *   Force data to be pulled, ignoring any timestamps.
    */
   public function __construct(SObject $sobject, SalesforceMappingInterface $mapping, $force_pull = FALSE) {
     $this->sobject = $sobject;
-    $this->mapping_id = $mapping->id;
-    $this->force_pull = $force_pull;
+    $this->mappingId = $mapping->id;
+    $this->forcePull = $force_pull;
+  }
+
+  /**
+   * Getter.
+   *
+   * @return \Drupal\salesforce\SObject
+   *   Salesforce data.
+   */
+  public function getSobject() {
+    return $this->sobject;
+  }
+
+  /**
+   * Getter.
+   *
+   * @return string
+   *   Salesforce mapping id.
+   */
+  public function getMappingId() {
+    // Legacy backwards compatibility.
+    // @TODO remove for 8.x-3.3
+    if (property_exists($this, 'mapping_id')) {
+      return $this->mapping_id;
+    }
+    return $this->mappingId;
+  }
+
+  /**
+   * Getter.
+   *
+   * @return bool
+   *   Force pull.
+   */
+  public function getForcePull() {
+    // Legacy backwards compatibility.
+    // @TODO remove for 8.x-3.3
+    if (property_exists($this, 'force_pull')) {
+      return $this->force_pull;
+    }
+    return $this->forcePull;
   }
 
 }

modules/salesforce_pull/src/QueueHandler.php

@@ -27,40 +27,65 @@ class QueueHandler {
   const PULL_MAX_QUEUE_SIZE = 100000;
 
   /**
+   * Salesforce client.
+   *
    * @var \Drupal\salesforce\Rest\RestClientInterface
    */
   protected $sfapi;
 
   /**
+   * Queue service.
+   *
    * @var \Drupal\Core\Queue\QueueInterface
    */
   protected $queue;
 
   /**
-   * @var arrayof\Drupal\salesforce_mapping\Entity\SalesforceMapping
+   * All pull mappings.
+   *
+   * @var \Drupal\salesforce_mapping\Entity\SalesforceMapping[]
    */
   protected $mappings;
 
   /**
+   * Config service.
+   *
    * @var \Drupal\Core\Config\Config
    */
   protected $config;
 
   /**
+   * The current request.
+   *
    * @var \Symfony\Component\HttpFoundation\Request
    */
   protected $request;
 
   /**
+   * Event dispatcher service.
+   *
    * @var \Symfony\Component\EventDispatcher\EventDispatcherInterface
    */
   protected $eventDispatcher;
 
   /**
+   * QueueHandler constructor.
+   *
    * @param \Drupal\salesforce\Rest\RestClientInterface $sfapi
-   * @param QueueInterface $queue
-   * @param StateInterface $state
+   *   Salesforce service.
+   * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
+   *   Entity type manager service.
+   * @param \Drupal\Core\Queue\QueueDatabaseFactory $queue_factory
+   *   Queue service.
+   * @param \Drupal\Core\Config\ConfigFactoryInterface $config
+   *   Config service.
    * @param \Symfony\Component\EventDispatcher\EventDispatcherInterface $event_dispatcher
+   *   Event dispatcher service.
+   * @param \Drupal\Component\Datetime\TimeInterface $time
+   *   Time service.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
+   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
    */
   public function __construct(RestClientInterface $sfapi, EntityTypeManagerInterface $entity_type_manager, QueueDatabaseFactory $queue_factory, ConfigFactoryInterface $config, EventDispatcherInterface $event_dispatcher, TimeInterface $time) {
     $this->sfapi = $sfapi;
@@ -113,6 +138,8 @@ class QueueHandler {
   }
 
   /**
+   * Fetch and enqueue records from Salesforce.
+   *
    * Given a mapping and optional timeframe, perform an API query for updated
    * records and enqueue them into the pull queue.
    *
@@ -127,7 +154,7 @@ class QueueHandler {
    *   Timestamp of ending window from which to pull records. If omitted, use
    *   "now".
    *
-   * @return FALSE | int
+   * @return false|int
    *   Return the number of records fetched by the pull query, or FALSE no
    *   query was executed.
    *
@@ -169,7 +196,7 @@ class QueueHandler {
    *
    * @see SalesforceMappingInterface
    */
-  public function doSfoQuery(SalesforceMappingInterface $mapping, $mapped_fields = [], $start = 0, $stop = 0) {
+  public function doSfoQuery(SalesforceMappingInterface $mapping, array $mapped_fields = [], $start = 0, $stop = 0) {
     // @TODO figure out the new way to build the query.
     // Execute query.
     try {
@@ -188,12 +215,14 @@ class QueueHandler {
   }
 
   /**
-   * Iterates over an entire result set, calling nextRecordsUrl when necessary,
-   * and inserts the records into pull queue.
+   * Inserts the given records into pull queue.
    *
    * @param \Drupal\salesforce_mapping\Entity\SalesforceMappingInterface $mapping
+   *   Mapping.
    * @param \Drupal\salesforce\SelectQueryResult $results
+   *   Results.
    * @param bool $force_pull
+   *   Force flag.
    */
   public function enqueueAllResults(SalesforceMappingInterface $mapping, SelectQueryResult $results, $force_pull = FALSE) {
     while (!$this->enqueueResultSet($mapping, $results, $force_pull)) {
@@ -250,8 +279,11 @@ class QueueHandler {
    * Enqueue a single record for pull.
    *
    * @param \Drupal\salesforce_mapping\Entity\SalesforceMappingInterface $mapping
+   *   Mapping.
    * @param \Drupal\salesforce\SObject $record
-   * @param bool $foce
+   *   Salesforce data.
+   * @param bool $force_pull
+   *   If TRUE, ignore timestamps and force data to be pulled.
    */
   public function enqueueRecord(SalesforceMappingInterface $mapping, SObject $record, $force_pull = FALSE) {
     $this->queue->createItem(new PullQueueItem($record, $mapping, $force_pull));

modules/salesforce_pull/tests/src/Unit/PullBaseTest.php

@@ -206,7 +206,11 @@ class PullBaseTest extends UnitTestCase {
     $container->set('entity_type.manager', $this->etm);
     \Drupal::setContainer($container);
 
-    $this->pullWorker = $this->getMock(PullBase::CLASS, ['getMappedEntity'], [$this->etm, $this->sfapi, $this->ed]);
+    $this->pullWorker = $this->getMock(PullBase::CLASS, ['getMappedEntity'], [
+      $this->etm,
+      $this->sfapi,
+      $this->ed,
+    ]);
     $this->pullWorker->expects($this->any())
       ->method('getMappedEntity')
       ->willReturn($this->entity);

modules/salesforce_pull/tests/src/Unit/PullQueueItemTest.php

@@ -35,7 +35,7 @@ class PullQueueItemTest extends UnitTestCase {
       ->willReturn(1);
     $item = new PullQueueItem($sobject, $mapping);
     $this->assertTrue($item instanceof PullQueueItem);
-    $this->assertEquals(1, $item->mapping_id);
+    $this->assertEquals(1, $item->mappingId);
   }
 
 }

modules/salesforce_pull/tests/src/Unit/QueueHandlerTest.php

@@ -25,7 +25,7 @@ use Symfony\Component\EventDispatcher\EventDispatcherInterface;
  * @group salesforce_pull
  */
 class QueueHandlerTest extends UnitTestCase {
-  static $modules = ['salesforce_pull'];
+  static public $modules = ['salesforce_pull'];
 
   /**
    * {@inheritdoc}
@@ -119,7 +119,14 @@ class QueueHandlerTest extends UnitTestCase {
 
     $this->qh = $this->getMockBuilder(QueueHandler::CLASS)
       ->setMethods(['parseUrl'])
-      ->setConstructorArgs([$this->sfapi, $this->etm, $this->queue_factory, $this->configFactory, $this->ed, $this->time])
+      ->setConstructorArgs([
+        $this->sfapi,
+        $this->etm,
+        $this->queue_factory,
+        $this->configFactory,
+        $this->ed,
+        $this->time,
+      ])
       ->getMock();
     $this->qh->expects($this->any())
       ->method('parseUrl')
@@ -157,7 +164,14 @@ class QueueHandlerTest extends UnitTestCase {
 
     $this->qh = $this->getMockBuilder(QueueHandler::CLASS)
       ->setMethods(['parseUrl'])
-      ->setConstructorArgs([$this->sfapi, $this->etm, $this->queue_factory, $this->configFactory, $this->ed, $this->time])
+      ->setConstructorArgs([
+        $this->sfapi,
+        $this->etm,
+        $this->queue_factory,
+        $this->configFactory,
+        $this->ed,
+        $this->time,
+      ])
       ->getMock();
     $this->qh->expects($this->any())
       ->method('parseUrl')