diff --git a/package_manager/package_manager.module b/package_manager/package_manager.module
index fc0c624c2659da65754818e6276f73efb8c79a10..2e6eab24d6dfe2d97d1715ac3f14c1c78a50ef10 100644
--- a/package_manager/package_manager.module
+++ b/package_manager/package_manager.module
@@ -26,7 +26,15 @@ function package_manager_help($route_name, RouteMatchInterface $route_match) {
$output .= '<ul>';
$output .= ' <li>' . t("The Drupal application's codebase must be writable in order to use Automatic Updates. This includes Drupal core, modules, themes and the Composer dependencies in the <code>vendor</code> directory. This makes Automatic Updates incompatible with some hosting platforms.") . '</li>';
$output .= ' <li>' . t('Package Manager requires a Composer executable whose version satisfies <code>@version</code>, and PHP must have permission to run it. The path to the executable may be stored in config, or it will be automatically detected. To set the path to Composer, you can add the following line to settings.php:', ['@version' => ComposerInspector::SUPPORTED_VERSION]) . '</li>';
- $output .= '</ul>';
+ $output .= ' <li>' . t("Your Drupal site's <code>composer.json</code> file must be valid according to <code>composer validate</code>. See <a href=\":url\">Composer's documentation</a> for more information.", [':url' => 'https://getcomposer.org/doc/03-cli.md#validate']) . '</li>';
+ $output .= ' <li>' . t('Composer must be configured for secure downloads. This means that <a href=":disable-tls">the <code>disable-tls</code> option</a> must be <code>false</code>, and <a href=":secure-http">the <code>secure-http</code> option</a> must be <code>true</code> in the <code>config</code> section of your <code>composer.json</code> file. If these options are not set in your <code>composer.json</code>, Composer will behave securely by default. To set these values at the command line, run the following commands:', [
+ ':disable-tls' => 'https://getcomposer.org/doc/06-config.md#disable-tls',
+ ':secure-http' => 'https://getcomposer.org/doc/06-config.md#secure-http',
+ ]);
+ $output .= '<pre><code>';
+ $output .= "composer config --unset disable-tls\n";
+ $output .= "composer config --unset secure-http\n";
+ $output .= '</code></pre></li></ul>';
$output .= '<h3 id="package-manager-limitations">' . t('Limitations') . '</h3>';
$output .= '<p>' . t("Because Package Manager modifies the current site's code base, it is intentionally limited in certain ways to prevent unexpected changes to the live site:") . '</p>';
diff --git a/package_manager/src/Validator/ComposerValidator.php b/package_manager/src/Validator/ComposerValidator.php
index 8c17867976a1ea4cb0f9062c1b38c2e510d43401..cb16c27cc71941061cbcfcf5fb821a5ed0ec34e2 100644
--- a/package_manager/src/Validator/ComposerValidator.php
+++ b/package_manager/src/Validator/ComposerValidator.php
@@ -54,14 +54,13 @@ class ComposerValidator implements EventSubscriberInterface {
$this->composerInspector->validate($dir);
}
catch (\Throwable $e) {
+ // @todo There are other reasons this exception could have happened
+ // besides Composer not being found. Explain those reasons in our online
+ // help, and update this link, in https://drupal.org/i/3357657.
if ($this->moduleHandler->moduleExists('help')) {
- $url = Url::fromRoute('help.page', ['name' => 'package_manager'])
- ->setOption('fragment', 'package-manager-faq-composer-not-found')
- ->toString();
-
$message = $this->t('@message See <a href=":package-manager-help">the help page</a> for information on how to configure the path to Composer.', [
'@message' => $e->getMessage(),
- ':package-manager-help' => $url,
+ ':package-manager-help' => self::getHelpUrl('package-manager-faq-composer-not-found'),
]);
$event->addError([$message]);
}
@@ -87,15 +86,41 @@ class ComposerValidator implements EventSubscriberInterface {
// If disable-tls is enabled, it overrides secure-http and sets its value to
// FALSE, even if secure-http is set to TRUE explicitly.
if ($settings['disable-tls'] === TRUE) {
- $messages[] = $this->t('TLS must be enabled for HTTPS Composer downloads. See <a href=":url">the Composer documentation</a> for more information.', [
- ':url' => 'https://getcomposer.org/doc/06-config.md#disable-tls',
- ]);
+ $message = $this->t('TLS must be enabled for HTTPS Composer downloads.');
+
+ // If the Help module is installed, link to our help page, which displays
+ // the commands for configuring Composer correctly. Otherwise, direct
+ // users straight to the Composer documentation, which is a little less
+ // helpful.
+ if ($this->moduleHandler->moduleExists('help')) {
+ $messages[] = $this->t('@message See <a href=":url">the help page</a> for more information on how to configure Composer to download packages securely.', [
+ '@message' => $message,
+ ':url' => self::getHelpUrl('package-manager-requirements'),
+ ]);
+ }
+ else {
+ $messages[] = $this->t('@message See <a href=":url">the Composer documentation</a> for more information.', [
+ '@message' => $message,
+ ':url' => 'https://getcomposer.org/doc/06-config.md#disable-tls',
+ ]);
+ }
$messages[] = $this->t('You should also check the value of <code>secure-http</code> and make sure that it is set to <code>true</code> or not set at all.');
}
elseif ($settings['secure-http'] !== TRUE) {
- $messages[] = $this->t('HTTPS must be enabled for Composer downloads. See <a href=":url">the Composer documentation</a> for more information.', [
- ':url' => 'https://getcomposer.org/doc/06-config.md#secure-http',
- ]);
+ $message = $this->t('HTTPS must be enabled for Composer downloads.');
+
+ if ($this->moduleHandler->moduleExists('help')) {
+ $messages[] = $this->t('@message See <a href=":url">the help page</a> for more information on how to configure Composer to download packages securely.', [
+ '@message' => $message,
+ ':url' => self::getHelpUrl('package-manager-requirements'),
+ ]);
+ }
+ else {
+ $messages[] = $this->t('@message See <a href=":url">the Composer documentation</a> for more information.', [
+ '@message' => $message,
+ ':url' => 'https://getcomposer.org/doc/06-config.md#secure-http',
+ ]);
+ }
}
if ($messages) {
@@ -103,4 +128,19 @@ class ComposerValidator implements EventSubscriberInterface {
}
}
+ /**
+ * Returns a URL to a specific fragment of Package Manager's online help.
+ *
+ * @param string $fragment
+ * The fragment to link to.
+ *
+ * @return string
+ * A URL to Package Manager's online help.
+ */
+ private static function getHelpUrl(string $fragment): string {
+ return Url::fromRoute('help.page', ['name' => 'package_manager'])
+ ->setOption('fragment', $fragment)
+ ->toString();
+ }
+
}
diff --git a/package_manager/tests/src/Kernel/ComposerValidatorTest.php b/package_manager/tests/src/Kernel/ComposerValidatorTest.php
index f008de987f44b0defaa05182c922a24f2040f501..df41794a2ebddf89a86e2f43963ca4e4c6b67fb7 100644
--- a/package_manager/tests/src/Kernel/ComposerValidatorTest.php
+++ b/package_manager/tests/src/Kernel/ComposerValidatorTest.php
@@ -118,6 +118,48 @@ class ComposerValidatorTest extends PackageManagerKernelTestBase {
$this->assertResults($expected_results, PreApplyEvent::class);
}
+ /**
+ * Data provider for ::testLinkToOnlineHelp().
+ *
+ * @return array[]
+ * The test cases.
+ */
+ public function providerLinkToOnlineHelp(): array {
+ return [
+ 'TLS disabled' => [
+ ['disable-tls' => TRUE],
+ [
+ t('TLS must be enabled for HTTPS Composer downloads. See <a href="/admin/help/package_manager#package-manager-requirements">the help page</a> for more information on how to configure Composer to download packages securely.'),
+ t('You should also check the value of <code>secure-http</code> and make sure that it is set to <code>true</code> or not set at all.'),
+ ],
+ ],
+ 'secure-http is off' => [
+ ['secure-http' => FALSE],
+ [
+ t('HTTPS must be enabled for Composer downloads. See <a href="/admin/help/package_manager#package-manager-requirements">the help page</a> for more information on how to configure Composer to download packages securely.'),
+ ],
+ ],
+ ];
+ }
+
+ /**
+ * Tests that invalid configuration links to online help, if available.
+ *
+ * @param array $config
+ * The Composer configuration to set.
+ * @param \Drupal\Core\StringTranslation\TranslatableMarkup[] $expected_messages
+ * The expected validation error messages.
+ *
+ * @dataProvider providerLinkToOnlineHelp
+ */
+ public function testLinkToOnlineHelp(array $config, array $expected_messages): void {
+ $this->enableModules(['help']);
+ (new ActiveFixtureManipulator())->addConfig($config)->commitChanges();
+
+ $result = ValidationResult::createError($expected_messages, t("Composer settings don't satisfy Package Manager's requirements."));
+ $this->assertStatusCheckResults([$result]);
+ }
+
/**
* {@inheritdoc}
*/