Devtools Laravel Package

Getting Started

SeviaFlow DevTools is a require-dev companion package for SeviaFlow projects. It ships Artisan tooling for three jobs: reporting application/diagnostic status, discovering Eloquent models and existing SeviaFlow Resources, and scaffolding new Resources from discovered models. It depends on SeviaFlow Core only — you do not need the UI or API packages installed for it to work.

composer require --dev seviaflow/devtools:^0.1@beta

Verified beta targets are Laravel 12 / PHP 8.2+ and Laravel 13 / PHP 8.3+. Laravel 11 and PostgreSQL are explicitly unverified — treat anything outside the verified matrix as unsupported until you've smoke-tested it yourself.

Where to look first:

1. php artisan list and filter for the SeviaFlow command namespace. The release notes describe the command categories but not exact signatures, so enumerate them rather than guessing.
2. The docs at https://seviaflow.io/docs/0.1/devtools/ for setup and command reference for this exact beta.
3. config/ after publishing, if the package exposes config (check php artisan vendor:publish --list).

First use case: run the diagnostics/status command against a local app to confirm DevTools can see Core and resolve your models, then run discovery to see what it finds, then generate a Resource for a single low-risk model (a Post, Category, or similar) and read the generated file end to end before generating anything else. That one file tells you more about the generator's conventions than the docs will.

Implementation Patterns

Discovery → generate → review, in that order. Discovery output is the cheapest way to catch models the tool can't see (non-standard namespaces, abstract base classes, models without tables). Fix discovery gaps before generating, otherwise you'll hand-write Resources for models the generator silently skipped and end up with two conventions in one codebase.

Treat generated Resources as a reviewed artifact, not build output. Commit them. Diff them on regeneration. The generator's sensitive-field safeguard is a heuristic first pass — it reduces the chance of scaffolding a Resource over password, remember_token, API keys, or token columns, but it cannot know about your custom accessors, $appends, encrypted casts, or JSON columns with embedded secrets. Every generated Resource deserves a manual pass over $fillable/$guarded, hidden/visible, and appended attributes before it merges.

Generate into one namespace. Pick a single location for generated Resources and stick to it. Mixing generated and hand-written Resources in the same directory makes it impossible to tell which files are safe to regenerate later.

Use diagnostics as a cheap CI smoke check. The status/diagnostic commands are a fast way to fail a pipeline when Core is missing, misconfigured, or a Resource references a model that no longer exists. Run them before your test suite in the dev/CI job (where dev dependencies are installed), not in the production build.

Keep the dependency genuinely dev-only. Because it's require-dev, production installs (composer install --no-dev) won't have the commands — which is what you want. Don't script DevTools commands into deploy pipelines or release steps; they will fail on any image built without dev dependencies.

Pair it with Core, not the full stack. If your project also uses the SeviaFlow UI or API packages, generated Resources may reference contracts or base classes those packages provide. Confirm the generated code resolves with only Core installed before you assume the output is portable across editions.

Onboard the team through the tool. The most reliable documentation for a package at this maturity is a short contributing note: install command, the discovery command, the generate command, and "review the generated file against this checklist." That survives beta churn better than prose.

Gotchas and Tips

Pin the beta and commit the lock file. ^0.1@beta plus a committed composer.lock is the only sane posture — the release notes state APIs and compatibility may change before stable. Avoid dev-main or unbounded constraints in a shared repo.

Stability flags bite in nested dependency graphs. The explicit @beta flag on the require line is usually enough, but if your root minimum-stability is stable and Core's own constraints are pre-release, you may need prefer-stable or a stability entry. If Composer refuses to resolve, read the constraint error before reaching for minimum-stability: dev — that's a repo-wide change you probably don't want.

Laravel 11 is not just "untested" — it's unverified. Don't assume it works because the API surface looks similar. If you're on 11, either upgrade or accept that failures are yours to debug. Same for PostgreSQL: discovery may behave differently against non-MySQL drivers, and generated Resources may carry driver-specific assumptions about column types.

The safeguard is not a security boundary. The single highest-risk failure mode for this package is a developer treating a generated Resource as "safe by default" and shipping it. Audit for: $appends on models, accessors that compute from sensitive fields, relationship names that expose related models implicitly, and casts that decrypt or unserialize. Generate, then read.

Commands vanish outside dev installs. This is correct behavior, but it produces confusing "command not found" errors for anyone who ran composer install --no-dev locally or is inside a production-like container. Check composer install --dev and that the package is in require-dev before debugging the package itself.

Clear caches after install and after upgrades. Package discovery and config caching are the usual suspects when commands don't appear. php artisan config:clear and php artisan package:discover resolve most first-run problems.

Regenerate, don't hand-edit, when the model changes — but expect conflicts. If you've customized a generated Resource, regeneration will overwrite it. Either keep customizations in a separate class that extends the generated one, or accept that regeneration is a one-time scaffold and hand-maintain thereafter. Decide this per-Resource before you start editing.

Look for publishable stubs/config as the extension point. If the package exposes generator stubs or config via vendor:publish, customize there rather than editing generated output — that's the only customization that survives upgrades. Verify what's publishable in this beta before assuming the extension surface is stable.

Check upstream before filing bugs. At 0.1.0-beta.1 with an explicit "APIs may change" caveat, some rough edges are known. Search the SeviaFlow issue tracker against the exact beta version before spending a day on a discovery edge case.