Visual Diff Merge

Prerequisites

Before installing Visual Diff Merge, ensure your environment meets the following requirements:

Server Requirements

• PHP 7.4 or higher
• Web server (Apache, Nginx, etc.)
• Composer (for PHP dependencies)

Development Requirements (Optional)

These are only needed if you plan to modify the source code:

• Node.js 14.x or higher
• npm 6.x or higher

Installation

Option 1: Standard Installation (Recommended)

If you want to use Visual Diff Merge as-is without modifying the source code:

1. Clone or Download the Repository

   git clone https://github.com/migliori/visual-diff-merge.git
   cd visual-diff-merge

2. Install PHP Dependencies

   composer install --no-dev

3. Configure the Application (Optional)

   You can use the default configuration or customize the configuration as needed:

   # Copy example configuration file
   cp api/config.example.php api/config.php
   
   # Edit the configuration as needed
   nano api/config.php  # or use any text editor

4. Set Proper Permissions

   Ensure your web server has read/write access to the necessary directories:

   # On Linux/Unix systems
   chmod -R 755 api/
   chmod 644 api/config.php

   For server-specific permission settings, see Server-Specific Configuration.

5. Configure Web Server

   Set up your web server to serve the Visual Diff Merge directory.

Option 2: Development Installation

If you want to modify the source code:

1. Clone the Repository

   git clone https://github.com/migliori/visual-diff-merge.git
   cd visual-diff-merge

2. Install PHP Dependencies

   composer install

3. Install Node.js Dependencies

   npm install

4. Build the Assets

   # For production build
   npm run build
   
   # For development with auto-rebuild
   npm run dev

5. Configure the Application

   # Copy example configuration file
   cp api/config.example.php api/config.php
   
   # Edit the configuration as needed
   nano api/config.php  # or use any text editor

Configuration

Visual Diff Merge comes with default configuration settings defined in php/Config.php. These default settings work out of the box for most typical use cases.

Customizing Configuration

To customize the configuration:

1. Copy the example configuration file: Rename api/config.example.php to api/config.php
2. Edit the configuration: Modify the settings in api/config.php to match your requirements

For a comprehensive overview of styling options, see the Styling Customization section.

For language and localization settings, refer to the Translations documentation.

Basic Configuration Structure

<?php

return [
    // PHP-only settings
    'php' => [
        'debug' => [
            'enabled' => false,
            'logLevel' => 2,
            'logFile' => 'debug-php-diff.log'
        ],
        'diff' => [
            'contextLines' => 3,
            'ignoreWhitespace' => false,
            'ignoreCase' => false
        ],
        'security' => [
            'csrfProtection' => true,
            'salt' => '',
            'allowedDirectories' => []
        ],
        'paths' => [
            'base' => ''
        ]
    ],

    // JavaScript settings
    'javascript' => [
        'lang' => 'en',
        'debug' => false,
        'logLevel' => 2,
        'apiBaseUrl' => null,  // Auto-detect API path, or set custom path
        'theme' => [
            'defaultFamily' => 'atom-one',
            'defaultMode' => 'dark',
            'showSelector' => true
        ],
        // Additional JavaScript settings...
    ]
];

Key Configuration Options

PHP Settings

JavaScript Settings

Security Configuration

For the File Browser mode, you need to configure which directories are allowed to be accessed:

'security' => [
    // Other security settings...
    'allowedDirectories' => [
        // Examples (uncomment and modify as needed):
        // realpath(__DIR__ . '/../diff-viewer/samples'),
        // '/var/www/html/my-project',
        // 'C:\\Projects\\my-files'
    ]
]

If no directories are specified, only the application root directory is accessible.

Internationalization

Visual Diff Merge supports multiple languages through the PHP configuration:

'php' => [
    // Other PHP settings...
    'translations' => [
        'en' => [
            'applyMerge' => 'Apply Merge',
            'continueResolving' => 'Continue Resolving',
            // Other English translations...
        ],
        'fr' => [
            'applyMerge' => 'Appliquer la fusion',
            'continueResolving' => 'Continuer la résolution',
            // Other French translations...
        ]
    ],
],
'javascript' => [
    // JavaScript settings...
    'lang' => 'fr', // Set default language to use
]

The full list of translatable strings is available in the api/config.example.php file.

Testing Your Installation

Test File Browser Mode

To test the File Browser mode:

1. Copy some sample files to a directory within your allowed directories
2. Access diff-viewer/file-browser.php through your web server
3. Select two files for comparison
4. Verify that the comparison works correctly

Test Other Modes

The other modes (File Upload, Text Compare, URL Compare) don't require any special setup:

1. Access the respective example file through your web server:
   • diff-viewer/file-upload.html
   • diff-viewer/text-compare.html
   • diff-viewer/url-compare.html
2. Follow the on-screen instructions to compare content
3. Verify that the comparison works correctly

Troubleshooting

API Endpoint Issues

If you get API errors:

1. Check that your web server can access the api/ directory
2. Verify that PHP is properly configured
3. Check the browser console for specific error messages
4. Enable debugging in api/config.php and check the log file

File Browser Access Issues

If you can't access files in the File Browser mode:

1. Make sure the directories are listed in php.security.allowedDirectories
2. Check file permissions on the server
3. Verify that paths are correctly specified (absolute paths recommended)

Blank Screen or JavaScript Errors

If you get a blank screen or JavaScript errors:

1. Enable debug mode in both PHP and JavaScript settings in your api/config.php file:

   'php' => [
       'debug' => [
           'enabled' => true,  // Set to true to enable PHP debugging
           'logLevel' => 3,    // Set to 3 for verbose logging
           'logFile' => 'debug-php-diff.log'
       ],
       // ...other settings...
   ],
   'javascript' => [
       'debug' => true,       // Set to true to enable JavaScript debugging
       'logLevel' => 3,       // Set to 3 for detailed console logging
       // ...other settings...
   ]

2. Open your browser's developer console (F12 or Ctrl+Shift+I in most browsers)
3. Reload the page and check the console for error messages
4. Also check the PHP log file (default location: api/debug-php-diff.log)
5. Look for "Failed to load resource" errors which may indicate path or permission issues
6. If you see AJAX errors, check network requests in the browser's developer tools
7. Try clearing your browser cache and cookies

PHP Errors

If you get PHP errors:

1. Verify that your PHP version is 7.4 or higher
2. Check that all required PHP extensions are installed
3. Ensure Composer dependencies are properly installed
4. Check PHP error logs for specific messages

Server-Specific Configuration

Apache

For Apache servers, you may need to add/modify the .htaccess file:

# Allow PHP to access .php files in the api directory
<FilesMatch "\.(php)$">
    Require all granted
</FilesMatch>

# Set proper MIME types
AddType application/javascript .js
AddType text/css .css

# Enable CORS if needed
<IfModule mod_headers.c>
    Header set Access-Control-Allow-Origin "*"
    Header set Access-Control-Allow-Methods "GET, POST, OPTIONS"
    Header set Access-Control-Allow-Headers "Content-Type, Authorization"
</IfModule>

Nginx

For Nginx servers, add to your server block:

server {
    # Other server configuration...

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; # Adjust to your PHP-FPM socket
    }

    # Enable CORS if needed
    location /api/ {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization';
    }
}