Path Redirect Import
Enables bulk import and export of URL redirects via CSV files using Drupal's Migrate API.
path_redirect_import
Install
composer require 'drupal/path_redirect_import:^2.1'
composer require 'drupal/path_redirect_import:^2.0'
Overview
Path Redirect Import provides a streamlined solution for managing large numbers of URL redirects in Drupal. Built on top of Drupal's Migrate API, this module allows site administrators to bulk import redirects from CSV files and export existing redirects for backup or migration purposes.
The module integrates seamlessly with the Redirect module, appearing as additional tabs on the redirect administration page. It supports various redirect scenarios including internal paths, external URLs, homepage redirects using <front>, and URLs with query parameters. The module also provides Drush commands for command-line operations, making it suitable for automated deployment workflows and large-scale redirect management.
CSV validation ensures data integrity before import, checking for proper encoding, required fields, and preventing circular redirects where source and destination are identical.
Features
- Bulk import URL redirects from CSV files with validation for encoding, empty values, and circular redirect prevention
- Bulk export all existing redirects to a downloadable CSV file for backup or migration
- Supports internal paths, external URLs, and special paths like <front> for homepage redirects
- Handles URL-encoded characters and query parameters in source paths
- Language-aware redirects with support for language codes (und for language-neutral)
- Configurable HTTP status codes (301, 302, etc.) per redirect
- Batch processing for large datasets to prevent timeouts
- Integration with Drupal's Migrate API for robust data handling
- Drush commands for command-line import and export operations
- Delete mode to remove redirects defined in a CSV file
Use Cases
Site Migration with URL Redirects
When migrating content from an old site to a new Drupal site, URLs often change. Create a CSV mapping old URLs to new URLs and import them in bulk to maintain SEO rankings and prevent broken links for visitors.
URL Structure Reorganization
When reorganizing site content (e.g., moving blog posts from /blog/post-title to /articles/post-title), export current redirects, prepare a CSV with the old-to-new mappings, and import to ensure all existing links continue to work.
Marketing Campaign Vanity URLs
Create short, memorable URLs for marketing campaigns (e.g., /sale redirecting to /products/summer-sale-2024) by preparing a CSV with campaign URLs and importing them before launch.
Redirect Backup and Restore
Regularly export redirects to CSV files as part of site backup procedures. If redirects are accidentally deleted or corrupted, restore them by importing the backup CSV.
Multi-environment Redirect Sync
Export redirects from production, adjust if needed, and import to staging or development environments to ensure consistent redirect behavior across environments.
Bulk Redirect Cleanup
Export all redirects, identify obsolete ones in the CSV, then use the delete mode to remove outdated redirects that point to pages that no longer exist.
Multilingual Site Redirects
Manage language-specific redirects by using the language column in the CSV. Set redirects to 'und' for language-neutral behavior or specific language codes (en, fr, de, etc.) for language-specific redirects.
Tips
- Source paths in the CSV should not have a leading slash - use 'old-page' not '/old-page'
- Use <front> as the destination to redirect to the homepage
- Query parameters are supported in source paths (e.g., old-page?param=value)
- External URLs are fully supported as destinations (e.g., https://example.com)
- The 301 status code is the default if not specified, indicating a permanent redirect
- For temporary redirects (e.g., during maintenance), use 302 status code
- Large imports are processed in batches to prevent PHP timeout issues
- Exported files are temporary and will be deleted by cron - download promptly
- When using the delete option, you'll see a confirmation page before redirects are removed
- The module reuses Migrate's update functionality, so re-importing the same CSV will update existing redirects rather than create duplicates
Technical Details
Admin Pages 2
/admin/config/search/redirect/migrate
Import URL redirects from a CSV file or delete existing redirects based on CSV data. The form validates the CSV file for proper headers, UTF-8 encoding, empty values, and circular redirects before processing.
/admin/config/search/redirect/export
Export all existing URL redirects from the site to a downloadable CSV file. The exported file follows the same format as the import, making it suitable for backup, migration to another site, or editing and re-importing.
Drush Commands 2
drush path_redirect_import:import <file>
Imports redirects from the specified CSV file. The file must follow the standard format with headers: source, destination, language, status_code.
drush path_redirect_import:export
Exports all existing redirects to a CSV file. The file is saved in the public files directory under path_redirect_import/ with a timestamp-based filename.
Troubleshooting 7
Ensure your CSV file has exactly these headers in the first row: source,destination,language,status_code (case-sensitive, no spaces)
Save your CSV file with UTF-8 encoding. In Excel, use 'Save As' and select 'CSV UTF-8 (Comma delimited)'. In other editors, ensure the file is saved as UTF-8 without BOM.
Check the CSV for rows where source and destination are identical (including the leading slash comparison). A redirect cannot point to itself.
Ensure every row has values in all four columns. Use 'und' for language-neutral redirects and a valid status code (301, 302, etc.).
Clear Drupal caches after import. Also verify the source path doesn't have a leading slash in the CSV (source-path not /source-path).
Ensure there are existing redirects to export. The module will display an error message if there are no redirects in the system.
Ensure Migrate Tools module is enabled. The Drush commands are conditionally registered only when Migrate Tools is installed.