Search and Replace Scanner
Performs search and replace operations on configurable text fields across Drupal entities using plain text or regular expressions.
scanner
Install
composer require 'drupal/scanner:8.x-1.0'
Overview
The Search and Replace Scanner module provides powerful bulk search and replace functionality for Drupal sites. It can perform regular expression or plain text matches against a configurable list of text fields across multiple entity types, making it invaluable for tasks like updating company names, fixing URLs, or correcting repeated content errors across large amounts of content.
Unlike Drupal's built-in search, Scanner can find HTML strings and other content that would normally be ignored. The module creates new revisions when making replacements, allowing changes to be reverted if needed. It also provides a comprehensive undo system that tracks all replacement operations and allows reverting all entities affected by a specific replacement action.
Out of the box, Scanner supports nodes and paragraphs, but its extensible plugin architecture allows developers to add support for additional entity types like taxonomy terms or custom entities. The module includes sophisticated handling for multi-language content, nested paragraph structures, and various field types including formatted text, plain text, strings, and link fields.
Features
- Plain text search and replace across configurable entity fields
- Regular expression search and replace with full regex syntax support
- Case sensitive search option for precise matching
- Whole word matching option to avoid partial word matches (e.g., 'run' won't match 'running')
- Preceded by and followed by text filters to narrow matches based on surrounding context
- Support for nodes and paragraphs out of the box with extensible plugin system for other entities
- Restrict searches to published nodes only
- Multi-language content support with language-specific or all-language searches
- Automatic revision creation when replacements are made for easy rollback
- Comprehensive undo functionality to revert all entities from a specific replacement operation
- Search results display with highlighted matches and context snippets
- Batch processing for large-scale operations with automatic execution time expansion
- Configurable default search options for streamlined workflow
- MySQL/MariaDB word boundary compatibility handling for different database versions
- Themeable search results template
- Supports string, text, text_long, text_with_summary, and link field types
Use Cases
Company Name Change
When a company changes its name, Scanner can find and replace all instances of the old name across all content. Use whole word matching to avoid partial replacements, and the undo feature provides safety if any mistakes are made.
URL Migration
When moving content between domains or changing URL structures, Scanner can update all internal links. Using regular expressions, complex URL patterns can be matched and transformed systematically.
Content Standardization
Standardize terminology across a site by replacing informal terms with official ones. For example, replacing 'website' with 'web site' or updating product names to current branding.
HTML Cleanup
Find and remove or replace unwanted HTML tags, fix broken markup, or update deprecated HTML to modern standards. Regular expression mode allows complex pattern matching for HTML structures.
Multi-language Content Updates
When content needs to be updated across multiple language versions, Scanner can process all translations simultaneously or target specific languages, ensuring consistency across localized content.
Fixing Repeated Typos
Correct a typo that has been made repeatedly across many pieces of content. Use case-sensitive search to match the exact error, and whole word matching to avoid unintended changes.
Contact Information Updates
Update phone numbers, email addresses, or physical addresses that appear in multiple locations throughout the site's content.
Tips
- Always backup your database before performing large-scale replacements. Scanner is powerful and can modify content site-wide.
- Use the search feature first to preview what will be changed before executing a replacement.
- For complex patterns, test your regular expressions on a single field/content type before enabling all fields.
- The 'Preceded by' and 'Followed by' options are useful for narrowing matches without complex regular expressions.
- When replacing HTML, be careful with regular expression mode as HTML is not a regular language. Consider preceded/followed text options instead.
- New revisions are created automatically, so you can always revert individual entities through Drupal's revision interface even if you don't use the undo feature.
- For multi-language sites, consider whether you want to replace in all languages or just one. The language filter can prevent unintended changes to translations.
- Users with 'perform search and replace' permission can modify entities they normally can't edit. Assign this permission carefully.
- The undo feature tracks all replacements. Periodically review the undo list to clean up old operations if needed.
Technical Details
Admin Pages 5
/admin/content/scanner
The main search and replace interface where users can enter search terms, specify replacement text, configure search options, and view results. Users can perform searches to preview matches before executing replacements.
/admin/config/content/scanner
Configuration page for setting default search options, selecting which entity types and fields can be searched, and configuring database compatibility settings.
/admin/content/scanner/confirm
Confirmation page displayed before executing a replacement operation. Shows the search term and replacement text and asks for confirmation before proceeding.
/admin/content/scanner/undo
Lists all previous replacement operations that have not been undone. Shows the date, search term, replacement text, number of affected entities, and provides an undo link for each operation.
/admin/content/scanner/undo/{id}/confirm
Confirmation page displayed before undoing a previous replacement operation. Reverting restores all affected entities to their previous revisions.
Permissions 3
Hooks 1
hook_scanner_info_alter
Allows modules to alter scanner plugin definitions. Can be used to replace the default scanner handler for an entity type with a custom implementation.
Troubleshooting 6
Check the 'Regex word boundaries' setting in the admin configuration. If your database is MySQL 8.0.4+, ensure it's set to 'ICU mode' or 'Detect automatically'. Older MySQL and MariaDB versions require 'Henry Spencer mode'.
The module attempts to extend PHP's max_execution_time to 5 minutes. If replacements still timeout, contact your hosting provider about increasing the max_execution_time limit, or break the replacement into smaller batches by selecting fewer fields.
Scanner uses temporary storage tied to the user session. Only one instance can run at a time per user. Complete or cancel the current operation before starting another.
Undo restores entities to their previous revision. If other changes were made to the entity between the replacement and the undo, those changes may be lost. Always backup your database before major replacement operations.
Go to Administration > Reports > Status report to see the detected database type and version. Then update the word boundaries setting at Administration > Configuration > Content authoring > Search and Replace Scanner to match your database.
The replace functionality requires the 'Perform search and replace' permission. Users with only 'Perform search only' permission can search but not replace. Check user permissions at Administration > People > Permissions.
Security Notes 5
- Users with 'Perform search and replace' permission can modify entities even without normal edit access to those entities. Grant this permission only to trusted users.
- The 'Administer scanner settings' permission controls which fields can be searched. This restricts which content can be modified even by users with replace permission.
- Regular expression replacements execute PHP's preg_replace function. While search terms are user-provided, the replacement is limited to text substitution.
- Scanner creates revision history for all changes, providing an audit trail of modifications.
- Database credentials are used to detect MySQL/MariaDB version for word boundary compatibility but are not exposed in the interface.