Commit 78fa4dd7 authored by gbyte.co's avatar gbyte.co

Clean up and add code documentation

parent 9f0d6b44
......@@ -11,7 +11,8 @@
## INTRODUCTION ##
Author and maintainer: Pawel Ginalski (gbyte.co)
https://www.drupal.org/u/gbyte.co
* Drupal: https://www.drupal.org/u/gbyte.co
* Personal: https://gbyte.co/
The module generates multilingual XML sitemaps which adhere to Google's new
hreflang standard. Out of the box the sitemaps index most of Drupal's
......@@ -166,6 +167,9 @@ $generator
->generateSitemap();
```
See https://gbyte.co/projects/simple-xml-sitemap and code documentation in
Drupal\simple_sitemap\Simplesitemap for further details.
### API HOOKS ###
It is possible to hook into link generation by implementing
......@@ -219,9 +223,11 @@ the settings array of the new generator plugin's annotation. See how the
EntityUrlGenerator is overwritten by the EntityMenuLinkContentUrlGenerator to
facilitate a different logic for menu links.
See https://gbyte.co/projects/simple-xml-sitemap for further details.
## HOW CAN YOU CONTRIBUTE? ##
* Report any bugs, feature or support requests in the issue tracker, if
* Report any bugs, feature or support requests in the issue tracker; if
possible help out by submitting patches.
http://drupal.org/project/issues/simple_sitemap
......@@ -231,6 +237,8 @@ facilitate a different logic for menu links.
* If you would like to say thanks and support the development of this module, a
donation will be much appreciated.
https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5AFYRSBLGSC3W
* Feel free to contact me for paid support: https://gbyte.co/contact
## MAINTAINERS ##
......
......@@ -42,7 +42,6 @@ services:
- '@state'
- '@module_handler'
- '@simple_sitemap.queue'
- '@lock'
simple_sitemap.queue:
class: Drupal\simple_sitemap\Queue\SimplesitemapQueue
......
......@@ -101,8 +101,10 @@ class EntityHelper {
}
/**
* @param $url_object
* @return object|null
* @param \Drupal\Core\Url $url_object
* @return \Drupal\Core\Entity\EntityInterface|null
* @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
* @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
*/
public function getEntityFromUrlObject(Url $url_object) {
return $url_object->isRouted()
......@@ -140,8 +142,8 @@ class EntityHelper {
}
/**
* @param $entity_type_name
* @param $entity_id
* @param string $entity_type_name
* @param string $entity_id
* @return array
*/
public function getEntityImageUrls($entity_type_name, $entity_id) {
......
......@@ -12,6 +12,7 @@ use Drupal\simple_sitemap\Simplesitemap;
use Drupal\Core\Language\LanguageManagerInterface;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\Language\Language;
use Drupal\Core\Session\AnonymousUserSession;
/**
* Class UrlGeneratorBase
......@@ -19,8 +20,6 @@ use Drupal\Core\Language\Language;
*/
abstract class UrlGeneratorBase extends SimplesitemapPluginBase implements UrlGeneratorInterface {
const ANONYMOUS_USER_ID = 0;
/**
* @var \Drupal\simple_sitemap\Simplesitemap
*/
......@@ -76,8 +75,6 @@ abstract class UrlGeneratorBase extends SimplesitemapPluginBase implements UrlGe
* @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
* @param \Drupal\simple_sitemap\Logger $logger
* @param \Drupal\simple_sitemap\EntityHelper $entityHelper
* @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
* @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
*/
public function __construct(
array $configuration,
......@@ -94,8 +91,7 @@ abstract class UrlGeneratorBase extends SimplesitemapPluginBase implements UrlGe
$this->languages = $language_manager->getLanguages();
$this->defaultLanguageId = $language_manager->getDefaultLanguage()->getId();
$this->entityTypeManager = $entity_type_manager;
$this->anonUser = $this->entityTypeManager->getStorage('user')
->load(self::ANONYMOUS_USER_ID);
$this->anonUser = new AnonymousUserSession();
$this->logger = $logger;
$this->entityHelper = $entityHelper;
}
......
......@@ -17,10 +17,8 @@ trait BatchTrait {
/**
* @param string $from
* @param null $variants
* @param array|null $variants
* @return bool
*
* @todo Implement generating for certain variants only.
*/
public function batchGenerateSitemap($from = 'form', $variants = NULL) {
$this->batch = [
......@@ -56,6 +54,7 @@ trait BatchTrait {
/**
* @param $context
* @throws \Drupal\Component\Plugin\Exception\PluginException
*
* @todo Make sure batch does not run at the same time as cron.
* @todo Variants into generateSitemap().
......
......@@ -8,7 +8,6 @@ use Drupal\simple_sitemap\SimplesitemapSettings;
use Drupal\Core\Extension\ModuleHandler;
use Drupal\simple_sitemap\SimplesitemapManager;
use Drupal\Core\State\State;
use Drupal\Core\Lock\LockBackendInterface;
class QueueWorker {
......@@ -37,11 +36,6 @@ class QueueWorker {
*/
protected $moduleHandler;
/**
* @var \Drupal\Core\ProxyClass\Lock\DatabaseLockBackend
*/
protected $lock;
/**
* @var \Drupal\simple_sitemap\Queue\SimplesitemapQueue
*/
......@@ -94,20 +88,17 @@ class QueueWorker {
* @param \Drupal\Core\State\State $state
* @param \Drupal\Core\Extension\ModuleHandler $module_handler
* @param \Drupal\simple_sitemap\Queue\SimplesitemapQueue $element_queue
* @param \Drupal\Core\Lock\LockBackendInterface $lock
*/
public function __construct(SimplesitemapSettings $settings,
SimplesitemapManager $manager,
State $state,
ModuleHandler $module_handler,
SimplesitemapQueue $element_queue,
LockBackendInterface $lock) {
SimplesitemapQueue $element_queue) {
$this->settings = $settings;
$this->manager = $manager;
$this->state = $state;
$this->moduleHandler = $module_handler;
$this->queue = $element_queue;
$this->lock = $lock;
}
/**
......@@ -129,11 +120,9 @@ class QueueWorker {
}
/**
* @param null $variants
* @param array|null $variants
* @return $this
* @throws \Drupal\Component\Plugin\Exception\PluginException
*
* @todo Lock functionality
*/
public function rebuildQueue($variants = NULL) {
$all_data_sets = [];
......@@ -199,9 +188,6 @@ class QueueWorker {
* @param string $from
* @return $this
* @throws \Drupal\Component\Plugin\Exception\PluginException
*
* @todo Lock functionality
* @todo Does not unpublish sitemaps were variant does not have links anymore.
*/
public function generateSitemap($from = 'form') {
......@@ -266,6 +252,10 @@ class QueueWorker {
return $this;
}
/**
* @param $element
* @throws \Drupal\Component\Plugin\Exception\PluginException
*/
protected function generateResultsFromElement($element) {
$results = $this->manager->getUrlGenerator($element->data['url_generator'])
->setSitemapVariant($this->variantProcessedNow)
......@@ -276,6 +266,9 @@ class QueueWorker {
$this->results = array_merge($this->results, $results);
}
/**
* @param array $results
*/
protected function removeDuplicates(&$results) {
if ($this->generatorSettings['remove_duplicates']
&& !empty($results)
......@@ -289,6 +282,10 @@ class QueueWorker {
}
}
/**
* @param bool $complete
* @throws \Drupal\Component\Plugin\Exception\PluginException
*/
protected function generateVariantChunksFromResults($complete = FALSE) {
if (!empty($this->results)) {
$generator = $this->manager->getSitemapGenerator($this->generatorProcessedNow)
......@@ -351,6 +348,10 @@ class QueueWorker {
return $this->elementsTotal;
}
/**
* @param bool $force_recount
* @return int
*/
public function getQueuedElementCount($force_recount = FALSE) {
if ($force_recount || NULL === $this->elementsRemaining) {
$this->elementsRemaining = $this->queue->numberOfItems();
......@@ -359,10 +360,16 @@ class QueueWorker {
return $this->elementsRemaining;
}
/**
* @return int
*/
public function getStashedResultCount() {
return count($this->state->get('simple_sitemap.queue_stashed_results', ['results' => []])['results']);
}
/**
* @return int
*/
public function getProcessedElementCount() {
$initial = $this->getInitialElementCount();
$remaining = $this->getQueuedElementCount();
......@@ -370,6 +377,9 @@ class QueueWorker {
return $initial > $remaining ? ($initial - $remaining) : 0;
}
/**
* @return bool
*/
public function generationInProgress() {
return 0 < ($this->getQueuedElementCount() + $this->getStashedResultCount());
}
......
......@@ -167,6 +167,7 @@ class Simplesitemap {
*
* @param string $name
* Setting name, like 'max_links'.
*
* @param mixed $setting
* The setting to be saved.
*
......@@ -216,7 +217,12 @@ class Simplesitemap {
}
/**
* Gets the currently set variants, the default variant, or all variants.
*
* @param bool $default_get_all
* If true and no variants are set, all variants are returned. If false and
* no variants are set, only the default variant is returned.
*
* @return array
*/
protected function getVariants($default_get_all = TRUE) {
......@@ -268,7 +274,8 @@ class Simplesitemap {
*
* @return array
* An array containing all published sitemap chunk IDs, deltas and creation
* timestamps keyed by their variant ID.
* timestamps keyed by the currently set variants, or in case of only one
* variant set the above keyed by sitemap delta.
*/
protected function fetchSitemapVariantInfo() {
$result = $this->db->select('simple_sitemap', 's')
......@@ -297,6 +304,8 @@ class Simplesitemap {
}
/**
* Removes sitemap instances for the currently set variants.
*
* @return $this
* @throws \Drupal\Component\Plugin\Exception\PluginException
*/
......@@ -307,11 +316,17 @@ class Simplesitemap {
}
/**
* Generates all sitemaps.
*
* @param string $from
* Can be 'form', 'drush', 'cron' and 'backend'.
*
* @return $this
*
* @throws \Drupal\Component\Plugin\Exception\PluginException
*
* @todo variants
* @todo Respect $this->variants and generate for specific variants.
* @todo Implement lock functionality.
*/
public function generateSitemap($from = 'form') {
switch($from) {
......@@ -329,6 +344,12 @@ class Simplesitemap {
return $this;
}
/**
* Rebuilds the queue for the currently set variants.
*
* @return $this
* @throws \Drupal\Component\Plugin\Exception\PluginException
*/
public function rebuildQueue() {
$this->queueWorker->rebuildQueue($this->getVariants());
......@@ -342,17 +363,15 @@ class Simplesitemap {
*
* @return string|array|false
* Formatted timestamp of last sitemap generation, otherwise FALSE.
*
* @todo: variants
*/
public function getGeneratedAgo() {
/* public function getGeneratedAgo() {
$chunks = $this->fetchSitemapVariantInfo();
return isset($chunks[DefaultSitemapGenerator::FIRST_CHUNK_DELTA]->sitemap_created)
? $this->dateFormatter
->formatInterval($this->time->getRequestTime() - $chunks[DefaultSitemapGenerator::FIRST_CHUNK_DELTA]
->sitemap_created)
: FALSE;
}
}*/
/**
* Enables sitemap support for an entity type. Enabled entity types show
......@@ -380,7 +399,6 @@ class Simplesitemap {
* settings from entity forms.
*
* @param string $entity_type_id
* Entity type id like 'node'.
*
* @return $this
*/
......@@ -409,19 +427,18 @@ class Simplesitemap {
}
/**
* Sets sitemap settings for a non-bundle entity type (e.g. user) or a bundle
* of an entity type (e.g. page).
* Sets settings for bundle or non-bundle entity types. This is done for the
* currently set variant.
*
* @param string $entity_type_id
* Entity type id like 'node' the bundle belongs to.
* @param string $bundle_name
* Name of the bundle. NULL if entity type has no bundles.
* @param $entity_type_id
* @param null $bundle_name
* @param array $settings
* An array of sitemap settings for this bundle/entity type.
* Example: ['index' => TRUE, 'priority' => 0.5, 'changefreq' => 'never', 'include_images' => FALSE].
*
* @return $this
*
* @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
* @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
*
* @todo: enableEntityType automatically
* @todo multiple variants
*/
......@@ -482,18 +499,18 @@ class Simplesitemap {
}
/**
* Gets sitemap settings for an entity bundle, a non-bundle entity type or for
* all entity types and their bundles.
* Gets settings for bundle or non-bundle entity types. This is done for the
* currently set variants.
*
* @param string|null $entity_type_id
* If set to null, sitemap settings for all entity types and their bundles
* are fetched.
* Limit the result set to a specific entity type.
*
* @param string|null $bundle_name
* Limit the result set to a specific bundle name.
*
* @return array|false
* Array of sitemap settings for an entity bundle, a non-bundle entity type
* or for all entity types and their bundles.
* False if entity type does not exist.
* Array of settings or array of settings keyed by variant name. False if
* entity type does not exist.
*/
public function getBundleSettings($entity_type_id = NULL, $bundle_name = NULL, $supplement_defaults = TRUE, $multiple_variants = FALSE) {
......@@ -553,9 +570,19 @@ class Simplesitemap {
}
/**
* Removes settings for bundle or a non-bundle entity types. This is done for
* the currently set variants.
*
* @param string|null $entity_type_id
* Limit the removal to a specific entity type.
*
* @param string|null $bundle_name
* Limit the removal to a specific bundle name.
*
* @return $this
*
* @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
* @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
*/
public function removeBundleSettings($entity_type_id = NULL, $bundle_name = NULL) {
if (empty($variants = $this->getVariants(FALSE))) {
......@@ -593,7 +620,8 @@ class Simplesitemap {
* Supplements all missing link setting with default values.
*
* @param string $type
* 'entity'|'custom'
* Can be 'entity' or 'custom'.
*
* @param array &$settings
* @param array $overrides
*/
......@@ -609,13 +637,17 @@ class Simplesitemap {
}
/**
* Overrides entity bundle/entity type sitemap settings for a single entity.
* Overrides sitemap settings for a single entity for the currently set
* variants.
*
* @param string $entity_type_id
* @param int $id
* @param string $id
* @param array $settings
*
* @return $this
*
* @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
* @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
*/
public function setEntityInstanceSettings($entity_type_id, $id, $settings) {
if (empty($variants = $this->getVariants(FALSE))) {
......@@ -665,13 +697,19 @@ class Simplesitemap {
}
/**
* Gets sitemap settings for an entity instance which overrides the sitemap
* settings of its bundle, or bundle settings, if they are not overridden.
* Gets sitemap settings for an entity instance which overrides bundle
* settings, or gets bundle settings, if they are not overridden. This is
* done for the currently set variant.
*
* @param string $entity_type_id
* @param int $id
* @param string $id
*
* @return array|false
* Array of entity instance settings or the settings of its bundle. False if
* entity type does not exist.
*
* @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
* @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
*
* @todo multiple variants
*/
......@@ -702,11 +740,14 @@ class Simplesitemap {
}
/**
* Removes sitemap settings for an entity that overrides the sitemap settings
* of its bundle.
* Removes sitemap settings for entities that override bundle settings. This
* is done for the currently set variants.
*
* @param string|null $entity_type_id
* Limits the removal to a certain entity type.
*
* @param string $entity_type_id
* @param string|null $entity_ids
* Limits the removal to entities with certain IDs.
*
* @return $this
*/
......@@ -733,12 +774,14 @@ class Simplesitemap {
/**
* Checks if an entity bundle (or a non-bundle entity type) is set to be
* indexed in the sitemap settings.
* indexed for the currently set variant.
*
* @param string $entity_type_id
* @param string|null $bundle_name
*
* @return bool
*
* @todo multiple variants?
*/
public function bundleIsIndexed($entity_type_id, $bundle_name = NULL) {
$settings = $this->getBundleSettings($entity_type_id, $bundle_name);
......@@ -757,10 +800,13 @@ class Simplesitemap {
}
/**
* Stores a custom path along with its sitemap settings to configuration.
* Stores a custom path along with its settings to configuration for the
* currently set variants.
*
* @param string $path
*
* @param array $settings
* Settings that are not provided are supplemented by defaults.
*
* @return $this
*
......@@ -804,10 +850,19 @@ class Simplesitemap {
}
/**
* Returns an array of custom paths and their sitemap settings.
* Gets custom link settings for the currently set variants.
*
* @param string|null $path
* Limits the result set by an internal path.
*
* @param bool $supplement_defaults
* @return array
* Supplements the result set with default custom link settings.
*
* @param bool $multiple_variants
* If true, returns an array of results keyed by variant name, otherwise it
* returns the result set for the first variant only.
*
* @return array|mixed|null
*/
public function getCustomLinks($path = NULL, $supplement_defaults = TRUE, $multiple_variants = FALSE) {
$all_custom_links = [];
......@@ -852,7 +907,10 @@ class Simplesitemap {
}
/**
* Removes all custom paths from the sitemap settings.
* Removes custom links from currently set variants.
*
* @param array|null $paths
* Limits the removal to certain paths.
*
* @return $this
*/
......
......@@ -91,7 +91,7 @@ class SimplesitemapManager {
}
/**
* @param $sitemap_generator_id
* @param string $sitemap_generator_id
* @return \Drupal\simple_sitemap\Plugin\simple_sitemap\SitemapGenerator\SitemapGeneratorBase
* @throws \Drupal\Component\Plugin\Exception\PluginException
*/
......@@ -105,7 +105,7 @@ class SimplesitemapManager {
}
/**
* @param $url_generator_id
* @param string $url_generator_id
* @return \Drupal\simple_sitemap\Plugin\simple_sitemap\UrlGenerator\UrlGeneratorBase
* @throws \Drupal\Component\Plugin\Exception\PluginException
*/
......@@ -119,7 +119,7 @@ class SimplesitemapManager {
}
/**
* @return array
* @return \Drupal\simple_sitemap\Plugin\simple_sitemap\SitemapType\SitemapTypeBase[]
*/
public function getSitemapTypes() {
if (empty($this->sitemapTypes)) {
......@@ -130,10 +130,9 @@ class SimplesitemapManager {
}
/**
* @param null $sitemap_type
* @param string|null $sitemap_type
* @param bool $attach_type_info
* @return array
*
* @todo translate label
*/
public function getSitemapVariants($sitemap_type = NULL, $attach_type_info = TRUE) {
if (NULL === $sitemap_type) {
......@@ -154,16 +153,25 @@ class SimplesitemapManager {
return $variants;
}
/**
* @param array $variants
* @param string $type
* @return array
*/
protected function attachSitemapTypeToVariants(array $variants, $type) {
return array_map(function($variant) use ($type) { return $variant + ['type' => $type]; }, $variants);
}
/**
* @param array $variants
* @return array
*/
protected function detachSitemapTypeFromVariants(array $variants) {
return array_map(function($variant) { unset($variant['type']); return $variant; }, $variants);
}
/**
* @param $name
* @param string $name
* @param array $definition
* @return $this
* @throws \Drupal\Component\Plugin\Exception\PluginException
......@@ -210,10 +218,10 @@ class SimplesitemapManager {
/**
* @param null|array|string $variant_names
* null: Removes all sitemap instances
* string|array: Removes specific instances
* Limit removal by specific variants.
*
* @return $this
*
* @throws \Drupal\Component\Plugin\Exception\PluginException
*/
public function removeSitemap($variant_names = NULL) {
......@@ -238,10 +246,10 @@ class SimplesitemapManager {
/**
* @param null|array|string $variant_names
* null: Removes all sitemap variants
* string|array: Removes specific variants
* Limit removal by specific variants.
*
* @return $this
*
* @throws \Drupal\Component\Plugin\Exception\PluginException
*/
public function removeSitemapVariants($variant_names = NULL) {
......
......@@ -7,8 +7,6 @@ use Drupal\Core\Config\ConfigFactory;
/**
* Class SimplesitemapSettings
* @package Drupal\simple_sitemap
*
* @todo use this in other services instead of SimpleSitemap::get|setSetting
*/
class SimplesitemapSettings {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment