Laravel

Installation

To install the package simply require the composer package at your Laravel project.

composer require psx/api-laravel

Make sure, that the package is registered at the bootstrap/providers.php file:

return [
    PSX\ApiLaravel\ApiServiceProvider::class,
];

Controller

The following is a simple controller which shows how to use the PSX specific attributes to describe different HTTP parameters:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Model\PostCollection;
use App\Model\Post;
use App\Model\Message;
use PSX\Api\Attribute\Body;
use PSX\Api\Attribute\Param;
use PSX\Api\Attribute\Query;

final class PostController extends Controller
{
    public function __construct(private PostService $service, private PostRepository $repository)
    {
    }

    public function getAll(#[Query] ?string $filter): PostCollection
    {
        return $this->repository->findAll($filter);
    }

    public function get(#[Param] int $id): Post
    {
        return $this->repository->find($id);
    }

    public function create(#[Body] Post $payload): Message
    {
        return $this->service->create($payload);
    }

    public function update(#[Param] int $id, #[Body] Post $payload): Message
    {
        return $this->service->update($id, $payload);
    }

    public function delete(#[Param] int $id): Message
    {
        return $this->service->delete($id);
    }
}

Internally we read all routing information from routes/web.php and combine this with the attributes at the controller. In the example we use the #[Query], #[Param] and #[Body] attribute to map different parts of the incoming HTTP request. In the controller we use a fictional PostService and PostRepository but you are complete free to design the controller how you like, for PSX it is only important to map the incoming HTTP request parameters to arguments and to provide a return type.

Generator

SDK

To generate an SDK you can simply run the following command:

php artisan generate:sdk

This reads alls the attributes from your controller and writes the SDK to the output folder. At first argument you can also provide a type, by default this is client-typescript but you can also select a different type.

client-php
client-typescript
spec-openapi

Model

This bundle also provides a model generator which helps to generate DTOs to describe the incoming and outgoing payload s.

php artisan generate:model

This commands reads the TypeSchema specification located at resources/schema/typeschema.json and writes all model classes to app/Dto. In general TypeSchema is a JSON specification to describe data models. The following is an example specification to generate a simple Student model.

{
  "definitions": {
    "Student": {
      "description": "A simple student struct",
      "type": "struct",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "age": {
          "type": "integer"
        }
      }
    }
  }
}

Configuration

The package needs the following psx.php configuration:

return [

    'base_url' => '',

    /*
     * Optional username or app key of your sdkgen.app account
     */
    'sdkgen_client_id' => env('SDKGEN_CLIENT_ID'),

    /*
     * Optional password or app secret of your sdkgen.app account
     */
    'sdkgen_client_secret' => env('SDKGEN_CLIENT_SECRET'),

];

The base_url is the absolute url to your API so that you don’t need to provide the base url at your client SDK.

The sdkgen_client_id and sdkgen_client_secret are credentials to the SDKgen app.

Community

Feel free to create an issue or PR in case you want to improve this package.