Update to Drupal 8.1.0. For more information, see https://www.drupal.org/drupal-8.1.0-release-notes

core/modules/tour/src/Annotation/Tip.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\Annotation\Tip.
- */
-
 namespace Drupal\tour\Annotation;
 
 use Drupal\Component\Annotation\Plugin;

core/modules/tour/src/Entity/Tour.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\Entity\Tour.
- */
-
 namespace Drupal\tour\Entity;
 
 use Drupal\Core\Config\Entity\ConfigEntityBase;

core/modules/tour/src/Plugin/HelpSection/TourHelpSection.php

@@ -0,0 +1,132 @@
+<?php
+
+namespace Drupal\tour\Plugin\HelpSection;
+
+use Drupal\Core\Entity\EntityTypeManagerInterface;
+use Drupal\Core\Link;
+use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
+use Drupal\Core\Url;
+use Drupal\help\Plugin\HelpSection\HelpSectionPluginBase;
+use Symfony\Component\DependencyInjection\ContainerInterface;
+
+/**
+ * Provides the tours list section for the help page.
+ *
+ * @HelpSection(
+ *   id = "tour",
+ *   title = @Translation("Tours"),
+ *   description = @Translation("Tours guide you through workflows or explain concepts on various user interface pages. The tours with links in this list are on user interface landing pages; the tours without links will show on individual pages (such as when editing a View using the Views UI module). Available tours:"),
+ *   permission = "access tour"
+ * )
+ */
+class TourHelpSection extends HelpSectionPluginBase implements ContainerFactoryPluginInterface {
+
+  /**
+   * The entity type manager.
+   *
+   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
+   */
+  protected $entityTypeManager;
+
+  /**
+   * Constructs a TourHelpSection object.
+   *
+   * @param array $configuration
+   *   A configuration array containing information about the plugin instance.
+   * @param string $plugin_id
+   *   The plugin_id for the plugin instance.
+   * @param mixed $plugin_definition
+   *   The plugin implementation definition.
+   * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
+   *   The entity manager service.
+   */
+  public function __construct(array $configuration, $plugin_id, $plugin_definition, EntityTypeManagerInterface $entity_type_manager) {
+    parent::__construct($configuration, $plugin_id, $plugin_definition);
+    $this->entityTypeManager = $entity_type_manager;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
+    return new static(
+      $configuration,
+      $plugin_id,
+      $plugin_definition,
+      $container->get('entity_type.manager')
+    );
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getCacheMaxAge() {
+    // The calculation of which URL (if any) gets put on which tour depends
+    // on a route access check. This can have a lot of inputs, including user
+    // permissions and other factors. Rather than doing a complicated
+    // accounting of the cache metadata for all of these possible factors, set
+    // the max age of the cache to zero to prevent using incorrect cached
+    // information.
+    return 0;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function listTopics() {
+    /** @var \Drupal\tour\TourInterface[] $tours */
+    $tours = $this->entityTypeManager->getStorage('tour')->loadMultiple();
+    // Sort in the manner defined by Tour.
+    uasort($tours, ['Drupal\tour\Entity\Tour', 'sort']);
+
+    // Make a link to each tour, using the first of its routes that can
+    // be linked to by this user, if any.
+    $topics = [];
+    foreach ($tours as $tour) {
+      $title = $tour->label();
+      $id = $tour->id();
+      $routes = $tour->getRoutes();
+      $made_link = FALSE;
+      foreach ($routes as $route) {
+        // Some tours are for routes with parameters. For instance, there is
+        // currently a tour in the Language module for the language edit page,
+        // which appears on all pages with URLs like:
+        // /admin/config/regional/language/edit/LANGCODE.
+        // There is no way to make a link to the page that displays the tour,
+        // because it is a set of pages. The easiest way to detect this is to
+        // use a try/catch exception -- try to make a link, and it will error
+        // out with a missing parameter exception if the route leads to a set
+        // of pages instead of a single page.
+        try {
+          $params = isset($route['route_params']) ? $route['route_params'] : [];
+          $url = Url::fromRoute($route['route_name'], $params);
+          // Skip this route if the current user cannot access it.
+          if (!$url->access()) {
+            continue;
+          }
+
+          // Generate the link HTML directly, using toString(), to catch
+          // missing parameter exceptions now instead of at render time.
+          $topics[$id] = Link::fromTextAndUrl($title, $url)->toString();
+          // If the line above didn't generate an exception, we have a good
+          // link that the user can access.
+          $made_link = TRUE;
+          break;
+        }
+        catch (\Exception $e) {
+          // Exceptions are normally due to routes that need parameters. If
+          // there is an exception, just try the next route and see if we can
+          // find one that will work for us.
+        }
+      }
+      if (!$made_link) {
+        // None of the routes worked to make a link, so at least display the
+        // tour title.
+        $topics[$id] = $title;
+      }
+    }
+
+    return $topics;
+  }
+
+}

core/modules/tour/src/Plugin/tour/tip/TipPluginText.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\Plugin\tour\tip\TipPluginText.
- */
-
 namespace Drupal\tour\Plugin\tour\tip;
 
 use Drupal\Component\Utility\Html;

core/modules/tour/src/Tests/TourCacheTagsTest.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\Tests\TourCacheTagsTest.
- */
-
 namespace Drupal\tour\Tests;
 
 use Drupal\Core\Url;

core/modules/tour/src/Tests/TourHelpPageTest.php

@@ -0,0 +1,141 @@
+<?php
+
+namespace Drupal\tour\Tests;
+
+use Drupal\simpletest\WebTestBase;
+
+/**
+ * Verifies help page display of tours.
+ *
+ * @group help
+ */
+class TourHelpPageTest extends WebTestBase {
+
+  /**
+   * Modules to enable, including some providing tours.
+   *
+   * @var array
+   */
+  public static $modules = ['help', 'tour', 'locale', 'language'];
+
+  /**
+   * User that can access tours and help.
+   *
+   * @var \Drupal\user\UserInterface
+   */
+  protected $tourUser;
+
+  /**
+   * A user who can access help but not tours.
+   *
+   * @var \Drupal\user\UserInterface
+   */
+  protected $noTourUser;
+
+  /**
+   * {@inheritdoc}
+   */
+  protected function setUp() {
+    parent::setUp();
+
+    // Create users. For the Tour user, include permissions for the language
+    // tours' parent pages, but not the translation tour's parent page. See
+    // self:getTourList().
+    $this->tourUser = $this->drupalCreateUser(['access administration pages', 'access tour', 'administer languages']);
+    $this->noTourUser = $this->drupalCreateUser(['access administration pages']);
+  }
+
+  /**
+   * Logs in users, tests help pages.
+   */
+  public function testHelp() {
+    $this->drupalLogin($this->tourUser);
+    $this->verifyHelp();
+
+    $this->drupalLogin($this->noTourUser);
+    $this->verifyHelp(FALSE);
+  }
+
+  /**
+   * Verifies the logged in user has access to the help properly.
+   *
+   * @param bool $tours_ok
+   *   (optional) TRUE (default) if the user should see tours, FALSE if not.
+   */
+  protected function verifyHelp($tours_ok = TRUE) {
+    $this->drupalGet('admin/help');
+
+    // All users should be able to see the module section.
+    $this->assertText('Module overviews are provided by modules');
+    foreach ($this->getModuleList() as $name) {
+      $this->assertLink($name);
+    }
+
+    // Some users should be able to see the tour section.
+    if ($tours_ok) {
+      $this->assertText('Tours guide you through workflows');
+    }
+    else {
+      $this->assertNoText('Tours guide you through workflows');
+    }
+
+    $titles = $this->getTourList();
+
+    // Test the titles that should be links.
+    foreach ($titles[0] as $title) {
+      if ($tours_ok) {
+        $this->assertLink($title);
+      }
+      else {
+        $this->assertNoLink($title);
+        // Just test the first item in the list of links that should not
+        // be there, because the second matches the name of a module that is
+        // in the Module overviews section, so the link will be there and
+        // this test will fail. Testing one should be sufficient to verify
+        // the page is working correctly.
+        break;
+      }
+    }
+
+    // Test the titles that should not be links.
+    foreach ($titles[1] as $title) {
+      if ($tours_ok) {
+        $this->assertText($title);
+        $this->assertNoLink($title);
+      }
+      else {
+        $this->assertNoText($title);
+        // Just test the first item in the list of text that should not
+        // be there, because the second matches part of the name of a module
+        // that is in the Module overviews section, so the text will be there
+        // and this test will fail. Testing one should be sufficient to verify
+        // the page is working correctly.
+        break;
+      }
+    }
+  }
+
+  /**
+   * Gets a list of modules to test for hook_help() pages.
+   *
+   * @return array
+   *   A list of module names to test.
+   */
+  protected function getModuleList() {
+    return ['Help', 'Tour'];
+  }
+
+  /**
+   * Gets a list of tours to test.
+   *
+   * @return array
+   *   A list of tour titles to test. The first array element is a list of tours
+   *   with links, and the second is a list of tours without links. Assumes
+   *   that the user being tested has 'administer languages' permission but
+   *   not 'translate interface'.
+   */
+  protected function getTourList() {
+    return [['Adding languages', 'Language'], ['Editing languages', 'Translation']];
+  }
+
+}

core/modules/tour/src/Tests/TourPluginTest.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\Tests\TourPluginTest.
- */
-
 namespace Drupal\tour\Tests;
 
 use Drupal\simpletest\KernelTestBase;

core/modules/tour/src/Tests/TourTest.php

@@ -1,13 +1,9 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\Tests\TourTest.
- */
-
 namespace Drupal\tour\Tests;
 
 use Drupal\language\Entity\ConfigurableLanguage;
+use Drupal\tour\Entity\Tour;
 
 /**
  * Tests the functionality of tour tips.
@@ -108,7 +104,7 @@ class TourTest extends TourTestBasic {
     $this->assertNotEqual(count($elements), 1, 'Did not find English variant of tip 1.');
 
     // Programmatically create a tour for use through the remainder of the test.
-    $tour = entity_create('tour', array(
+    $tour = Tour::create(array(
       'id' => 'tour-entity-create-test-en',
       'label' => 'Tour test english',
       'langcode' => 'en',

core/modules/tour/src/Tests/TourTestBase.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\Tests\TourTestBase.
- */
-
 namespace Drupal\tour\Tests;
 
 use Drupal\simpletest\WebTestBase;

core/modules/tour/src/Tests/TourTestBasic.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\Tests\TourTestBasic.
- */
-
 namespace Drupal\tour\Tests;
 
 /**

core/modules/tour/src/TipPluginBase.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\TipPluginBase.
- */
-
 namespace Drupal\tour;
 
 use Drupal\Core\Plugin\PluginBase;

core/modules/tour/src/TipPluginInterface.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\TipPluginInterface.
- */
-
 namespace Drupal\tour;
 
 /**

core/modules/tour/src/TipPluginManager.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\TipPluginManager.
- */
-
 namespace Drupal\tour;
 
 use Drupal\Core\Cache\CacheBackendInterface;

core/modules/tour/src/TipsPluginCollection.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\TipsPluginCollection.
- */
-
 namespace Drupal\tour;
 
 use Drupal\Core\Plugin\DefaultLazyPluginCollection;

core/modules/tour/src/TourInterface.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\TourInterface.
- */
-
 namespace Drupal\tour;
 
 use Drupal\Core\Config\Entity\ConfigEntityInterface;

core/modules/tour/src/TourViewBuilder.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour\TourViewBuilder.
- */
-
 namespace Drupal\tour;
 
 use Drupal\Core\Entity\EntityViewBuilder;

core/modules/tour/tests/src/Unit/Entity/TourTest.php

@@ -1,8 +1,4 @@
 <?php
-/**
- * @file
- * Contains \Drupal\Tests\tour\Unit\Entity\TourTest.
- */
 
 namespace Drupal\Tests\tour\Unit\Entity;
 

core/modules/tour/tests/tour_test/src/Controller/TourTestController.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour_test\Controller\TourTestController.
- */
-
 namespace Drupal\tour_test\Controller;
 
 /**
@@ -16,7 +11,7 @@ class TourTestController {
    * Outputs some content for testing tours.
    *
    * @param string $locale
-   *  (optional) Dummy locale variable for testing routing parameters. Defaults
+   *   (optional) Dummy locale variable for testing routing parameters. Defaults
    *   to 'foo'.
    *
    * @return array

core/modules/tour/tests/tour_test/src/Plugin/tour/tip/TipPluginImage.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\tour_test\Plugin\tour\tip\TipPluginImage.
- */
-
 namespace Drupal\tour_test\Plugin\tour\tip;
 
 use Drupal\Component\Utility\Html;