Setup Bundle Laravel Package

Getting Started

• Check the constraint before anything else. This package’s last release is November 2017, which lands squarely in the Laravel 5.4/5.5 era. Read composer.json in the repo and look for illuminate/support, illuminate/console, and illuminate/database ranges — they will almost certainly be ~5.4 or ~5.5. On anything from Laravel 6 onward, composer require orkestra-cms/setup-bundle will fail with a dependency resolution error, and --ignore-platform-reqs will not help because the code itself calls APIs that were removed.
• Where to look first, in order: composer.json (constraints and auto-discovery block) → the service provider in src/ (which commands it registers) → the Console/ commands themselves (that’s where the actual setup logic lives) → config/ → README. For a “setup bundle”, the service provider is thin and the commands are the product.
• Know what it actually is. Despite the marketing text calling it a “Laravel package”, the repo name and description (“Bundle allowing easy setup of new Symfony projects”) suggest a Symfony heritage. Verify which framework the src/ code actually targets before wiring anything. If the classes extend Symfony\Component\Console\Command rather than Illuminate\Console\Command, nothing here will run under Laravel as-is.
• Realistic first use case: treat this as a reference implementation, not a dependency. Spin up a throwaway Laravel 5.5 project (or the oldest supported LTS your CI still has), install it there, and run its installer command end-to-end so you can see the intended order of operations: publish config → publish assets → migrate → seed → environment check. Read src/Console/* side by side with the output.
• The move for a modern project: copy the pattern into your own app/Console/Commands/AppInstallCommand.php, not the package. You get the orchestration order and safety rails without the 2017 constraint lock-in.

Implementation Patterns

• Model the installer as a single idempotent Artisan command. The package’s value is the sequence: $this->call('vendor:publish', ['--tag' => 'orkestra-config', '--force' => $this->option('force')]), then vendor:publish for assets, then migrate, then db:seed --class=OrkestraSeeder. Recreate that as php artisan app:install in your own code.
• Make every step repeatable. Guard each publish with $this->confirm(...) unless --force is passed. Guard the seeding with firstOrCreate keys so re-running on a half-installed environment doesn’t duplicate rows. This is the single biggest robustness gap in 2017-era installers.
• Do environment checks up front, as a separate command. A php artisan app:check-env that asserts: required PHP extensions, APP_KEY present, storage/ and bootstrap/cache/ writable, DB connection reachable (DB::connection()->getPdo() inside a try/catch), and any Orkestra-specific config keys non-null. Wire it as the first step of app:install, exit non-zero on failure, and reuse it in your deploy pipeline.
• Wrap Orkestra access behind your own service. Do not call Orkestra classes directly from controllers or jobs. Inject an OrkestraSetup interface (bound to an adapter) via the constructor. When the upstream API changes or you fork the package later, you touch one binding in a service provider instead of every call site.
• Resolve from the container. app(OrkestraSetup::class), constructor injection, or $this->app->make(...) — never new. This is what lets you swap to a fake in tests and lets config changes take effect without rebuilding the class.
• If you genuinely install the package on 5.5, use package discovery. Add "extra": {"laravel": {"providers": [...], "aliases": [...]}} to the vendor manifest or copy it into your config/app.php if the package predates auto-discovery. Do not mix both — double-registration produces duplicate command listings.
• Put all configuration in config/orkestra.php and reference via config('orkestra.*'). Keep per-environment setup (DB name, asset CDN, seeding mode) out of the installer code and out of the published config’s hardcoded defaults.
• Test against a mock, not the real Orkestra internals. In setUp(), $this->app->instance(OrkestraSetup::class, Mockery::mock(...)) and assert on the sequence of methods your installer calls (publish → migrate → seed). Asserting on the package’s internal state couples your tests to abandoned code.

Gotchas and Tips

• It will not install on modern Laravel. This is the first and biggest pitfall. Confirm the illuminate/* ranges in composer.json. Anything from Laravel 6 up is incompatible by constraint and by API. Don’t burn time fighting Composer; if you need the behavior, vendor the installer pattern into your own command.
• “Bundle” means Symfony terminology leaking into a Laravel package. Read the source to see which Command base class is used. If src/Console/* extends Symfony\Component\Console\Command, the entire thing is a Symfony bundle, and every Laravel-flavored assumption in the description (artisan, vendor:publish, facades) will be wrong.
• Abandoned = no security patches. No releases since 2017, zero stars, zero dependents. If any of it executes in a production request path, you have a supply-chain risk you can’t patch. Keep it strictly to build-time / install-time if you use it at all.
• Publish tags are silent no-ops. php artisan vendor:publish --tag=<wrong-tag> prints nothing and does nothing. Grep src/ for publishes( to get the exact tags the package registers before you script anything.
• Published files drift. Once published, config and migrations are copies in your repo. A vendor upgrade will never update them. Diff published config against the package’s config/ whenever you touch the version constraint, and diff your own copied installer against src/Console/ when you fork it.
• config:cache staleness. After editing published config, run php artisan config:clear locally and php artisan config:cache in deploy. A stale cache is the number-one “the package ignores my settings” cause, and it applies doubly here because 2017 installers typically read config at boot.
• Migration collisions and missing down(). Before running migrate, grep the package’s migrations for table names that might collide with your app (users, settings, media). Then verify each migration’s down() actually drops what up() created — 2017-era migrations frequently shipped an empty down(), which makes local rollbacks painful.
• Pin the minor and read before updating. Even if you get it working on 5.5, use "^1.0" from composer.json and read the CHANGELOG before any composer update. Deploy with composer install --no-dev --optimize-autoloader; only update deliberately on a branch.
• Debugging tools: php artisan about to confirm the provider is loaded (Laravel 9+; on 5.5 use php artisan route:list or a tinker $app->getLoadedProviders()), php artisan tinker to poke the resolved command, and Log::channel('single') for the installer’s own output. If a facade throws “class not found”, run composer dump-autoload.
• Uninstall cleanly if you trial it. Remove the provider from config/app.php, delete config/orkestra.php, delete any published migrations and assets, and run php artisan config:clear. Orphaned published config from a dead installer is a classic source of “why is this value wrong” six months later.
• Extension points, in order of upgrade safety: config keys → events/listeners the package fires → container rebinding of its classes → Artisan command macros → subclassing its internals. Given the package is abandoned, treat subclassing as forking: copy the file into your namespace and stop depending on the vendor copy entirely.