field_value_tracker

The Field Value Tracker module automatically updates environment-specific field values when syncing databases from production to staging or development
environments. It solves a common problem: keeping production URLs, email addresses, and other sensitive data from being used in lower environments where they
could cause issues like sending test emails to real customers or linking to production services.

Instead of manually updating hundreds or thousands of field values after each database sync, configure this module once and run a simple Drush command to
automatically replace production values with environment-appropriate alternatives.

Features

Basic Functionality:

• Two Update Modes:
  • Replace Mode - Performs substring replacement (e.g., change "production.example.com" to "staging.example.com" in URLs)
  • Overwrite Mode - Completely replaces all values (e.g., set all email addresses to "[email protected]")
• Field Configuration Entity - Store your environment-specific field mappings that persist across deployments
• Drush Integration - Simple commands to list trackers and update field values
• Production Safety - Automatically blocks execution in production environments (Acquia and Pantheon)
• Dry-Run Support - Preview what will change before actually updating the database
• Autocomplete Field Selection - Easy-to-use interface for selecting which fields to track

When would you use this module?

• You regularly sync production databases to staging/dev environments
• Your content contains environment-specific URLs (API endpoints, service URLs, CDN links)
• You need to prevent test emails from going to real customers
• You want to automate post-sync database cleanup tasks
• You have OAuth callback URLs or webhook endpoints that differ between environments

Use Cases:

• API Endpoints: Replace production API URLs with sandbox versions in staging
• Email Addresses: Override all notification emails to go to test addresses
• External Services: Point to staging versions of payment processors, CRMs, or other integrations
• CDN URLs: Use different CDN domains for different environments
• Login/SSO URLs: Ensure authentication goes to the right environment

Post-Installation

After enabling the module:

1. Grant Permissions: Go to /admin/people/permissions and grant the "Administer field value tracker" permission to
   appropriate roles
2. Configure Trackers: Navigate to /admin/config/development/field-value-tracker
   • Click "Add field value tracker item"
   • Select a mode (Replace or Overwrite)
   • Use the autocomplete field to select which field to track (format: entity_type.bundle.field_name)
   • Enter the production value (what to find/replace)
   • Enter the lower environment value (what to replace it with)
   • Save
3. Test with Dry-Run: Before making any changes, test your configuration:
   

   drush fvt:update --dry-run

   This shows what would be updated without actually changing anything

4. Run Updates: Execute the update command:
   

   drush fvt:update

5. Automate (Optional): Integrate with your hosting platform's post-database-sync hooks:
   • Acquia: Add to hooks/post-db-copy/field-value-sync.sh
   • Pantheon: Add to pantheon.yml workflows

Special Considerations:

• The module only works with fields that store data in field tables (not base fields)
• Updates are performed directly at the database level for performance
• Entity caches are not automatically cleared (the module provides guidance on this)
• The module will refuse to run in detected production environments for safety

Additional Requirements

Core Requirements:

• Drupal Core 11.0 or higher
• PHP 8.3 or higher

Drupal Core Modules:

• Field (drupal:field)
• Options (drupal:options)
• System (drupal:system)

Drush:

• Drush 12 or higher (for command functionality)

No external libraries or APIs are required.

Recommended modules/libraries

While not required, these modules can enhance your workflow:

• Config Split - Manage environment-specific configuration alongside field
  values
• Stage File Proxy - Complement this module by proxying files from
  production instead of syncing them
• Environment Indicator - Visual reminder of which environment you're
  working in
• Devel - Useful development tools when testing field updates

Similar projects

Stage File Proxy - Handles files instead of field values. Stage File Proxy
proxies file requests to production, while Field Value Tracker updates database field values. They work well together.

Config Split - Manages environment-specific configuration (settings, blocks,
etc.), while Field Value Tracker handles content field values. Different use cases that complement each other.

Manual SQL Updates - Before this module, developers often wrote custom SQL scripts or post-sync hooks. Field Value Tracker provides a
standardized, UI-driven approach that's easier to maintain and doesn't require SQL knowledge.

What makes Field Value Tracker different?

• User-friendly configuration interface (no SQL required)
• Persistent configuration that survives deployments
• Built-in safety features to prevent running in production
• Dry-run support for safe testing
• Comprehensive test coverage
• Designed specifically for field values in content entities

Supporting this Module

This module is maintained by Phase2. If you find this module useful, please:

• ⭐ Star the project on Drupal.org
• 🐛 Report issues and help improve the module
• 💡 Share your use cases and feature requests
• 📝 Contribute documentation or code improvements

Community Documentation

Additional resources:

• Comprehensive README - Full documentation is included in the module's README.md file
• GitLab CI Integration - The module includes a .gitlab-ci.yml file for automated testing
• Test Coverage - Extensive kernel tests demonstrate usage patterns and serve as code examples

Want to add a video tutorial or demo? Contributions welcome!

Quick Start Example

Here's a complete example workflow:

  # 1. Enable the module
  drush en field_value_tracker

  # 2. Create a tracker via the UI at /admin/config/development/field-value-tracker
  #    - Mode: Replace
  #    - Field Target: node.article.field_api_url
  #    - Production Value: https://api.example.com
  #    - Lower Environment Value: https://api-staging.example.com

  # 3. After your next database sync, run:
  drush fvt:update --dry-run   # Preview changes
  drush fvt:update              # Apply changes

  # 4. Verify results
  drush fvt:list                # See all configured trackers
  

That's it! Your staging environment now uses staging API endpoints instead of production ones.