From 5558f0c4fa6fea3fd01871a106c8df26471430fd Mon Sep 17 00:00:00 2001 From: Aaron Bauman <aaron@messageagency.com> Date: Fri, 30 Nov 2018 11:14:49 -0500 Subject: [PATCH] Documentation standards updates --- .../salesforce_pull/salesforce_pull.drush.inc | 13 ++++ .../src/Commands/SalesforcePullCommands.php | 56 +++++++++++++---- modules/salesforce_pull/src/DeleteHandler.php | 5 ++ .../src/Plugin/QueueWorker/PullBase.php | 27 +++++--- modules/salesforce_pull/src/PullException.php | 6 +- modules/salesforce_pull/src/PullQueueItem.php | 61 +++++++++++++++++-- modules/salesforce_pull/src/QueueHandler.php | 48 ++++++++++++--- .../tests/src/Unit/PullBaseTest.php | 6 +- .../tests/src/Unit/PullQueueItemTest.php | 2 +- .../tests/src/Unit/QueueHandlerTest.php | 20 +++++- 10 files changed, 202 insertions(+), 42 deletions(-) diff --git a/modules/salesforce_pull/salesforce_pull.drush.inc b/modules/salesforce_pull/salesforce_pull.drush.inc index 6c5e185b..3dc6167f 100644 --- a/modules/salesforce_pull/salesforce_pull.drush.inc +++ b/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) { diff --git a/modules/salesforce_pull/src/Commands/SalesforcePullCommands.php b/modules/salesforce_pull/src/Commands/SalesforcePullCommands.php index 8c724381..7d795b0a 100644 --- a/modules/salesforce_pull/src/Commands/SalesforcePullCommands.php +++ b/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); diff --git a/modules/salesforce_pull/src/DeleteHandler.php b/modules/salesforce_pull/src/DeleteHandler.php index 30cc6f4d..dda74d36 100644 --- a/modules/salesforce_pull/src/DeleteHandler.php +++ b/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; diff --git a/modules/salesforce_pull/src/Plugin/QueueWorker/PullBase.php b/modules/salesforce_pull/src/Plugin/QueueWorker/PullBase.php index 04756bcc..ae459518 100644 --- a/modules/salesforce_pull/src/Plugin/QueueWorker/PullBase.php +++ b/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; } diff --git a/modules/salesforce_pull/src/PullException.php b/modules/salesforce_pull/src/PullException.php index 912eab69..afa0cd4b 100644 --- a/modules/salesforce_pull/src/PullException.php +++ b/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 { } diff --git a/modules/salesforce_pull/src/PullQueueItem.php b/modules/salesforce_pull/src/PullQueueItem.php index 1787540f..59cc0219 100644 --- a/modules/salesforce_pull/src/PullQueueItem.php +++ b/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; } } diff --git a/modules/salesforce_pull/src/QueueHandler.php b/modules/salesforce_pull/src/QueueHandler.php index e055dd79..67a2bde6 100644 --- a/modules/salesforce_pull/src/QueueHandler.php +++ b/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)); diff --git a/modules/salesforce_pull/tests/src/Unit/PullBaseTest.php b/modules/salesforce_pull/tests/src/Unit/PullBaseTest.php index 076dc04b..64ccfcf8 100644 --- a/modules/salesforce_pull/tests/src/Unit/PullBaseTest.php +++ b/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); diff --git a/modules/salesforce_pull/tests/src/Unit/PullQueueItemTest.php b/modules/salesforce_pull/tests/src/Unit/PullQueueItemTest.php index 171960b9..9d5b82df 100644 --- a/modules/salesforce_pull/tests/src/Unit/PullQueueItemTest.php +++ b/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); } } diff --git a/modules/salesforce_pull/tests/src/Unit/QueueHandlerTest.php b/modules/salesforce_pull/tests/src/Unit/QueueHandlerTest.php index 974ebf81..ae82d8ed 100644 --- a/modules/salesforce_pull/tests/src/Unit/QueueHandlerTest.php +++ b/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') -- GitLab