spiral/writeaway

PHP API server for Writeaway editor

v0.4.0 2022-03-14 05:46 UTC

Requires

• php: >=8.0
• ext-imagick: *
• doctrine/collections: ^1.6
• spiral/cycle-bridge: ^1.0
• spiral/framework: ^2.9
• spiral/helpers: ^1.0

Requires (Dev)

• laminas/laminas-diactoros: ^2.4
• phpunit/phpunit: ^9.5
• spiral/code-style: ^1.0
• spiral/roadrunner: ^1.9

MIT

README

License:

MIT License (MIT). Please see LICENSE for more information. Maintained by Spiral Scout.

TODO

• add tests for public services

Usage

• Register WriteawayBootloader in the App

Note that it must be registered and after RouterBootloader.

• Implement MetaProviderInterface
• WriteawayCommandBootloader can be added if you want to have a reset command.

Note that it uses TokenizerBootloader so it must be registered before CommandsBootloader.

• WriteawayViewsBootloader can be added if you want use ready views bundle.

API Endpoints:

List Images

GET or POST writeaway:images:list to fetch a full list of available images.

Example response:

{
  "status": 200,
  "data": [
    {
      "id": "unique-id",
      "src": "image1.png"
    },
    {
      "id": "unique-id",
      "thumbnailSrc": "image2-th.png",
      "src": "image2.png"
    }
  ]
}

Possible image fields:

Upload Image

POST writeaway:images:upload to upload an image file.

Example request:

image - FormData file

Example response:

{
  "status": 200,
  "data": [
    {
      "id": "unique-id",
      "src": "image1.png"
    }
  ]
}

For possible image fields see the previous endpoint.

Delete Image

POST or DELETE writeaway:images:delete to delete a particular image

Example request:

{
  "id": "unique-id"
}

Example response:

{
  "status": 200
}

Get Piece

GET or POST writeaway:pieces:get to fetch a particular piece by its id and type.

Example request:

{
  "id": "unique-id",
  "type": "piece-type"
}

If no pieces found, a new one wil be created. id is a unique value across all pieces.

Example response:

{
  "status": 200,
  "data": {
    "id": "unique-id",
    "type": "piece-type",
    "data": {
      "key": "value",
      "key...": "value..."
    }
  }
}

In case if validation errors the example response will be:

{
  "status": 400,
  "errors": {
    "field-name": "error-message",
    "field-name...": "error-message..."
  }
}

Get Pieces in bulk

GET or POST writeaway:pieces:bulk to fetch a particular pieces by theirs id and type.

Example request:

{
  "pieces": [
    {
      "id": "unique-id",
      "type": "piece-type"
    },
    {
      "id": "unique-id",
      "type": "piece-type"
    }
  ]
}

Example response:

{
  "status": 200,
  "data": [
    {
      "id": "unique-id",
      "type": "piece-type",
      "data": {
        "key": "value",
        "key...": "value..."
      }
    },
    {
      "id": "unique-id",
      "type": "piece-type",
      "data": {
        "key": "value",
        "key...": "value..."
      }
    }
  ]
}

Not found pieces will be ignored.

In case if validation errors the example response will be:

{
  "status": 400,
  "errors": {
    "field-name": "error-message",
    "field-name...": "error-message..."
  }
}

Save Piece

POST writeaway:pieces:save to save a particular piece by its id and type.

Example request:

{
  "id": "unique-id",
  "type": "piece-type",
  "data": {
    "key": "value",
    "key...": "value..."
  }
}

If no pieces found, a new one wil be created. id is a unique value across all pieces.

Example response:

{
  "status": 200,
  "data": {
    "id": "unique-id",
    "type": "piece-type",
    "data": {
      "key": "value",
      "key...": "value..."
    }
  }
}

In case if validation errors the example response will be:

{
  "status": 400,
  "errors": {
    "field-name": "error-message",
    "field-name...": "error-message..."
  }
}

Components

Meta

Meta is a structure designed to represent current piece editor. While this package knows nothing about real app actors, \Spiral\Writeaway\Service\Meta\ProviderInterface is given - a developer can bind it to a more rich implementation, so the meta will contain the real user's id, label and time. Example:

{
  "id": "some user id",
  "label": "some user label, such as name",
  "time": "current date time string"
}