Tardis Laravel Package

Getting Started

• Confirm the stack first. Tardis 0.1 requires PHP 8.3+, Laravel 13+, and Livewire 4. These are very fresh majors; if the app is still on Laravel 11/12 or Livewire 3 you cannot install. Verify php -v, composer show laravel/framework livewire/livewire before anything else.
• Treat it as experimental. v0.1.0 is an explicitly marked pre-release ("Do not use it in production"). Pin yellow-three/tardis:^0.1 and assume API breaks on future minor bumps.
• Install from the VCS repository, not Packagist:

  composer config repositories.tardis vcs https://github.com/yellow-three/tardis
  composer require yellow-three/tardis:^0.1
  php artisan tardis:install [email protected]
  php artisan tardis:doctor
  

  The install creates the first administrator with the super-admin role and prints the generated password — capture it and rotate.
• Panel lives at /admin. tardis:doctor is the first diagnostic you should run after install; use it again whenever something behaves oddly.
• First real use case: pick one existing model, create a single BREAD resource for it, and verify list/search/filters, the view page, and a full create/update round-trip before expanding to more types. Keep the first BREAD narrow so a broken resource doesn't take the panel down.

Implementation Patterns

• BREAD as JSON definitions. Resources are defined by JSON, with a builder UI, backups, per-type field views, and configurable list/view layouts. Pattern: keep the JSON in version control as code and treat builder edits as drafts to be reviewed — do not let the panel be the single source of truth for resource definitions.
• Per-type field views and list/view layouts let you tailor a resource without touching vendor code. Reach for these before considering package modifications.
• Authorization is on by default (access admin gate plus a permission tree). Map roles to permissions up front, especially for non-super-admin roles; verify each resource/action resolves correctly before adding real users.
• Plugin system (assets, routes, settings screens) is the intended extension point for cross-cutting additions. Build admin extensions as plugins rather than editing vendor files.
• Translatable content with locale tabs (EN/TR panel). For required translatable fields, every locale must be filled by default; set tardis.translation.validation to active to relax that. Decide the policy per resource early.
• Theming, menus, dashboard, media. Themes are data-driven (theme editor), menus use up/down ordering, the dashboard is widget-based, and the media library has a media picker. Use the media library rather than shipping raw uploads through your own controllers.
• Command runner and log viewer. The command runner is an allow-listed artisan runner, off by default. If you enable it, allow-list only idempotent, read-only-ish commands per role; the log viewer is safe to expose to admin roles only.
• Deploy workflow. Any time a BREAD is created or changed, re-run php artisan route:cache. Add this to deploy scripts so cached routes don't lag behind resource definitions.

Gotchas and Tips

• Pre-release API churn. The API can change before 1.0. Avoid wrapping Tardis internals in your own abstractions too tightly; keep your integration thin so a bump is a small patch, not a rewrite.
• Not on Packagist. Upgrades come from the VCS repo, so normal composer update against Packagist will not pull it. Watch RELEASE_NOTES.md and UPGRADE.md for each new build; the latter matters most between dev builds.
• Stack coupling. Laravel 13 / Livewire 4 are new; installing Tardis effectively forces those majors. Plan the Laravel/Livewire upgrade path before adopting, not after.
• route:cache after BREAD changes is mandatory. BREAD creation registers routes; a stale route cache produces 404s and missing pages. Put it in your deploy pipeline, not in a README comment.
• Required translatable fields validate in every locale by default. This is a deliberate behavior, not a bug. Relax only with tardis.translation.validation = active; otherwise authors will fight validation on fields they cannot fill.
• Menu/dashboard ordering is up/down only — no drag and drop, no nested menus. Don't design complex navigation expecting either; keep menus flat. Up/down ordering is also O(n) clicks, so plan ordering before populating.
• Command runner is a remote shell path. Default off is correct; if you turn it on, verify the allow-list is narrow and role-scoped. Do not expose it to non-super-admin roles without an explicit review.
• Install generates an admin password. Capture it at creation time (it is printed, not stored), rotate it immediately, and do not re-run tardis:install casually in shared environments.
• Debugging order: tardis:doctor → log viewer → route cache. Most "missing page" issues are stale route cache; most "auth fails" issues are permission-tree misconfiguration on non-super-admin roles.