• Stars
    star
    170
  • Rank 223,357 (Top 5 %)
  • Language
    PHP
  • License
    Apache License 2.0
  • Created about 12 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

PSX is an innovative PHP framework dedicated to build fully typed REST APIs.

About

PSX is an innovative PHP framework dedicated to build fully typed REST APIs.

It helps to improve the API development process by providing the following features:

  • Fully typed controller classes
  • Client SDK generator which supports TypeScript, PHP, Java, Go
  • OpenAPI generation
  • Generate model classes based on a TypeSchema specification
  • Uses the Symfony DI container component
  • Works with Doctrine DBAL and migrations
  • Type-safe database interaction
  • Endpoint integration testing

More information about PSX at phpsx.org.

Installation

To install the framework you can simply install this demo API project.

php composer.phar create-project psx/psx .

Getting started

This repository contains already a fully working demo API build with PSX which you can use as a starting point and to better understand how PSX works. In the following we go based on the demo files through the important concepts of PSX.

Controller

A controller is the entrypoint of your app which gets invoked by the framework. A controller is a simple PHP class which contains attributes to make specific methods invokable. In the following extract we have a simple controller with a getAll and create method which gets invoked if a GET or POST request arrives at the /population endpoint s.

class Population extends ControllerAbstract
{
    #[Get]
    #[Path('/population')]
    public function getAll(?int $startIndex = null, ?int $count = null): Model\PopulationCollection
    {
        return $this->populationTable->getCollection($startIndex, $count);
    }

    #[Post]
    #[Path('/population')]
    public function create(Model\Population $payload): Model\Message
    {
        $id = $this->populationService->create($payload);

        $message = new Model\Message();
        $message->setSuccess(true);
        $message->setMessage('Population record successfully created');
        $message->setId($id);
        return $message;
    }
}

One key concept of PSX is that the arguments of your exposed controller methods are mapped to values of the incoming HTTP request, at the getAll method the $startIndex and $count parameter are mapped to a query parameter from the HTTP request, at the create method the $payload parameter is mapped to the request body.

PSX tries to automatically map each parameter to the fitting value from the HTTP request, since this is not always distinct possible you can also use attributes to explicit declare the mapping, please take a look at our documentation to see all available mapping attributes.

Since PSX uses the symfony DI container all controller classes are automatically loaded through auto-wiring. This means you can simply define at the constructor all dependencies which are needed for your controller. Please take a look at the container.php if you want to customize which classes are loaded.

SDK

One of the greatest feature of PSX is that it can automatically generate a client SDK for the API which you have build. To generate the client SDK simply run the following command.

php bin/psx generate:sdk

This writes the SDK to the output/ folder. By default, the command generates the typescript SDK. Based on the controller defined above PSX would generate the following client SDK.

const client = new Client(...);

client.population().getAll(startIndex?: number, count?: number);
client.population().create(payload: Population);

The client then contains the same schemas which are also defined at the backend but converted to TypeScript. This means you are using exactly the same schema at the backend and frontend. If you change your schema at the backend you can then regenerate the SDK and you will directly see all problems with your new schema. In this sense PSX provides similar features like tRPC but in a language neutral way.

The generate:sdk command accepts as argument a format which defines the type of SDK which is generated. The following list shows some supported formats.

  • client-go
  • client-java
  • client-php
  • client-typescript
  • spec-openapi

Model

To enable this SDK generation PSX needs to understand the structure of the incoming or outgoing JSON payload. This is done by using DTO models for every argument and return type. PSX contains a model generator which allows you to generate those models based on a TypeSchema specification. Please take a look at the typeschema.json file which contains the models for our demo API. You can generate all models using the following command s.

php bin/psx generate:model

The command writes all models to the src/Model folder. You can then use those models at the controller classes.

Service

PSX recommends to move your actual business logic into a separate service class. The controller then simply invokes methods from your service. While this is not mandatory it improves your code quality since you can easily use this service also in another context. All classes under the service/ folder are automatically loaded thus you can specify all dependencies through simple constructor injection.

Migrations

PSX uses doctrine migrations which helps to manage your database schema. To generate a new migration you can simply run s.

php bin/psx migrations:generate

This would create a new migration file at src/Migrations. You can then model your table schema at this migration file. After this you can run the migrate command to execute all needed database changes s.

php bin/psx migrations:migrate

Please take a look at the doctrine migrations project for more information how the migration system works.

Table

PSX provides a command which generates table and row classes to interact with your database in a type-safe way. This command should be executed after you have executed all your migrations.

php bin/psx generate:table

This command then writes all files to the src/Table folder.

Note in general we think that for API development an ORM is not needed, but it would be easy possible to integrate any existing ORM into PSX.

Tests

PSX provides a way to easily build an integration test for every controller endpoint. The following extract shows the test which requests the /population endpoint and simply compares the JSON payload with an existing JSON structure.

public function testGetAll(): void
{
    $response = $this->sendRequest('/population', 'GET');

    $actual = (string) $response->getBody();
    $expect = file_get_contents(__DIR__ . '/resources/collection.json');

    $this->assertEquals(200, $response->getStatusCode(), $actual);
    $this->assertJsonStringEqualsJsonString($expect, $actual, $actual);
}

Through this you can easily build integration tests for every endpoint. Please take a look at the tests/Controller/PopulationTest.php file to see the complete test case.

Components

Besides the framework PSX is build on various PHP components. These components are independent of the framework and can also be used in another context. The following list contains the most notable packages:

  • psx/api
    Parse and generate API specification formats
  • psx/schema
    Parse and generate data schema formats
  • psx/data
    Data processing library to read and write POPOs in different formats
  • psx/sql
    Generate type-safe PHP classes from your database

More Repositories

1

fusio

Open source API management platform
PHP
1,836
star
2

typeschema

TypeSchema is a JSON format to describe data models in a language neutral format
PHP
69
star
3

typeapi

TypeAPI is an OpenAPI alternative to describe REST APIs for type-safe code generation.
PHP
63
star
4

psx-schema

Parse and generate data schema formats
PHP
54
star
5

fusio-docker

Official docker container of Fusio an open source API management system
PHP
45
star
6

psx-api

Parse and generate API specification formats
PHP
33
star
7

psx-sandbox

Execute PHP code in a sandbox
PHP
13
star
8

fusio-impl

Fusio implementation
PHP
11
star
9

psx-sql

Generate type-safe PHP classes from your database
PHP
11
star
10

psx-model

Model classes based on open data specifications
PHP
9
star
11

psx-framework

Engine of the PSX framework
PHP
8
star
12

fusio-tools-electron

JavaScript
8
star
13

fusio-sample-cms

Fusio headles CMS sample app
PHP
7
star
14

fusio-apps-backend

TypeScript
7
star
15

fusio-apps-documentation

Web API documentation viewer for the PSX framework
JavaScript
5
star
16

psx-json

Read and transform JSON documents through JSON-Patch/Pointer
PHP
5
star
17

psx-openssl

OpenSsl wrapper library
PHP
5
star
18

psx-data

Data processing library to read and write POPOs in different formats
PHP
4
star
19

fusio-sdk-php

PHP
4
star
20

psx-uri

URI, URL and URN value objects
PHP
4
star
21

psx-cloudevents

Library which helps to produce and consume cloud events
PHP
3
star
22

fusio-apps-swaggerui

HTML
3
star
23

fusio-adapter-graphql

PHP
3
star
24

fusio-adapter-aws

PHP
3
star
25

fusio-adapter-laravel

PHP
3
star
26

fusio-engine

PHP
3
star
27

fusio-adapter-mongodb

PHP
3
star
28

typeschema-generator

TypeSchema code generator
Dockerfile
3
star
29

typeschema-angular-editor

TypeScript
3
star
30

psx-http

Interfaces to describe HTTP message, middleware and client implementations
PHP
3
star
31

fusio-apps-developer

Fusio developer portal app
TypeScript
3
star
32

fusio-sdk-javascript

TypeScript
2
star
33

fusio-adapter-php

PHP
2
star
34

fusio-adapter-sql

PHP
2
star
35

fusio-model

PHP
2
star
36

fusio-adapter-paypal

PHP
2
star
37

psx-cache

PSR-6 and PSR-16 implementation using the doctrine cache system
PHP
2
star
38

fusio-tools-vscode

TypeScript
2
star
39

fusio-worker-javascript

Fusio worker to execute javascript code
TypeScript
2
star
40

fusio-apps-vscode

JavaScript
2
star
41

psx-sample

PHP
2
star
42

fusio-sdk-javascript-angular

TypeScript
2
star
43

fusio-adapter-file

PHP
2
star
44

psx-datetime

PHP port of the Java JSR 310 time API
PHP
2
star
45

fusio-worker-python

Python
2
star
46

fusio-adapter-stripe

PHP
1
star
47

fusio-adapter-amqp

PHP
1
star
48

fusio-adapter-smtp

PHP
1
star
49

fusio-website

PHP
1
star
50

psx-engine-amp

PHP
1
star
51

fusio-sdk-go

Go
1
star
52

fusio-cli

PHP
1
star
53

typeschema-generator-action

GitHub action to automatically generate code based on a TypeSchema specification.
Dockerfile
1
star
54

fusio-adapter-fcgi

PHP
1
star
55

fusio-adapter-soap

PHP
1
star
56

fusio-sdk-java

Java
1
star
57

psx-dependency

Simple and fast PSR-11 compatible DI container
PHP
1
star
58

fusio-sample-angularjs

HTML
1
star
59

fusio-apps-pma

PHP
1
star
60

psx-record

Data HashMap implementation
PHP
1
star
61

fusio-docs

Fusio documentation
JavaScript
1
star
62

fusio-apps-redoc

HTML
1
star
63

sdkgen-cli

SDKgen is a powerful code generator to automatically build client SDKs for your REST API.
Go
1
star
64

fusio-sample-laravel

PHP
1
star
65

fusio-sdk-php-laravel

PHP
1
star
66

fusio-adapter-cli

PHP
1
star
67

fusio-worker-php

PHP
1
star
68

fusio-sdk-php-wordpress

PHP
1
star
69

psx-v8

Execute Javasript code via V8
PHP
1
star
70

fusio-worker-java

Fusio worker to execute java code
Java
1
star
71

fusio-adapter-util

PHP
1
star
72

fusio-adapter-gcp

PHP
1
star
73

psx-website

JavaScript
1
star
74

fusio-adapter-http

PHP
1
star
75

fusio-adapter-neo4j

PHP
1
star
76

psx-engine

Engine to support multiple web server types
PHP
1
star
77

psx-asyncapi

Model classes to generate an AsyncAPI specification in a type-safe way
PHP
1
star