Demo Kit Laravel Package

Getting Started

capell-app/demo-kit is a demo-content companion for the Capell CMS stack. Treat it as scaffolding for a local or staging Capell install, not as application code.

1. Inspect before installing. Open the package's composer.json, README, and src/ on the tagged release (v1.1.0-beta.51). Confirm the Laravel/PHP constraints and whether the package declares capell-app/capell (or admin/frontend packages) as dependencies or expects them to already be present.
2. Install as a dev dependency so it never ships to production:

   composer require --dev capell-app/demo-kit:1.1.0-beta.51
   

   Pin the exact beta tag — this package iterates quickly and the changelog for beta.49 → beta.51 is only a compare link, with no described changes.
3. Publish what it exposes. Run php artisan vendor:publish --tag=... (check php artisan vendor:publish --provider="Capell\\DemoKit\\..." for the actual tags). Config, seeders, and any demo assets/views are the usual publishables.
4. Find the entry point. Run php artisan list and look for a demo install/seed command. If none exists, look for a seeder class in the published files and call it explicitly:

   php artisan db:seed --class="Capell\\DemoKit\\Database\\Seeders\\DemoKitSeeder"
   

5. First use case: fresh local database → migrate:fresh → run the demo installer → log into the Capell admin and browse the generated pages/blocks. That gives you a populated reference site to learn the CMS's block and page model from.

If the README does not document a command, read the service provider's boot()/register() methods first — that is where commands, publishes, and migrations are wired.

Implementation Patterns

Local bootstrap / onboarding. The highest-value use is a repeatable "demo site in one command" flow for new team members:

php artisan migrate:fresh --seed
php artisan capell:demo:install   # verify actual command name
php artisan storage:link

Wrap this in a Composer script or a Makefile target so the whole team gets an identical baseline.

Test fixtures. Because the kit produces realistic pages and blocks, it can stand in for hand-built fixtures in feature tests. Seed it inside a RefreshDatabase test case, or narrow it down by calling individual seeders if the full set is slow. Keep the full-kit seeding in a separate, slower test suite rather than every test.

Reference implementation, not a runtime dependency. Read the published block/page definitions and copy the patterns into app/ or your own seeders. Depending on a beta demo package at runtime couples your content model to upstream churn.

Ephemeral demo environments. Suitable for a Docker entrypoint or CI preview job: install Capell, run the demo kit, expose the admin. Always guard with an environment check (app()->environment('local', 'staging')) so an accidental production deploy cannot re-seed content.

Upgrade workflow for a pinned beta. Record the exact tag in composer.json with a comment in the README. On each bump, diff the vendor directory or the GitHub compare link, then re-run migrate:fresh and the installer. Do not assume seeders are idempotent across versions.

Gotchas and Tips

• Thin release notes. v1.1.0-beta.51 ships with only a GitHub compare URL. Before bumping, read the actual commit list and diff; a two-beta jump in a 1.1.0-beta.x line can quietly change seeder class names, block slugs, or asset paths.
• Beta churn. Pin the exact version. Using ^1.1@beta or dev-main will pull unreviewed content-model changes into your local environment without warning.
• Destructive seeding. Demo seeders commonly truncate or duplicate content. Never run them against a database containing work you care about; keep a separate local DB name for demo installs.
• Non-idempotency. Re-running the installer may create duplicate pages or throw unique-constraint errors. Prefer migrate:fresh + install over re-running the seeder on an existing database.
• Publish drift. Once config, views, or seeders are published, later package updates will not overwrite them. Delete and re-publish, or diff manually, when upgrading. Note the published files in your upgrade checklist.
• Media and storage. Demo content often references images. If thumbnails 404, check php artisan storage:link, the configured disk, and whether the package expects seeded media records or just files.
• Caches. After install, clear config, route, and view caches; stale compiled views are a common cause of "the demo pages look wrong."
• Production safety. Add an explicit guard in your deploy scripts and consider dont-discover in composer.json if the service provider registers anything globally that you do not want in production.
• Extension points. The usual three are available: publishable config, publishable views/blocks, and overridable seeder classes. Prefer subclassing or copying seeders over editing vendor files so upgrades stay clean.
• Debugging. If the installer command is missing after composer require, confirm package discovery ran (composer dump-autoload) and that the provider is not excluded via extra.laravel.dont-discover. Check storage/logs/laravel.log for seeding failures — they are often swallowed when run inside a command.