Installer Plugin Laravel Package

Product Decisions This Supports

• Standardizing Laravel project scaffolding: Bundle reusable files (e.g., .env.example, phpunit.xml, webpack.mix.js) into internal metapackages to ensure consistency across all Laravel projects. Reduces "works on my machine" issues by eliminating manual setup.
• Accelerating developer onboarding: Automate the installation of boilerplate configurations (e.g., Docker, Homestead, Tailwind) during composer install, cutting onboarding time by 20–40% for new hires or open-source contributors.
• Modularizing environment-specific configurations: Package dev/staging/prod-specific files (e.g., docker-compose.ci.yml, homestead.json) as metapackages, enabling zero-config environment switching via Composer commands.
• Reducing technical debt from custom scripts: Replace ad-hoc Bash/PHP scripts for file replication with version-controlled, maintainable metapackages. Handlers enable safe updates (e.g., renaming deprecated files like app/Console/Kernel.php → app/Console/CommandScheduler.php).
• Build vs. buy for internal tools: Justify not reinventing wheel for tools like:
  • A "Laravel SaaS Starter Kit" metapackage with preconfigured queues, caching, and logging.
  • A "Company Template" metapackage enforcing coding standards (e.g., PSR-12, custom PHPDoc blocks).
• Roadmap prioritization: Invest in Composer-based deployment over npm/yarn for PHP-heavy projects where file replication is a bottleneck (e.g., monorepos, microservices). Aligns with Laravel’s Composer-first philosophy.

When to Consider This Package

• Look elsewhere if:

  • Your team primarily uses npm/yarn or Go modules—this is PHP/Composer-specific.
  • You need advanced file merging (e.g., 3-way diffs for config files). This plugin overwrites by default; use laravel/envoy or git merge for complex conflicts.
  • Laravel’s vendor:publish suffices for your needs (e.g., publishing config files). This plugin is for non-publishable files (e.g., scripts, Docker configs).
  • Your project lacks Composer plugin familiarity—requires dev effort to write handlers for custom logic.
  • You’re building a public package with broad adoption (0 stars, untested in production).
  • Active maintenance is critical: Last release was 2022; fork if this becomes core to your roadmap.
  • Permissions are highly restrictive: While v1.2.3 fixes issues, test thoroughly in shared hosting or CI environments (e.g., GitHub Actions with storage/ permissions).

• Adopt if:

  • You manage 10+ Laravel projects with shared scaffolding needs (e.g., a design system, API clients).
  • Your team uses Composer for core dependencies and wants to extend it for file-based workflows.
  • You need lightweight, version-aware file deployment (e.g., updating tailwind.config.js across projects).
  • You’re building internal developer tools (e.g., a "project starter kit") where customization is acceptable.
  • Laravel’s vendor:publish is insufficient for your use case (e.g., replicating non-config files like Dockerfile or Makefile).

How to Pitch It (Stakeholders)

For Executives: "This plugin lets us automate Laravel project setup—like a ‘starter kit’—directly via Composer. Instead of developers manually copying .env files or Docker configs, we bundle them in reusable packages. This cuts onboarding time by 30% and ensures every project starts with the same, secure baseline. It’s low-risk (MIT-licensed) and integrates with our existing Composer workflows, so no new tools are needed. For example, we could create a ‘Company Template’ metapackage that all new projects inherit from, reducing errors and speeding up development."

For Engineering: *"The plugin extends Composer to replicate files from metapackages into our project root. Key benefits for Laravel:

• Handlers: Custom logic for file updates (e.g., renaming deprecated files like app/Console/Kernel.php during upgrades).
• Version awareness: Track changes between package versions (e.g., update tailwind.config.js when upgrading a dependency).
• Laravel integration: Pair with composer.json scripts to trigger artisan config:clear or cache:clear post-install. Tradeoffs:
• Requires dev effort to create handlers for complex logic (e.g., conditional replication).
• Overwrites files by default—risky for shared directories like config/ or resources/. Mitigate with handlers or by restricting to non-conflicting files (e.g., Dockerfile, README.md). Ideal for: Internal tools, project templates, or environments where scaffolding is repetitive. Not for core Laravel files (use vendor:publish instead)."*

For Developers: *"Think of this as Composer for files. Instead of:

cp -r ~/templates/.env.example ./  # Manual and error-prone

We define a metapackage in composer.json:

{
  "require": {
    "company/template-metapackage": "1.0.0"
  }
}

And boom—all your .env, docker-compose.yml, and scripts are installed automatically. Handlers let you add logic, like:

// Rename a deprecated file during updates
public function postFileCreationCallback(string $projectFilename) {
    if (str_contains($projectFilename, 'old-script.php')) {
        rename($projectFilename, str_replace('old-', '', $projectFilename));
    }
}

Pro tip: Use this for non-Laravel files (e.g., Docker, CI configs) and pair with vendor:publish for Laravel configs."*