Getting Started

Minimal Setup

Install the package via Composer in your Laravel project (dev dependency):
```
composer require --dev pluswerk/grumphp-xliff-task
```

Configure GrumPHP (grumphp.yml) to include the task:

parameters:
    tasks:
        xlifflint:
            ignore_patterns: []  # Add patterns like ['vendor/', 'tests/'] if needed
            triggered_by: [xlf, xliff]  # Files to trigger the task
extensions:
    - PLUS\GrumPHPXliffTask\ExtensionLoader

Run GrumPHP locally to test:
```
./vendor/bin/grumphp run
```
- Focus on files with .xlf or .xliff extensions.

First Use Case

Validate XLIFF files before merging translations into your Laravel localization workflow (e.g., Spatie Translation Manager or custom XLIFF-based systems).

Example: Catch malformed XML in translation files early, preventing deployment of broken translations.

Implementation Patterns

Core Workflows

Pre-Commit Hook Integration
- Add to .git/hooks/pre-commit or use grumphp's built-in Git hooks:
```
# grumphp.yml
hooks:
    pre_commit:
        tasks: [xlifflint]
```
- Ensures XLIFF files are linted before commits are accepted.

CI/CD Pipeline Enforcement

Run in GitHub Actions/GitLab CI:

# .github/workflows/grumphp.yml
jobs:
  lint-xliff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install --dev
      - run: ./vendor/bin/grumphp run --tasks=xlifflint

Fail the pipeline if XLIFF files violate rules.

Dynamic Configuration

Use Laravel’s config() to override ignore_patterns per environment:

// config/grumphp.php
'xlifflint' => [
    'ignore_patterns' => env('APP_ENV') === 'production'
        ? ['storage/old-translations/']
        : [],
];

Load dynamically in grumphp.yml via parameters.

Laravel-Specific Tips

Pair with Laravel Localization Packages
- Use alongside spatie/laravel-translation-loader to ensure XLIFF files align with your app’s translation structure.
- Example: Validate that all XLIFF files reference keys used in your Laravel views.

Artisan Command Integration

Create a custom Artisan command to run XLIFF linting on demand:

// app/Console/Commands/LintXliff.php
public function handle()
{
    $grumphp = new \GrumPHP\Runner();
    $grumphp->run(['--tasks' => 'xlifflint']);
}

Call via:
```
php artisan lint-xliff
```

Advanced Patterns

Schema Validation
- Enable DTD/schema checks for strict XLIFF compliance:
```
tasks:
    xlifflint:
        dtd_validation: true
        scheme_validation: true
```
- Useful for projects adhering to specific XLIFF standards (e.g., OASIS XLIFF 1.2).
Network Dependency Control
- Disable load_from_net if your CI environment restricts external requests:
```
tasks:
    xlifflint:
        load_from_net: false
```

Custom Error Handling

Extend the task to log XLIFF issues to Laravel’s log:

// app/Providers/AppServiceProvider.php
public function boot()
{
    \GrumPHP\Task\XliffLintTask::setLogger(function ($message) {
        \Log::info('XLIFF Lint: '.$message);
    });
}

Gotchas and Tips

Common Pitfalls

GrumPHP Version Mismatch
- Issue: The package supports GrumPHP 0.12–1.3 and 2.x. Using an unsupported version (e.g., 0.11 or 1.4+) may break the task.
- Fix: Pin GrumPHP in composer.json:
```
"require-dev": {
    "grumphp/grumphp": "^1.3"
}
```
Path Resolution Failures
- Issue: Older versions used __DIR__ instead of getcwd(), causing path errors in CI.
- Fix: Update to v10.2.7+ or manually set the working directory in CI:
```
# GitHub Actions
- run: cd $GITHUB_WORKSPACE && ./vendor/bin/grumphp run
```
Silent Failures
- Issue: The task may fail silently if the underlying xlifflint tool is missing or misconfigured.
- Fix: Verify xlifflint is installed in your CI environment:
```
# Example for Ubuntu
sudo apt-get install xlifflint
```
- Or use a Docker image with the tool preinstalled.
Performance with Large Files
- Issue: The package lacks optimizations for large XLIFF files (e.g., >50MB), leading to timeouts.
- Fix:
  - Split validation by language/file size in CI.
  - Use ignore_patterns to exclude non-critical files temporarily.
Namespace Confusion
- Issue: Upgrading from andersundsehr/grumphp-xliff-task may leave old namespace references (AUS\GrumPHPXliffTask\ExtensionLoader).
- Fix: Update grumphp.yml to use the new namespace:
```
extensions:
    - PLUS\GrumPHPXliffTask\ExtensionLoader
```

Debugging Tips

Enable Verbose Logging
- Run GrumPHP with debug mode to inspect task execution:
```
./vendor/bin/grumphp run --verbose --tasks=xlifflint
```
Test with a Subset of Files
- Temporarily limit triggered_by to a single file to isolate issues:
```
tasks:
    xlifflint:
        triggered_by: [path/to/test.xlf]
```
Check XLIFF File Validity
- Validate files manually using xlifflint:
```
xlifflint path/to/file.xlf
```
CI-Specific Quirks
- GitHub Actions: Ensure the xlifflint tool is available in the container. Use a custom Docker image if needed.
- GitLab CI: Cache the xlifflint binary to avoid reinstallation:
```
cache:
    key: xlifflint
    paths:
        - .xlifflint-cache
```

Extension Points

Custom Validation Rules

Extend the task by subclassing \PLUS\GrumPHPXliffTask\Task\XliffLintTask:

// app/GrumPHP/XliffCustomTask.php
class XliffCustomTask extends \PLUS\GrumPHPXliffTask\Task\XliffLintTask
{
    protected function validateFile($file)
    {
        // Add custom logic (e.g., check for specific tags)
        if (!str_contains(file_get_contents($file), '<target>')) {
            return $this->createFailure('Missing target element in '.$file);
        }
        return parent::validateFile($file);
    }
}

extensions:
    - App\GrumPHP\XliffCustomTask

Dynamic Configuration

Override task settings via Laravel’s service container:

// config/grumphp.php
'xlifflint' => [
    'ignore_patterns' => config('app.xliff_ignore_patterns'),
];

Post-Validation Actions

Trigger Laravel events or notifications after validation:

// app/Providers/AppServiceProvider.php
public function boot()
{
    \GrumPHP\Task\XliffLintTask::onFailure(function ($task, $file) {
        event(new \App\Events\XliffValidationFailed($file));
    });
}

Configuration Quirks

triggered_by vs. file_extensions
- The package uses triggered_by (not file_extensions) to define file patterns. Ensure your grumphp.yml matches:
```
tasks:
    xlifflint:
        triggered_by: [xlf, xliff]  # Correct
        # file_extensions: [xlf, xliff]
```

Grumphp Xliff Task Laravel Package