Laravel Project Initializator Laravel Package

Getting Started

ronasit/laravel-project-initializator is a dev-only scaffolding package: instead of hand-assembling a new Laravel app (Docker, CI, README, env files, base config), you describe the desired end state in an initializer config and let php artisan project:init materialize it.

Minimal path:

1. composer require --dev ronasit/laravel-project-initializator
2. Publish the package config/assets so the initializer manifest lives in your repo and is version-controlled like any other code.
3. Populate the manifest with the files you want copied verbatim and the stubs you want rendered with placeholders (project name, namespace, domain, etc.).
4. Run php artisan project:init on a clean, throwaway branch and review git diff.

Where to look first: the published initializer config. It is the single source of truth — every file that appears in a new project should be traceable to an entry there. If something is missing from a generated project, the answer is almost always "it isn't listed in the config" rather than a bug in the package.

First use case: onboarding a new repo. Clone, composer install, php artisan project:init, and you have .env, .env.testing, .env.ci-testing, CI workflow, Docker compose and the app skeleton in one command instead of a wiki page of manual steps.

As of 0.3.3, the init flow creates and configures .env.ci-testing and .env.testing alongside the standard .env. Previously these were a manual post-init step; if your docs tell people to cp .env.example .env.testing, that instruction can be deleted.

Implementation Patterns

Config-as-manifest. Treat the initializer config as declarative infrastructure. Two categories of entries: files copied byte-for-byte (Dockerfiles, workflows, editor config) and stubs rendered through placeholder substitution (README, composer.json name/description, config/app.php tweaks, env files). Keep the distinction explicit so a reviewer knows whether editing a target file is a template change or a code change.

Placeholders over hardcoding. Define tokens once (project name, namespace, author, DB name) and reference them everywhere. Anything typed twice will drift.

Env file triad. Keep .env.example, .env.testing and .env.ci-testing as committed examples in the template, and let init materialize the real ones. Since 0.3.3 the package handles the last two for you, so the pattern is: add a new env key to all three example files in the same PR that adds the feature. Missing one produces a generated project that passes locally and fails in CI.

CI integration. A typical workflow: checkout, install PHP deps, run php artisan project:init --no-interaction (or an equivalent force flag), then php artisan migrate and the test suite with .env.ci-testing supplying DB credentials and app key. This gives you a permanent smoke test that the template is not broken — run it on a schedule, not just on PRs to the template.

Extending. New shared infrastructure (a queue worker, a Sentry config, a Pint preset) is a two-line change: drop the file into the template directory, add it to the manifest. Keep template-only concerns out of app/ so the initializator and application code never fight.

Version pinning. It is a require-dev dependency whose output is the starting point of every new repo. Pin an exact version in composer.json and bump deliberately, after generating a project and diffing against the previous output.

Gotchas and Tips

• It overwrites. Running init against an existing checkout with local edits will clobber files. Always run it on a fresh clone or a clean branch, and use git diff as the review mechanism — the diff is the change set.
• Env files are gitignored. Only the *.example variants are committed. If a teammate's .env.testing looks wrong, check the example file, not the generated one.
• .env.testing vs .env.ci-testing. PHPUnit loads .env.testing; CI scripts typically source .env.ci-testing. Getting an APP_KEY into the CI env is mandatory — encryption/session tests fail with a confusing "No application encryption key" error otherwise. The 0.3.3 change is exactly the fix for that class of first-run failure, so verify the generated files actually contain a key (or that CI injects one) rather than assuming.
• Interactive prompts block CI. Init asks questions. Confirm the non-interactive path works before wiring it into a pipeline; a hung job with no output is the usual symptom.
• Leftover placeholders. After a run, grep -rn '{{' . — an unreplaced token in a rendered file usually means the file was listed as "copy" instead of "render", or the token name differs by a character.
• Config caching. Editing the initializer config while a cached config exists is a silent no-op. php artisan config:clear after changing it.
• Debugging. Use -v/-vv on the artisan command to see which files are being processed; if a file is silently skipped it is nearly always an unmatched glob or a path relative to the wrong root.
• Upgrade check. On every package bump, generate a project with the old version and the new one into two directories and diff them. That catches new default files (like the env files in 0.3.3) that you may want to document or intentionally exclude.