Tomato Flutter Laravel Package

Getting Started

The published description is still the Composer placeholder ("your package description will go here"), so treat the repository as the only documentation. You will learn more in ten minutes from composer.json, the service provider, config/, routes/, the command classes in src/, and stubs/ than from any blog post. Budget the first hour as source-reading.

Minimal path on an existing Laravel app with Flutter already chosen as the client:

1. Verify the baseline first. Check the package's composer.json constraints against your PHP and Laravel versions — a successful composer require is not proof the generators run on your runtime. Confirm Sanctum (or your token driver) works for a web client before adding this package; don't debug two unknowns at once.
2. Pin the version. composer require tomatophp/tomato-flutter:1.0.8. There is no changelog discipline to protect you from a patch that changes emitted Dart, so float nothing.
3. Publish interactively. Run php artisan vendor:publish without a tag, read the list, then re-run with the tag you saw. Tag names vary across TomatoPHP packages; guessing wastes time. Expect config, possibly stubs, possibly migrations.
4. Migrate and clear caches. php artisan migrate if migrations landed, then php artisan optimize:clear. Published config is invisible under a cached config — this is the single most common "it didn't install" false alarm.
5. Map the surface. php artisan route:list --path=api shows the endpoints your Flutter app will call — that list is your mobile API contract. php artisan list | grep -i flutter shows the generator command you actually drive day to day.

Read in this order: config/tomato-flutter.php (output paths, auth driver, stub locations, enabled modules) → routes/ → the generator command class → stubs/. Read the Dart templates before generating anything; they determine naming conventions, pagination envelopes, and error shapes, and those are cheap to fix once and expensive to fix after a mobile dev has built screens against them.

First use case: one vertical slice. Token login, list one resource, show one record, create one record, from a Flutter app pointed at php artisan serve over your LAN. Do not generate twenty resources on day one.

Implementation Patterns

Treat generation as a build step, not a wizard. The loop is: change a model or migration → re-run the generator → dart format → dart analyze → commit. If regeneration depends on someone remembering, the client drifts from the backend within two sprints. Wire it into a script, and ideally a CI job that fails when regenerating produces a diff.

Pick one lane for generated Dart and stay in it. Either commit the generated client (right when mobile devs don't run PHP, or you need reproducible builds) or gitignore it and generate in CI (right for a monorepo). Never mix — hand-editing a generated file means the next generation pass silently reverts it, discovered at the worst moment.

Keep auth outside the generated tree. Token storage, refresh, logout, and 401→re-login handling belong in a Dart service file you own, which the generated client imports. Generated code calls into it; it never contains it. That's the difference between "regenerate and move on" and "regenerate and re-apply six patches."

Parameterise the base URL at build time. --dart-define=API_BASE_URL=... rather than a baked-in constant, so one generated client serves local, staging, and production. If the package's config writes a URL into the output, override it in your config layer instead of editing the artifact.

Customise through stubs, not patches. Copy the stub you need into your app's own stub path, point the package config at it, edit there. Vendor patches vanish on composer update, and vendor:publish --force will happily overwrite stubs you customised in place.

Drive settings from the panel, not from code. If you already run tomato-settings and friends, put branding, feature flags, and app config there and trigger generation from the admin panel. The package is designed to be configured; forking it converts a dependency upgrade into a merge project.

Guard the contract deliberately. Once a build ships, the generated endpoints are public. Decide who owns breaking changes and how they're versioned before the first release and write it down — a scaffolding package that regenerates freely can change a response envelope without anyone noticing until a user reports a blank screen.

Record what you regenerated per bump. A short internal changelog noting which resources you regenerated on each upgrade and what you diffed. Future-you will not remember, and "which of our twenty resources did that patch touch" is not a question to answer by reading Dart.

Gotchas and Tips

• v1.0.8 has no release notes — the changelog is a bare compare link. Before any bump, read v1.0.7...v1.0.8 yourself. If the diff touches stubs/, regenerate into a scratch directory and diff the output before merging. For a code-generation package, a patch release can still change emitted Dart.
• Config cache blinds you. Published config and config edits do nothing under config:cache. Reach for optimize:clear whenever behaviour "doesn't change after install."
• vendor:publish --force overwrites custom stubs. It bites twice: during setup, and months later when someone re-publishes to "fix" something. Keep your stubs in your own path and commit them immediately so any overwrite is a loud diff.
• Route collisions and CORS masquerade as network errors. If you already expose /api/* for a SPA, check the package's prefix in route:list and adjust in config. Then remember a physical device hitting your laptop over LAN is a different origin than localhost — set SANCTUM_STATEFUL_DOMAINS and CORS accordingly, or lose an afternoon to a "connection failed" that is really a rejected preflight.
• Generated-code drift is silent. Anything you want to survive regeneration must live in a non-generated file that the generated one imports. Adopt this rule on day one; retrofitting it once hand-edits accumulate is painful.
• Debug generation with git diff, not logs. Snapshot the output directory (git status, git diff --stat) before and after — a precise file list beats any log line. If the command supports a dry-run or --pretend, use it in CI so drift fails the build instead of surprising a tester.
• The command classes and stubs are the intended extension points for changing naming and response shapes. Prefer config plus subclassing over composer patch-style hacks — the latter is unmaintainable and invisible to the next developer.
• Low adoption and a stale release date are adoption facts, not opinions. 5 stars, 0 dependents, nothing since November 2023. Measure your exit path (how many endpoints you'd hand-write to leave) rather than assuming it's cheap, and keep the integration spike behind one real resource so the decision stays reversible.