Download the PHP package bedita/php-sdk without Composer

BEdita API PHP SDK

BEdita PHP Official PHP SDK

Prerequisites

• PHP >= 8.1
• Composer

Install

To install the latest version of this library, run the command below:

Basic Usage

Init BEditaClient

Instantiate BEditaClient with API url and API key. This will usually be done via factory methods like ApiclientProvider::getApiClient() that will read from environment variables and/or configuration files.

Init Logger for custom log

You can activate a detailed request/response log to file of API calls using initLogger() method. This will be also usually performed by factory methods like ApiclientProvider::getApiClient().

Request Headers

Some headers are handled as default in API calls:

• Accept as application/vnd.api+json to use JSON-API format
• Content-Type as application/json when a request body is set
• Authorization with Bearer {token} if a JWT token has been set
• X-Api-Key with the key passed to contructor

Upon every API call you can add new headers or overwrite defaults in the $header array argument (see below).

Authenticate and tokens

To retrieve or set JWT tokens you can:

• use authenticate(string $username, string $password) method to perform a classic username/password authentication
• use setupTokens() to set JWT tokens, retrieved from previous authenticate or other methods, for subsequent calls

On every subsequent API call JWT token will be used in Authentication header and expired token response will also be handled via refresh token automatically by the SDK.

Direct API calls and utility methods

In order to use BEdita 4 API you have generally two options:

1. use direct API calls invoking POST/GET/PATCH/DELETE HTTP methods using correspondent get()/post()/patch()/delete() methods making sure that path, query string, body and headers are correctly populated;
2. use the utility methods explained below like save, addRelated and others to simplify settings and obtain a clearer code.

Read objects and resources

You can use getObjects(string $type = 'objects', ?array $query = null, ?array $headers = null) to retrieve a list of objects by type, getObject(int|string $id, string $type = 'objects', ?array $query = null, ?array $headers = null) to get a single object by unique identifier and type.

Examples:

You can also use get(string $path, ?array $query = null, ?array $headers = null) to make an explicit GET API call, specifying the complete request path. This is the correct way to call special endpoints like /home or /status for instance (GET calls that are not used to retrieve objects o resources).

When you need to get relationships related data, you can you getRelated(int|string $id, string $type, string $relation, ?array $query = null, ?array $headers = null).

Save objects and resources

You can use save(string $type, array $data, ?array $headers = null) method: this is the standard method to use to create or update objects or resources in BEdita 4. Please note that the payload is made of object attributes, without the need to specify a data.attribute section that you must use when dealing with direct POST o PATCH API calls.

Example:

save and saveObject use internally patch(string $path, mixed $body, ?array $headers = null) (when saving an existing object) or post(string $path, mixed $body, ?array $headers = null) (when saving a new object).

If you like to use them directly:

Delete and restore data

Soft delete

Soft delete puts object into the trashcan. You can trash an object with delete(string $path, mixed $body = null, ?array $headers = null) or deleteObject(int|string $id, string $type).

Restore data

Data in trashcan can be restored with restoreObject(int|string $id, string $type).

Hard delete

Hard delete removes object from trashcan. You can remove an object from trashcan with remove(int|string $id).

Working with relations

Add related objects

You can add related objects using addRelated(int|string $id, string $type, string $relation, array $data, ?array $headers = null).

Replace related objects

replaceRelated(int|string $id, string $type, string $relation, array $data, ?array $headers = null) is handy to replace related objects.

Note: internally addRelated uses post and replaceRelated uses patch. Both will call /:type/:id/relationships/:relation

Remove related objects

Related objects can be removed using removeRelated(int|string $id, string $type, string $relation, array $data, ?array $headers = null).

Upload

The easiest way to create a new media object with file upload is to call a POST with file content as body.

Example of image upload:

A new object of type images will be created having image.png file as related stream resource. If you need instead to handle more low level actions via streams read the paragraphs below.

Upload streams

Use upload(string $filename, string $filepath, ?array $headers = null) to perform a POST /streams/upload/:filename and create a new stream with your file.

Note: if you don't pass $headers argument, the function uses mime_content_type($filepath).

Create media from stream

You create a media object from a stream with createMediaFromStream(string $streamId, string $type, array $body). This basically makes 3 calls:

• POST /:type with $body as payload, create media object
• PATCH /streams/:stream_id/relationships/object modify stream adding relation to media
• GET /:type/:id get media data

Thumbnails

Media thumbnails can be retrived using thumbs(int|null $id, $query = []).

Usage:

Schema

You can get the JSON SCHEMA of a resource or object with schema(string $type).

Get info of a relation (data, params) and get left/right object types using relationData(string $name).