Unisys Api Laravel Package

Getting Started

Unisys API is not a library you require into an existing app — it's an opinionated Laravel skeleton (application template) for standing up JSON APIs. Treat it like laravel/laravel but API-first.

Minimal steps to evaluate it:

composer create-project weareunite/unisys-api my-api
cd my-api
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan serve

Where to look first, in order:

1. composer.json — confirm the pinned Laravel major version. This tells you whether the skeleton is current or stuck on an old framework. Given the repo has 1 star and 0 dependents, expect it to lag behind Laravel's latest.
2. routes/api.php — the whole point of the package; this defines the API surface and versioning convention.
3. app/Http/Controllers/ and app/Http/Resources/ (or Transformers/) — reveal the response-shaping pattern the author prefers (Eloquent API Resources vs. Fractal vs. hand-rolled arrays).
4. config/auth.php + composer.json guards — determine whether auth is Sanctum, Passport, JWT (tymon/jwt-auth), or something custom. This is the single biggest integration decision.
5. app/Exceptions/Handler.php — check how validation errors, 404s, and 500s are rendered as JSON. If this is customized, the skeleton has an opinion about error envelopes.

First use case: scaffold a versioned, token-authenticated REST resource end-to-end — e.g. a posts CRUD — using whatever conventions ship in the repo. If that flow feels natural, the skeleton is doing its job; if you fight it at every step, you're better off with a vanilla Laravel install plus a couple of packages.

Implementation Patterns

Because this is a starter template, "usage" means copying and extending its conventions, not calling its methods.

1. Scaffold resources with the shipped pattern. If the skeleton uses API Resources, follow it:

// app/Http/Resources/PostResource.php
public function toArray($request)
{
    return [
        'id'    => $this->id,
        'title' => $this->title,
        'body'  => $this->body,
        'meta'  => ['created_at' => $this->created_at->toIso8601String()],
    ];
}

// Controller
return new PostResource(Post::findOrFail($id));

Don't mix in Fractal if the skeleton uses API Resources — consistency with the template is what makes it worth adopting.

2. Keep controllers thin, push logic to services/actions. Even if the skeleton doesn't ship a service layer, this is the natural evolution. Controllers validate via FormRequests and delegate:

public function store(StorePostRequest $request, CreatePostAction $action)
{
    return (new PostResource($action->execute($request->validated())))
        ->response()
        ->setStatusCode(201);
}

3. Authentication flow. Whatever the skeleton ships (Sanctum is most likely), wire it once and reuse:

• POST /api/login → issue token
• Protect routes with the shipped middleware group
• Add a logout route that revokes tokens if the guard supports it

4. Version your routes from day one. If routes/api.php isn't already segmented, split into routes/api/v1.php and load it with a prefix. Retrofitting versioning later is painful.

5. Exception-driven JSON errors. Centralize error shaping in the Handler (or bootstrap/app.php on Laravel 11+) so every endpoint returns the same envelope:

$this->renderable(function (ValidationException $e) {
    return response()->json(['errors' => $e->errors()], 422);
});

6. Use the skeleton as a template, not a dependency. For new projects, composer create-project. To reuse across many projects, fork it into an internal template repo and composer create-project yourorg/unisys-api so you can patch it independently of the upstream.

Gotchas and Tips

• Don't composer require it into an existing app. It ships an app skeleton (bootstrap, config, routes). Requiring it just dumps unused files or conflicts with your existing structure. Use create-project or fork.
• Budget time for an audit. With 1 star and 0 dependents, this is effectively an unmaintained personal template. Read every file in app/, config/, and composer.json before building on it, and check the last commit date against your target Laravel version.
• Pin your PHP and Laravel versions deliberately. If the skeleton pins laravel/framework:^9.0 and you're starting a new project in 2024+, either accept the older stack or plan an upgrade. Upgrading a full skeleton from L9→L11 touches bootstrap, middleware, and config files — not trivial.
• Verify the lock file behavior. Run composer update --dry-run after scaffolding. Skeleton composer.json files frequently have overly broad constraints (^8.0|^9.0) that can resolve to unexpected versions.
• .env drift. Check .env.example against config/. Skeletons often ship keys the config never reads, or config that reads keys absent from .env.example — leading to silent null behavior (e.g. cache driver, mail from-address, queue connection).
• Migration ordering. Run php artisan migrate:fresh on a clean DB early to validate migrations are ordered correctly and don't collide with a shipped users migration.
• CORS and rate limiting. API skeletons usually ship config/cors.php and a RateLimiter in RouteServiceProvider. Confirm both match your actual client origins and throttling needs before going to prod.
• Debugging responses. Add php artisan route:list --path=api to your workflow — the fastest way to see the real registered surface when a route 404s but exists in the file (usually a middleware group or prefix mismatch).
• Extension point to lean on: the exception handler and base controller. Those two files are where a skeleton's opinion is most visible; adapt them to your team's conventions before writing new endpoints, or you'll end up with two response formats.
• Fallback plan. If the audit turns up stale dependencies or missing tests, the pragmatic move is to keep the conventions (route structure, resource classes, error envelope) and rebuild on a fresh laravel new --api install. You lose nothing but a composer.lock.