Getting Started

Minimal Steps

Installation Add the package to your project via Composer:
```
composer require slowprog/composer-copy-file
```
Ensure composer.json includes the package under require.
Basic Configuration Define a copy-file.json configuration file in your project root (or specify a custom path in composer.json):
```
{
  "copy-file": {
    "src": "path/to/source/file",
    "dest": "path/to/destination/file"
  }
}
```
Example: Copy a .env.example to .env during installation:
```
{
  "copy-file": {
    "src": "env.example",
    "dest": "env"
  }
}
```
First Use Case Run composer install or composer update. The package will automatically copy files as defined in copy-file.json after installation completes.

Implementation Patterns

Common Workflows

Environment-Specific Files Use the package to copy .env files or database configurations based on the environment:

{
  "copy-file": [
    {
      "src": ".env.local",
      "dest": ".env",
      "when": "dev"
    },
    {
      "src": ".env.production",
      "dest": ".env",
      "when": "prod"
    }
  ]
}

Trigger environment-specific copies via Composer scripts:

"scripts": {
  "post-install-cmd": [
    "@php -r \"if (getenv('APP_ENV') === 'dev') { shell_exec('composer copy-file --env=dev'); }\""
  ]
}

Conditional Copies Use when to control file copying based on conditions (e.g., OS, PHP version):

{
  "copy-file": {
    "src": "windows-config.ini",
    "dest": "config.ini",
    "when": "win"
  }
}

Post-Install Hooks Integrate with Laravel’s post-install-cmd or post-update-cmd scripts:

"scripts": {
  "post-install-cmd": [
    "Illuminate\\Foundation\\ComposerScripts::postInstall",
    "@copy-file"
  ]
}

Custom Scripts Extend functionality by creating custom Composer scripts:
```
composer copy-file --src=custom/src --dest=custom/dest --force
```

Integration Tips

Laravel Mix/Valet/Laravel Forge: Use the package to deploy configuration files during composer install on shared hosting or CI/CD pipelines.
CI/CD Pipelines: Trigger file copies as part of your deployment workflow (e.g., GitHub Actions, GitLab CI).
Monorepos: Copy shared configurations or assets between projects during installation.

Gotchas and Tips

Pitfalls

File Overwrites By default, the package skips copying if the destination file already exists. Use --force to overwrite:
```
composer copy-file --force
```
Or configure in copy-file.json:
```
{
  "copy-file": {
    "src": "file.txt",
    "dest": "file.txt",
    "force": true
  }
}
```
Permission Issues Ensure the destination directory is writable. Use chmod or configure permissions in your deployment scripts:
```
chmod -R 775 storage/
```

Path Resolution Paths in copy-file.json are relative to the project root. Use absolute paths if needed:

{
  "copy-file": {
    "src": "/absolute/path/to/source",
    "dest": "/absolute/path/to/dest"
  }
}

Composer Script Order Ensure @copy-file runs after Laravel’s post-install-cmd if dependencies are required:

"scripts": {
  "post-install-cmd": [
    "Illuminate\\Foundation\\ComposerScripts::postInstall",
    "@copy-file"
  ]
}

Debugging

Dry Run: Test configurations without copying files:
```
composer copy-file --dry-run
```
Verbose Output: Enable debug mode for detailed logs:
```
composer copy-file --verbose
```
Check Configuration: Validate copy-file.json syntax. Use a JSON validator if errors occur.

Extension Points

Custom Commands Extend the package by creating a custom Composer plugin or command to add pre/post-copy hooks.

Dynamic Configurations Load copy-file.json dynamically from a database or API during installation:

// In a custom Composer script
$config = json_decode(file_get_contents('https://api.example.com/config'), true);
file_put_contents('copy-file.json', json_encode($config));

Template Processing Combine with packages like php-template to render files with placeholders before copying:

{
  "copy-file": {
    "src": "config.template.php",
    "dest": "config.php",
    "template": true
  }
}

Event Listeners Listen to Composer events (e.g., post-install) to trigger custom logic alongside file copies. Example in composer.json:
```
"scripts": {
  "post-install-cmd": [
    "@php artisan config:copy",
    "@copy-file"
  ]
}
```

Composer Copy File Laravel Package