Api Laravel Package

Getting Started

psx/api is a PHP library that parses TypeAPI specifications and generates code from them — most commonly client SDKs and models. It is not an OpenAPI tool, and the spec format is not interchangeable.

Minimal setup:

composer require psx/api

Then look here, in this order:

1. bin/psxapi (or vendor/bin/psxapi) — the CLI is the fastest way to understand what the package actually does. Run vendor/bin/psxapi --help and inspect the subcommands before reading any source.
2. src/Parser/ — the TypeAPI parser, which turns typeapi.json into an in-memory Api model (operations, schemas, parameters).
3. src/Generator/ — the built-in generators (client, model, markdown, etc.). This is where you'll extend.
4. examples/ and the test suite — they show the exact class names and invocation patterns, which shift between releases.

First use case: you have a REST API described by a TypeAPI spec (yours or a vendor's) and you want a typed PHP client instead of hand-rolled Guzzle calls.

vendor/bin/psxapi generate --help
# then something like:
vendor/bin/psxapi generate client typeapi.json --output=./src/Sdk

Treat the exact flags as illustrative — confirm them against --help for your installed version, because the CLI surface has changed across releases.

Implementation Patterns

1. Spec-first client generation (the primary workflow). Keep typeapi.json in the repo next to the code that consumes it. Generate the client into a dedicated directory (src/Sdk/ or generated/), add a composer script, and regenerate on every spec change:

{
  "scripts": {
    "sdk:generate": "psxapi generate client api/typeapi.json --output=src/Sdk"
  }
}

This gives you a repeatable, diffable contract rather than a static client that drifts.

2. Programmatic parsing for tooling and validation. You don't have to use the CLI. Load the parser directly to inspect the spec inside your own code — useful for building linters, route registries, or doc generators:

use Psx\Api\ApiManager;

$manager = new ApiManager();
$api = $manager->getApi(file_get_contents('api/typeapi.json'), 'application/json');

foreach ($api->getOperations() as $operation) {
    printf("%s %s\n", $operation->getMethod(), $operation->getPath());
}

(Check src/ApiManager.php for the exact constructor and getApi() signature in your version — the API has been refactored more than once.)

3. Model/DTO generation and hydration. Generate plain value objects from the schema definitions, then hydrate them either via psx/data or your own mapper. Keeping models dumb and transport-agnostic pays off if you later swap the HTTP layer.

4. Custom generators. Built-in generators are usually GeneratorInterface implementations. When you need output the package doesn't ship (e.g. a PHP enum for a specific schema, or a framework-specific controller stub), implement the interface and either register it in the CLI or invoke it from a small build script. This is the intended extension point — don't fork the generator you want to tweak slightly.

5. Transport wrapping. Generated clients typically know nothing about auth, base URLs, retries, or logging. Wrap the generated client in your own thin service that injects a configured HTTP client and middleware. This keeps regeneration safe: your custom logic lives outside the generated tree.

6. CI contract gate. In CI, regenerate into a temp directory and diff against the committed output. If they differ, the spec changed without the SDK being updated — fail the build. Pair this with a spec validation step so malformed typeapi.json fails fast, before generation.

7. Server-side use. The parser model is also usable to drive routing or request validation in a PSX application (or any framework, with glue). This is less common than client generation but is the natural fit if you're already in the PSX ecosystem.

Gotchas and Tips

• TypeAPI ≠ OpenAPI. There is no built-in converter. If your upstream publishes OpenAPI, you need a separate translation step or you're using the wrong tool. Read the TypeAPI spec once before you start; it's deliberately small.
• Small project, moving target. 37 stars and zero dependents means you are effectively the only integration tester. Pin an exact version in composer.json, read the source when docs are thin, and expect breaking changes on minor bumps. Budget time for upgrades.
• Class names drift between versions. ApiManager, parser class names, and Generator signatures have changed. When an example from a blog post doesn't compile, check src/ rather than assuming the example is right.
• Terse parser errors. A malformed spec often surfaces as a vague exception. Validate the JSON/schema structure independently (or against a known-good TypeAPI example) before blaming the parser.
• Never edit generated files. They get overwritten. Put custom behavior in a wrapper class or a subclass, and keep the generated tree either committed-and-diffed or excluded via .gitattributes/.gitignore — pick one and be consistent.
• PSR-4 alignment. Generated namespaces must match your autoload config. If generated classes 404 at runtime, it's almost always a namespace/output-path mismatch, not a generator bug.
• PHP version constraints. Check composer.json for the minimum PHP version; older releases target older runtimes, and the newest ones may need 8.1+.
• Auth and base URL live outside the spec. Don't expect the generator to handle tokens or environment-specific hosts. Inject them at the transport layer.
• Runtime vs. build-time. Prefer build-time generation for production code (type safety, no parsing cost). Use runtime parsing only for tooling, docs, or dynamic discovery.
• Debugging generation. When output looks wrong, dump the parsed Api model first (operations, schemas) — the bug is usually in the spec interpretation, not the template. Only then dig into the generator.
• Extension points to know: the parser (via ApiManager), the generator interface, and the model classes (Api, Operation, Schema). Those three are where 90% of customizations happen.