README

Turn your Laravel API routes into a complete, importable Postman Collection — docs, examples, tests, environments, and one-command push — with zero manual annotations.

php artisan postman:sync

That's it. The package scans every API route, reads your controllers and FormRequest classes, and writes a Postman Collection v2.1 (with embedded docs and test scripts), per-stage environment files, and an OpenAPI document — then, with --push, syncs it straight to your Postman workspace.

Why

Keeping a Postman collection in step with a growing API is tedious and always out of date. This package makes the collection a build artifact: re-run one command and your routes, request bodies, auth, examples, docs, and tests regenerate deterministically. Add 10 new endpoints and --push appends just those — without clobbering the manual edits your team made in Postman.

Features

• 🔎 Automatic route scanning — every GET/POST/PUT/PATCH/DELETE, apiResource, and resource; derives version, group, controller, and middleware.
• 🧬 Reflection-based analysis — finds each controller's FormRequest and reads its rules(); no annotations required.
• 🧾 Typed request bodies + examples — required|email|min:8|in:…|confirmed|nullable|file… mapped to types and realistic example values, including nested/wildcard keys.
• 🔐 Auth detection — auth:<guard> → Bearer {{guard_token}}; collection-level auth with per-request overrides; public routes set noauth.
• 📦 Postman Collection v2.1 — folder-grouped, fully variable-driven ({{base_url}}, :id path vars) — no hardcoded hosts or secrets.
• 📚 Docs in Postman — endpoint summary, field table, and example responses embedded in each request's Docs tab (plus folder/collection descriptions).
• 🧪 Generated test scripts — status / response-time / JSON assertions, login-token capture into the environment, and validation/CRUD stubs.
• 🌱 Environment files — one per stage (local/staging/production) with secret-typed guard tokens.
• 📜 OpenAPI 3.0.3 — openapi.json generated alongside.
• 🚀 One-command push — --push uploads to the Postman API with incremental merge (append new, regenerate changed, preserve unchanged + manual edits) or --fresh full replace.
• 🛟 Never breaks your build — closures, missing FormRequests, and bad controllers degrade gracefully with warnings; exits 0.

Requirements

Installation

composer require bhaveshsoni26/laravel-postman-sync

The service provider auto-registers via package discovery. Publish the config:

php artisan vendor:publish --tag=postman-sync-config

Not on Packagist yet? Install from a local path repository — see INSTALLATION.md for the one-time repositories setup.

Quick start

# Generate collection + environments + openapi.json (into storage/app/postman/)
php artisan postman:sync

+---------------------+-------+
| Metric              | Value |
+---------------------+-------+
| Routes Found        | 164   |
| Requests Generated  | 164   |
| Warnings            | 0     |
| Files Written       | 5     |
+---------------------+-------+
Synced Successfully

Import storage/app/postman/collection.json and an environment file into Postman, fill in the token variables, and send.

What it generates

storage/app/postman/
├── collection.json                   # Postman Collection v2.1 (docs + test scripts embedded)
├── openapi.json                      # OpenAPI 3.0.3
├── local.postman_environment.json    # one per configured stage
├── staging.postman_environment.json
└── production.postman_environment.json

Command reference

Push to Postman

POSTMAN_API_KEY=PMAK-xxxx
POSTMAN_COLLECTION_ID=xxxx   # set to update an existing collection
POSTMAN_WORKSPACE_ID=xxxx    # optional, used when creating

php artisan postman:sync --push
# Pushed to Postman (merge): added 10, updated 2, unchanged 152, orphaned 0 [12345-abc]

Incremental merge appends new routes, regenerates changed ones, and leaves unchanged requests — including manual edits to their docs/tests — untouched. Use --fresh to overwrite the whole collection.

Configuration

Key options in config/postman-sync.php:

'api_prefix'      => 'api',                 // routes to scan
'output_path'     => storage_path('app/postman'),
'base_url'        => env('APP_URL').'/api', // seeds {{base_url}}
'default_guard'   => 'sanctum',             // collection-level auth
'guard_tokens'    => [],                    // guard => token var override
'environments'    => ['local', 'staging', 'production'],
'generate_tests'  => true,
'capture_login_token' => true,
'postman' => [
    'api_key'       => env('POSTMAN_API_KEY'),
    'collection_id' => env('POSTMAN_COLLECTION_ID'),
    'sync_mode'     => 'merge',             // merge | replace
    'prune_orphans' => false,
],

Full configuration reference and a multi-guard (CRM-style) example are in INSTALLATION.md.

How it works

RouteScanner ─► RequestAssembler ─► CollectionBuilder ─┐
   (ControllerScanner + Validation/Auth/Example/        ├─► collection.json
    Response extractors)                                 │   environment.json
                                ─► EnvironmentGenerator ─┤   openapi.json
                                ─► MarkdownGenerator ────┤   (+ docs in request descriptions)
                                ─► OpenApiGenerator ─────┤
                                ─► TestScriptBuilder ────┘
                                ─► PostmanSyncService ─► CollectionMerger ─► PostmanApiClient  (--push)

A one-directional pipeline of immutable DTOs; each stage is interface-backed and independently tested.

Testing

composer test     # Pest
composer stan     # PHPStan level max
composer lint     # Pint --test

All Postman API calls go through Laravel's Http facade and are mocked with Http::fake() — the test suite needs no real API key or network.

Contributing

Issues and PRs welcome. Please run composer test && composer stan && composer lint before submitting. New code uses declare(strict_types=1) and Sorbet-style full type hints; tests are written in Pest.

License

MIT.