Laravel Postman Laravel Package

Getting Started

• Install as a dev dependency: composer require phpsa/laravel-postman --dev. It never touches the request lifecycle, so there's no production blast radius — the worst case is a wasted afternoon, not a broken deploy.
• Publish the config and confirm the command signature before assuming anything:
  1. php artisan vendor:publish (list tags and confirm the postman tag exists in this version — the tag name has moved across majors).
  2. php artisan list | grep -i postman to get the real command name and flags. Don't trust a blog post; run it.
  3. Generate once into a scratch file and open it in an editor before importing. You're checking three things: is the base URL a variable or a hardcoded localhost, are requests grouped into folders by prefix, and does the auth block match what your app actually expects.
  4. Import → Files into Postman, confirm {{base_url}} resolves, fire one request.
• First use case: pick a single resourceful controller with a FormRequest, one auth-protected route, and one route with a URI parameter. That one slice exercises the three inference paths — URL/method from the route, body from validation rules, auth header from config. If those three come out right, the rest of your API probably will too. If they don't, you've found your ceiling in an hour instead of a week.
• Look first at the published config (include/exclude rules, base URL resolution, default headers), then the generated JSON. Read the JSON critically — the package's job is to produce something plausible, and "plausible" is not "correct".

Implementation Patterns

• Config is the source of truth; the JSON is an artifact. Every inclusion rule, header, and auth setting belongs in config/postman.php. Anything you hand-edit in the collection is erased on the next run. If you find yourself patching the output, you've found a config gap or a route that shouldn't be exported.
• Commit the generator, not the generated file — usually. The pragmatic default: a Composer script ("postman": "php artisan export:postman") plus a CI step that publishes the collection as a build artifact. Committing the JSON gives you reviewable drift in PRs; a CI artifact keeps the repo clean but makes drift invisible. Pick deliberately and write the decision down, because the wrong choice surfaces six months later as "why is our Postman collection three API versions stale?"
• Filter by prefix and audience. Export api/v1/* into one collection and api/v2/* into another. One 800-request collection is unreviewable, slow to import, and produces diffs nobody reads. Separate collections per domain (billing, users, admin) also make it clear who owns what.
• Move validation into FormRequests — this is the highest-leverage habit with this package. Body shape is inferred from rules, so inline $request->validate([...]) in a controller produces thin or empty request bodies. Extracting rules to a FormRequest is good practice anyway and directly improves the generated output. Same logic for typed controller signatures and API Resources: the more explicitly your code declares its shapes, the better the export.
• Auth once, inherited everywhere. Set a collection-level bearer token referencing {{token}} from the environment. Rotating a local token then means editing one variable, not N requests — and it means the collection keeps working after a teammate's token expires.
• Generate per environment. The base URL is baked at generation time. Either emit a Postman environment with {{base_url}} and let developers override locally, or run the generator per environment in CI. Teams that skip this ship a collection where every staging tester hits localhost.
• Pair it with the router, not against it. This package derives everything from Route:: definitions, so it fits naturally into a workflow where the route file is the API contract. Compared to an attribute/annotation-based OpenAPI generator (Scramble, Scribe), you get zero-annotation adoption on an existing app but noticeably less schema fidelity — no oneOf, no realistic examples, weaker response modelling. Choose accordingly: great for "give QA something to click", weaker as a public API contract.
• Seed data or the collection 404s. Model-bound route parameters become raw IDs in the path. Add a "create then capture" request at the top of each folder that POSTs a record and saves the ID into a collection variable ({{user_id}}), then reference that variable in downstream requests. This is the difference between a collection reviewers can actually run and one they give up on.

Gotchas and Tips

• v5.2.0 has no descriptive changelog — just a v5.1.0...v5.2.0 compare link. Read the diff before pinning, and after any upgrade diff the generated collection.json against the previous run. A silent change to how bodies or auth blocks are emitted is a quiet diff in a file your team imports, not a loud error. Never bump this package in the same PR as another dependency.
• Routes can be missing, and you won't get an error. The command boots the app in a CLI context, so routes behind feature flags, App::environment() guards, or conditional registration may not exist. Before blaming the package, run php artisan route:list | grep <path> — if it isn't there, the generator can't see it either.
• Closures and unconventional controller methods produce thin output. The package needs something to introspect. Prefer invokable and resourceful controllers with typed signatures; if a route has to be a closure, exclude it and define the request by hand.
• Validation rules are not a schema. sometimes, nullable, required_if, arrays-of-objects, and Rule:: objects all translate imperfectly. Expect to hand-tune a handful of requests. If it's more than a handful, keep a documented list of "requests we patch post-export" rather than silently accepting wrong bodies.
• Generated files are artefacts — treat them that way. Don't hand-edit in place without an escape hatch. If you must maintain edits, generate to a temp path and merge into a hand-maintained collection. Add the output path to .gitattributes as linguist-generated so JSON diffs stop appearing in code review.
• Uploads and non-JSON bodies rarely come out usable. Multipart, file fields, raw XML — define these manually and exclude the routes from the include list so you don't get duplicate broken copies regenerated every time.
• Environment drift is the most common silent failure. Base URL baked at generation time means staging testers hit localhost. Confirm the collection uses {{base_url}} and ship an environment file alongside it.
• Debugging a missing request: run one unfiltered export into a scratch file. Nine times out of ten the route is being caught by an over-eager exclude pattern matching a name you didn't anticipate — not missing from the router.
• Determinism erodes trust. If successive runs on the same commit produce noisy diffs (ordering, generated IDs), reviewers stop reading them and the collection drifts. Check for this in your first week; if the output isn't stable, don't commit it.
• Extension points: the published config (paths, headers, auth, include/exclude) is the supported surface. Anything deeper — custom generators, per-route annotations — is version-sensitive. Re-read vendor/phpsa/laravel-postman after each major bump rather than following tutorials written for v3 or v4. Keeping the integration shallow also means swapping to Scramble or Scribe later is a contained change, not a rewrite.
• Ownership: assign the generated collection to the backend/API platform team, not individual feature teams. It's low-cost but non-zero maintenance, and it must track Laravel majors — budget a small upgrade task per major, because past majors have moved config keys and command signatures.