Composer Publish Plugin Laravel Package

Getting Started

Start by installing the plugin into your project via Composer:

composer require spiral/composer-publish-plugin

The plugin activates automatically once installed—no extra configuration required for basic usage. Its core value emerges when your own packages declare publishing instructions in their composer.json. Create a custom package (e.g., myorg/app-config) and include a extra.publish section specifying resource mappings:

{
  "extra": {
    "publish": {
      "config/myapp.php": "config/myapp.php",
      "assets/": "public/vendor/myapp/"
    }
  }
}

After requiring this package in a Laravel (or other Composer-based) app, run composer install—files are automatically copied to target locations.

Implementation Patterns

• Declarative resource management: Define all publishing rules in extra.publish inside your package’s composer.json. Maps source paths (relative to package root) to destination paths (relative to application root).
• Framework-agnostic usage: Though inspired by Spiral, it works equally well in Laravel, Symfony, etc. For Laravel, publish config files to config/, migrations to database/migrations/, or stubs to resources/stubs/.
• Idempotent publishing: On each composer install/update, files overwrite existing targets, ensuring consistency across environments (ideal for CI/CD). Avoid manual post-install scripts like php artisan vendor:publish.
• Multiple package support: Use multiple packages with their own publish sections—files from each are merged safely (latter packages may overwrite former, but plugin logs conflicts).

Gotchas and Tips

• Paths are relative to app root: Destination paths assume your current working directory is the application root, not the vendor package root. Verify paths work in local dev before CI.
• No confirmation prompts: publishing is silent unless errors occur. Add -vvv to Composer commands for verbose logs to debug missing files.
• Overwrites without warning: Existing files are overwritten. Consider versioning configs (e.g., config/myapp.v1.php) or using publish hooks for migrations.
• No build-time filtering: Unlike Laravel’s vendor:publish, this plugin doesn’t support tags or profile filtering. All declared resources always publish.
• Legacy maintenance: Last release in 2020—ensure compatibility with modern Composer versions (tested up to Composer 2.0). Consider forking if active support is needed.
• Extension point: Implement custom logic by listening to Spiral\ComposerPublish\PluginEvents::POST_PUBLISH events via Composer plugins.