entity_links_bulk_processor
Current Release:
1.0.0-alpha9 (Alpha)
This is the first public release of Entity Links Bulk Processor. The module is production-ready with comprehensive tests and documentation. We're seeking community feedback before declaring a stable 1.0.0 release.
- ✅ Production-ready code quality
- ✅ Used in production at College of Western Idaho
- ✅ Comprehensive test coverage
- ⚠️ First public release - feedback welcome!
Transform Your Content with Comprehensive HTML Cleanup
Entity Links Bulk Processor is the complete solution for cleaning up migrated and legacy content. From entity link conversion and CSS class mapping to multilingual processing and media conversion, this module handles the entire HTML cleanup pipeline. Whether you're migrating from Drupal 7, modernizing your theme, or maintaining content quality across translations, this module provides industrial-strength tools.
Entity Links Bulk Processor + Drupal 11.3 + Linkit: Perfect Together
🎯 They're 100% Compatible - Here's Why:
- Same Language: All three use identical data-entity-type and data-entity-uuid attributes
- Different Jobs:
- Entity Links Bulk Processor = Bulk cleanup of thousands of legacy nodes (one-time)
- Drupal 11.3 Core = Create new entity links in CKEditor 5 (ongoing)
- Linkit Module = Advanced entity linking with profiles & configs (ongoing)
- Works Together: Links created by this module are recognized by Core/Linkit filters automatically
✅ Migration Power Combo:
- Migrate D7→D10/11
- Run Entity Links Bulk Processor to fix legacy markup in bulk
- Enable Core Entity Links or Linkit for editors going forward
- Result: Clean entity links everywhere, past and future
💡 Use Case:
- This module: "I have 5,000 migrated nodes with /node/123 paths and D7 media tokens"
- Core/Linkit: "I'm writing a new article and want to link to another node"
- Together: Historical content stays clean, new content follows best practices
No conflicts. No duplicate work. Just clean entity links throughout your entire site.
🎯 Perfect For
- Drupal 7 to 10/11 Migrations: Automatic entity links, media conversion, CSS cleanup
- Theme Modernization: Bootstrap 3→5, custom theme evolution, component library adoption
- Multilingual Sites: Language-aware processing, cross-language alias detection
- Content Cleanup: Standardize HTML across thousands of nodes from unhealthy data entry
- Ongoing Quality: Real-time processing with Autosave submodule prevents bad content copying
✨ Key Features
Entity Link Conversion
- Converts internal paths to UUID-based entity links
- Preserves links even when node IDs change
- Supports nodes, media, taxonomy terms, paragraphs
- Maintains query strings and URL fragments
Comprehensive Link Validation
- 📧 Email (mailto:) - Format validation and lowercase normalization
- 📞 Telephone (tel:) - RFC 3966/E.164 formats with country code support
- 💬 SMS - Number validation with body parameter preservation
- 📠 Fax - Complete format validation and normalization
Smart Path Resolution
- Pathauto alias resolution
- Redirect chain following
- External domain conversion
- Published status checking
CSS Class Mapping - ALL HTML Elements
- 🎨 Universal Element Support: Maps CSS classes on div, span, p, a, and ANY HTML element
- 🔍 Smart Discovery Tool: Scans all content, finds all classes, shows usage counts
- 📊 Priority Processing: Custom selectors → Element-specific → Wildcard
- ♻️ Theme Evolution: Bootstrap 3→5, old module classes, design system adoption
- 🎯 Circular Detection: Prevents A→B→A mapping loops with DFS algorithm
- 📝 Export: Bulk export from discovery results, you write config
- 🚫 Class Removal: Map to empty string to delete unwanted classes
Multilingual Content Processing
- 🌍 All Translations: Process all language versions of content
- 🔤 Language Filtering: Process only specific languages (e.g., es, fr)
- 🔗 Cross-Language Aliases: Detect when Spanish alias appears in English content
- 📍 Language-Aware Resolution: Path aliases resolved in correct language context
- 📊 Language Logging: Success logs include language column for tracking
Media Conversion (Drupal 7 → 10/11)
- 🖼️ Image Tags: <img> → <drupal-media> with file path lookup
- 🎥 Video Tags: <video> → <drupal-media> with multiple source support
- 📦 D7 WYSIWYG Tokens: [[{"fid":"123"}]] → <drupal-media> via migrate_map
- 🎨 Attribute Preservation: Alt text, titles, alignment, dimensions preserved
- 🔄 View Mode Mapping: D7 "teaser" → D10 "thumbnail" automatic conversion
- ⚡ Processing Order: D7 tokens BEFORE DOM parsing (critical for correctness)
Additional HTML Cleanup
- Inline style removal with CSS class exclusions
- Title attribute handling (removal/mismatch reporting)
- File path to media entity conversion
- Absolute to relative URL conversion
Enterprise-Ready
- Dry-run mode for safe testing
- Database backup integration
- CSV logging (success, statistics & errors)
- Batch processing for large datasets
- Hosting platform cli integration with drush commands (Acquia, Pantheon, Platform.sh)
Automation
- Full-featured Drush commands with command generation
- Entity Links Autosave submodule for real-time processing on every save
- Cron-ready for scheduled operations
- Non-interactive mode for CI/CD pipelines
🚀 Quick Start
# Install
composer require drupal/entity_links_bulk_processor
drush en entity_links_bulk_processor -y
# Preview changes
drush entity-links:bulk-process --filter="node:*" --dry-run
# Process with backup and logs
drush entity-links:bulk-process --filter="node:*" \
--backup=/tmp/backup.sql \
--success-log=/tmp/success.csv \
--error-log=/tmp/errors.csv \
-y📊 Processing Options
UI-Based
- Visual form with entity type/bundle selection
- Preview before any processing
- Batch operations for browser-based workflows
- Copy-to-clipboard command generation
- Rule-set management
- CSS class discovery and mapping
Drush Commands
- Entity type and bundle filtering
- Specific entity ID processing
- CSV-based batch imports
- Full logging and reporting
- Hosting platform command generation
🔧 Hosting Platform Integration
Pre-configured command generation for major hosting platforms:
Acquia Cloud
acli api:environments:database-backup-create @site.dev dev && \
acli drush:@site.dev -y -- drush entity-links:bulk-process --filter="node:article,page paragraph:text"Pantheon Terminus
terminus backup:create site.dev --element=db --keep-for=30 && \
terminus drush site.dev -y -- entity-links:bulk-process --filter="node:page"Platform.sh
platform backup:create -e main -y && \
platform drush -e main -y -- entity-links:bulk-process --filter="node:page"⚡ Entity Links Autosave Submodule
Enable real-time link processing:
- Automatic conversion as editors save content
- Configurable per entity type, bundle, and field
- Separate user feedback - Display warnings to editors without watchdog entries
- Optional debug logging - Enable detailed watchdog logging only when troubleshooting
- Zero manual intervention required
- Perfect for ongoing maintenance and editorial workflows
📈 Production-Ready with 43 PHPUnit Tests
Test Coverage:
- ✅ 43 automated tests, 319 assertions
- ✅ 7 unit tests for circular mapping detection (DFS algorithm)
- ✅ 10 kernel tests for CSS mapping, multilingual, media conversion
- ✅ 16 functional tests for forms and batch processing
- ✅ All tests pass in GitLab CI/CD environment
- ✅ Follows Drupal coding standards (PHPCS, PHPStan, ESLint)
- ✅ Comprehensive documentation (DEVELOPMENT_LOG.md)
- ✅ Active maintenance and issue queue support
🎓 Real-World Use Cases
Scenario 1: Complete Drupal 7 Migration
# Step 1: Convert D7 media tokens and entity links
drush entity-links:bulk-process --filter="media:*" \
--backup=/backup/pre-conversion.sql \
--success-log=/logs/conversion.csv -y
# Step 2: Process paragraphs
drush entity-links:bulk-process --filter="paragraph:*" -y
# Step 3: Handle multilingual content (Spanish + French)
drush entity-links:bulk-process --filter="node:page" --languages=es,fr -y
Scenario 2: Bootstrap 3 → Bootstrap 5 Theme Migration
1. Visit /admin/config/content/entity-links-bulk-processor/discover-css-classes
2. Scan all article and page content types
3. Review discovered classes: pull-left, text-muted, btn-primary
4. Map classes:
- pull-left → float-start
- pull-right → float-end
- text-muted → text-secondary
- button-primary → btn btn-primary
5. Import mappings and process all nodes
6. Result: 5,000+ nodes updated with new Bootstrap 5 classes
Scenario 3: Multilingual University Site
- 15,000 nodes in English, Spanish, French
- Editors mix language aliases (Spanish /acerca in English content)
- Enable cross-language alias detection
- Process all translations: drush elbp --filter="node:sa_page" -y
- Success log shows language column for tracking
- Cross-language aliases automatically detected and resolved
Scenario 4: Prevent Bad Content Copying
- Enable Autosave submodule on all text fields
- Editors copy content from old site with:
- Old CSS classes (clearfix, pull-left)
- Inline styles (style="margin-top: 20px") with class exclusions
- Legacy media tokens
- Autosave automatically cleans on save
- Editors see warnings, content stays clean
- Zero manual intervention required
Scenario 5: Custom Component Library Migration
# Map old component classes to new design system
# Old: <div class="card-primary">
# New: <div class="ds-card ds-card--primary">
# Discover, Export and Configure mappings via UI
/admin/config/content/entity-links-bulk-processor/discover-css-classes
# Process with custom element selector
drush elbp --filter="node:landing_page" -y📦 What's Included
Main Module
- Bulk processing form and configuration
- Drush commands
- Batch processing
- CSS class discovery and export
- Logging and reporting
Autosave Submodule
- Real-time processing on save
- Using the same configuration rule-set
- Per-entity-type, bundle, and field configuration
- Separate user feedback and debug logging
- Clean production logs with optional troubleshooting
Documentation
- Comprehensive README
- Detailed usage guide
- Manual Testing Guide
- Example use cases
🔒 Security & Safety
- Permission-based access control
- Dry-run mode for testing
- Database backup integration
- Input validation and sanitization
- Rollback procedures documented
📚 Resources
- Documentation: Complete usage guide included
- Issue Queue: Active support
- Test Coverage: PHPUnit tests for all major features
- Examples: Real-world use cases documented
🏆 Why Choose Entity Links Bulk Processor?
✅ Beyond Links: CSS mapping on ALL elements, not just <a> tags
✅ Migration Ready: D7 media conversion, multilingual support built-in
✅ Comprehensive Testing: 43 PHPUnit tests ensure reliability
✅ Safe Operations: Dry-run mode, backup integration, circular detection
✅ Production-Proven: Used at College of Western Idaho on 15,000+ nodes
✅ Flexible Deployment: UI, Drush, automated options, hosting platform integration
✅ Prevents Future Issues: Autosave submodule stops bad content at the source
✅ Well-Documented: DEVELOPMENT_LOG.md covers 30 development phases
✅ Smart Discovery: Find ALL CSS classes with usage counts across content
✅ Algorithm-Backed: DFS circular detection, priority-ordered processing
Requirements
- Drupal ^10.2 || ^11
- PHP ^8.1
- Drush ^12 || ^13 (optional, for command-line operations)
Installation
Via Composer (recommended):
composer require drupal/entity_links_bulk_processor
Via Drupal UI:
1. Download from project page
2. Extract to modules/contrib
3. Enable via Extend page
Support
- Issue Queue: Report bugs and request features
- Documentation: See included markdown files
---
Similar Projects & Unique Value
This module is unique in its comprehensive HTML cleanup approach:
Link-Focused Modules:
- Link Attributes: Adds attributes (no bulk processing, CSS mapping, or media conversion)
- Pathologic: Fixes paths (no entity links, multilingual, or CSS cleanup)
- Link Checker: Finds broken links (no automatic fixing or cleanup)
CSS/Theme Modules:
- CSS Editor: Manual CSS editing (no bulk class mapping or discovery)
- Asset Injector: Adds CSS/JS (no content-level class transformation)
Migration Modules:
- Migrate Tools: Migration framework (no post-migration HTML cleanup)
- Migrate Plus: Migration plugins (no CSS mapping or media conversion)
What Makes This Module Different:
Entity Links Bulk Processor is the only module that combines:
- ✅ Entity link conversion (UUID-based)
- ✅ CSS class mapping on ALL HTML elements (not just links)
- ✅ Multilingual content processing with cross-language detection
- ✅ Drupal 7 media token conversion ([[{}]] → <drupal-media>)
- ✅ Circular mapping detection (DFS algorithm)
- ✅ CSS class discovery tool with usage statistics
- ✅ Real-time autosave processing
- ✅ 43 PHPUnit tests covering all features
Think of it as: A complete HTML normalization pipeline for migrations and ongoing content quality, not just a link fixer.
---
License
GPL-2.0-or-later
---
Ready to transform your content links? Install today and see the difference!