#191310 by JirkaRybka, keith.smith: ship with a files directory by default and...

#191310 by JirkaRybka, keith.smith: ship with a files directory by default and improve installation error messages checking for all requirements on the same screen, instead of putting the user through individual error screens

INSTALL.txt

@@ -62,15 +62,22 @@ INSTALLATION
    http://drupal.org/project/Translations and download the package. Extract
    the contents to the same directory where you extracted Drupal into.
 
-2. GIVE PERMISSION TO DRUPAL TO BE ABLE TO CREATE THE CONFIGURATION FILE
+2. GRANT WRITE PERMISSIONS ON CONFIGURATION FILE AND FILES STORAGE DIRECTORY
 
    Drupal comes with a default.settings.php file in the sites/default
    directory. The installer will create a copy of this file filled with
    the details you provide through the install process, in the same
-   directory. For Drupal to be able to create the file, you need to
-   give the web server write privileges to the sites/default directory:
+   directory. Give the web server write privileges to the sites/default
+   directory with the command (from the installation directory):
 
-     chmod o+w default
+     chmod o+w sites/default
+
+   Drupal requires the files directory be present and writable during
+   the installation (the location of the files directory can be changed
+   after Drupal is installed). Give the web server write privileges to the
+   files directory with the command (from the installation directory):
+
+     chmod o+w files
 
 3. CREATE THE DRUPAL DATABASE
 
@@ -115,13 +122,13 @@ INSTALLATION
    running FastCGI can run into problems if the $base_url variable is left
    commented out (see http://bugs.php.net/bug.php?id=19656).
 
-   Consider creating a "files" subdirectory in your Drupal installation
-   directory. This subdirectory stores files such as custom logos, user avatars,
-   and other media associated with your new site. The sub-directory requires
-   "read and write" permission by the Drupal server process. You can change
-   the name of this subdirectory at "administer > site configuration > file
-   system".
-
+   Determine whether the default "files" directory is the right location for your
+   file system path. Drupal uses the location specified in the file system path
+   to store files attached to site content, theme-specific logos, user avatars, and
+   some temporary files. On some installations, it may be necessary to modify
+   the file system path, especially in large or multi-site configurations. See the
+   files/README.txt file for more information about setting the file system path.
+   
 6. CRON TASKS
 
    Many Drupal modules (such as the search functionality) have periodic tasks
@@ -226,6 +233,9 @@ accessible to other sites, the setup would look like this:
 NOTE: for more information about multiple virtual hosts or the configuration
 settings, consult the Drupal handbook at drupal.org.
 
+For more information on configuring Drupal's file system path in a multi-site
+configuration, see files/README.txt.
+
 MORE INFORMATION
 ----------------
 

files/README.txt

+// $Id$
+
+The files directory is the default file system path used to store
+all uploaded files, as well as some temporary files created by Drupal. To
+successfully install Drupal, the files directory must exist and be
+writable by the web server process.
+
+After installation, the settings for the file system path may be modified
+to store uploaded files in a different location. Ensure that this new
+location exists, is accessible, and is writable by the web server process.
+The file system path settings can be accessed by selecting these menu items
+from the Navigation menu:
+
+  administer > site configuration > file system
+
+You may wish to modify the file system path if:
+
+  * your site runs multiple Drupal installations from a single codebase
+    (modify the file system path of each installation to a different
+    directory so that uploads do not overlap between installations);
+
+  * your site runs a number of web server front-ends behind a load
+    balancer or reverse proxy (modify the file system path on each
+    server to point to a shared file repository); or,
+
+  * your site policies specify that all site-related files are stored
+    under the sites directory in order to simplify backup and restore
+    operations (modify the file system path to point to a newly-created
+    directory underneath sites).
+
+Changing the file system path after files have been uploaded may cause
+unexpected problems on an existing site. If you modify the file system path
+on an existing site, remember to copy all files from the original location
+to the new location.

install.php

@@ -91,12 +91,19 @@ function install_main() {
   // Tasks come after the database is set up
   if (!$task) {
     // Check the installation requirements for Drupal and this profile.
-    install_check_requirements($profile);
+    install_check_requirements($profile, $verify);
 
     // Verify existence of all required modules.
     $modules = drupal_verify_profile($profile, $install_locale);
-    if (!$modules) {
-      install_missing_modules_error($profile);
+
+    // If any error messages are set now, it means a requirement problem.
+    $messages = drupal_set_message();
+    if (!empty($messages['error'])) {
+      drupal_maintenance_theme();
+      install_task_list('requirements');
+      drupal_set_title(st('Requirements problem'));
+      print theme('install_page', '');
+      exit;
     }
 
     // Change the settings.php information if verification failed earlier.
@@ -112,7 +119,7 @@ function install_main() {
     $settings_dir = './'. conf_path();
     $settings_file = $settings_dir .'/settings.php';
     if (!drupal_verify_install_file($settings_file, FILE_EXIST|FILE_READABLE|FILE_NOT_WRITABLE) || !drupal_verify_install_file($settings_dir, FILE_NOT_WRITABLE, 'dir')) {
-      drupal_set_message(st('All necessary changes to %dir and %file have been made, so you should now remove write permissions to them. Failure to remove write permissions to them is a security risk.', array('%dir' => $settings_dir, '%file' => $settings_file)), 'error');
+      drupal_set_message(st('All necessary changes to %dir and %file have been made, so you should remove write permissions to them now in order to avoid security risks. If you are unsure how to do so, please consult the <a href="@handbook_url">on-line handbook</a>.', array('%dir' => $settings_dir, '%file' => $settings_file, '@handbook_url' => 'http://drupal.org/getting-started')), 'error');
     }
     else {
       drupal_set_message(st('All necessary changes to %dir and %file have been made. They have been set to read-only for security.', array('%dir' => $settings_dir, '%file' => $settings_file)));
@@ -182,32 +189,6 @@ function install_change_settings($profile = 'default', $install_locale = '') {
   drupal_maintenance_theme();
   install_task_list('database');
 
-  // The existing database settings are not working, so we need write access
-  // to settings.php to change them.
-  $writable = FALSE;
-  $file = $conf_path;
-  // Verify the directory exists.
-  if (drupal_verify_install_file($conf_path, FILE_EXIST, 'dir')) {
-    // Check to see if a settings.php already exists
-    if (drupal_verify_install_file($settings_file, FILE_EXIST)) {
-      // If it does, make sure it is writable
-      $writable = drupal_verify_install_file($settings_file, FILE_READABLE|FILE_WRITABLE);
-      $file = $settings_file;
-    }
-    else {
-      // If not, makes sure the directory is.
-      $writable = drupal_verify_install_file($conf_path, FILE_READABLE|FILE_WRITABLE, 'dir');
-    }
-  }
-
-  if (!$writable) {
-    drupal_set_message(st('The @drupal installer requires write permissions to %file during the installation process.', array('@drupal' => drupal_install_profile_name(), '%file' => $file)), 'error');
-
-    drupal_set_title(st('Drupal database setup'));
-    print theme('install_page', '');
-    exit;
-  }
-
   if ($db_url == 'mysql://username:password@localhost/databasename') {
     $db_user = $db_pass = $db_path = '';
   }
@@ -607,19 +588,6 @@ function install_already_done_error() {
   exit;
 }
 
-/**
- * Show an error page when Drupal is missing required modules.
- */
-function install_missing_modules_error($profile) {
-  global $base_url;
-
-  drupal_maintenance_theme();
-  install_task_list('requirements');
-  drupal_set_title(st('Modules missing'));
-  print theme('install_page', '<p>'. st('One or more required modules are missing.') .'</p>');
-  exit;
-}
-
 /**
  * Tasks performed after the database is initialized. Called from install.php.
  */
@@ -779,26 +747,49 @@ function install_reserved_tasks() {
 }
 
 /**
- * Page to check installation requirements and report any errors.
+ * Check installation requirements and report any errors.
  */
-function install_check_requirements($profile) {
+function install_check_requirements($profile, $verify) {
   $requirements = drupal_check_profile($profile);
   $severity = drupal_requirements_severity($requirements);
 
   // If there are issues, report them.
   if ($severity == REQUIREMENT_ERROR) {
-    drupal_maintenance_theme();
-    install_task_list('requirements');
 
     foreach ($requirements as $requirement) {
       if (isset($requirement['severity']) && $requirement['severity'] == REQUIREMENT_ERROR) {
-        drupal_set_message($requirement['description'] .' ('. st('Currently using !item !version', array('!item' => $requirement['title'], '!version' => $requirement['value'])) .')', 'error');
+        $message = $requirement['description'];
+        if ($requirement['value']) {
+          $message .= ' ('. st('Currently using !item !version', array('!item' => $requirement['title'], '!version' => $requirement['value'])) .')';
+        }
+        drupal_set_message($message, 'error');
       }
     }
+  }
 
-    drupal_set_title(st('Incompatible environment'));
-    print theme('install_page', '');
-    exit;
+  // If Drupal is not set up already, we also need to create a settings file.
+  if (!$verify) {
+    $writable = FALSE;
+    $conf_path = './'. conf_path();
+    $settings_file = $conf_path .'/settings.php';
+    $file = $conf_path;
+    // Verify that the directory exists.
+    if (drupal_verify_install_file($conf_path, FILE_EXIST, 'dir')) {
+      // Check to see if a settings.php already exists.
+      if (drupal_verify_install_file($settings_file, FILE_EXIST)) {
+        // If it does, make sure it is writable.
+        $writable = drupal_verify_install_file($settings_file, FILE_READABLE|FILE_WRITABLE);
+        $file = $settings_file;
+      }
+      else {
+        // If not, make sure the directory is.
+        $writable = drupal_verify_install_file($conf_path, FILE_READABLE|FILE_WRITABLE, 'dir');
+      }
+    }
+
+    if (!$writable) {
+      drupal_set_message(st('The @drupal installer requires write permissions to %file during the installation process. If you are unsure how to grant file permissions, please consult the <a href="@handbook_url">on-line handbook</a>.', array('@drupal' => drupal_install_profile_name(), '%file' => $file, '@handbook_url' => 'http://drupal.org/getting-started')), 'error');
+    }
   }
 }
 

modules/system/system.install

@@ -111,37 +111,39 @@ function system_requirements($phase) {
   }
 
   // Test files directory
-  if ($phase == 'runtime') {
-    $directory = file_directory_path();
-    $is_writable = is_writable($directory);
-    $is_directory = is_dir($directory);
-    if (!$is_writable || !$is_directory) {
-      if (!$is_directory) {
-        $error = $t('The directory %directory does not exist.', array('%directory' => $directory));
-      }
-      else {
-        $error = $t('The directory %directory is not writable.', array('%directory' => $directory));
-      }
-      $requirements['file system'] = array(
-        'value' => $t('Not writable'),
-        'severity' => REQUIREMENT_ERROR,
-        'description' => $error .' '. $t('You may need to set the correct directory at the <a href="@admin-file-system">file system settings page</a> or change the current directory\'s permissions so that it is writable.', array('@admin-file-system' => url('admin/settings/file-system'))),
-      );
+  $directory = file_directory_path();
+  $is_writable = is_writable($directory);
+  $is_directory = is_dir($directory);
+  if (!$is_writable || !$is_directory) {
+    if (!$is_directory) {
+      $error = $t('The directory %directory does not exist.', array('%directory' => $directory));
     }
     else {
-      if (variable_get('file_downloads', FILE_DOWNLOADS_PUBLIC) == FILE_DOWNLOADS_PUBLIC) {
-        $requirements['file system'] = array(
-          'value' => $t('Writable (<em>public</em> download method)'),
-        );
-      }
-      else {
-        $requirements['file system'] = array(
-          'value' => $t('Writable (<em>private</em> download method)'),
-        );
-      }
+      $error = $t('The directory %directory is not writable.', array('%directory' => $directory));
+    }
+    $requirements['file system'] = array(
+      'value' => $t('Not writable'),
+      'severity' => REQUIREMENT_ERROR,
+    );
+    if ($phase == 'runtime') {
+      $requirements['file system']['description'] = $error .' '. $t('You may need to set the correct directory at the <a href="@admin-file-system">file system settings page</a> or change the current directory\'s permissions so that it is writable.', array('@admin-file-system' => url('admin/settings/file-system')));
+    }
+    else if ($phase == 'install') {
+      // For the installer UI, we need different wording. 'value' will
+      // be treated as version, so provide none there.
+      $requirements['file system']['description'] = $error .' '. $t('To proceed with the installation, please change the %directory directory permissions to allow the installer to write to it. If you are unsure how to do so, please consult the <a href="@handbook_url">on-line handbook</a>.', array('%directory' => $directory, '@handbook_url' => 'http://drupal.org/getting-started'));
+      $requirements['file system']['value'] = '';
+    }
+  }
+  else {
+    if (variable_get('file_downloads', FILE_DOWNLOADS_PUBLIC) == FILE_DOWNLOADS_PUBLIC) {
+      $requirements['file system']['value'] = $t('Writable (<em>public</em> download method)');
+    }
+    else {
+      $requirements['file system']['value'] = $t('Writable (<em>private</em> download method)');
     }
-    $requirements['file system']['title'] = $t('File system');
   }
+  $requirements['file system']['title'] = $t('File system');
 
   // See if updates are available in update.php.
   if ($phase == 'runtime') {