innovatif/restfulserver-extension

Extension for RestfulServer; adds APIID and fluent capatibilities

dev-master 2026-04-23 12:04 UTC

Requires

• php: ^8.2
• silverstripe/framework: ^5
• silverstripe/restfulserver: dev-144-cleanup-hooks as 3.1
• silverstripe/versioned: ^2
• symbiote/silverstripe-queuedjobs: ^5
• tractorcow/silverstripe-fluent: ^7

Requires (Dev)

• cambis/silverstan: ^2.1
• phpstan/extension-installer: ^1.0
• phpstan/phpstan: ^2
• phpunit/phpunit: ^9.5
• squizlabs/php_codesniffer: ^3.7
• wernerkrauss/silverstripe-rector: ^1.2

BSD-3-Clause

• Werner M. Krauß

README

This module handles APIID (a UUID for each DataObject) and i18n support for REST calls in SilverStripe.

configuration with APIId...

To add an APIID, i18n support for REST calls and support for remote file handling via URLs, you need to add the following configuration to your YAML config file:

My\Namspace\Model\MyAPIClass:
  extensions:
    apiid: Innovatif\RestfulServerExtension\Extension\ApiId
    synclock: Innovatif\RestfulServerExtension\Extension\SyncLock # allows to lock objects for API sync
    autopublish: Innovatif\RestfulServerExtension\Extension\AutoPublish # automatically publishes objects after API sync
    fluentapi: Innovatif\RestfulServerExtension\Extension\FluentAPIUpdate #for handling translations; needs fluent applied on the DataObject
    filehandling: Innovatif\RestfulServerExtension\Extension\RemoteFileHandling #for handling files with URLs
    autopublish: Innovatif\RestfulServerExtension\Extension\AutoPublish #for automatically publishing new items
    generateurlsegment: Innovatif\RestfulServerExtension\Extension\GenerateURLSegment #for generating the urlsegement in translations; schema is <Title>-<APIID>

Note: FluentAPIUpdate extension also needs fluent and throws an exception, if the class doesn't have fluent applied.

checking required extensions on dev/build

On dev/build, the module will check if the required extensions are installed. If not, it will throw an error message.

The required extensions can be configured with the Innovatif\RestfulServerExtension\Extension\DevBuild.required_extensions config variable.

Requirements

This module requires a specific branch of silverstripe/restfulserver (version 3.1) which includes necessary hooks and cleanup. See silverstripe/restfulserver issue #144 for details.

To use this in your project, add the following to your composer.json:

{
    "repositories": [
        {
            "type": "git",
            "url": "https://github.com/wernerkrauss/silverstripe-restfulserver.git"
        }
    ],
    "require": {
        "silverstripe/restfulserver": "dev-144-cleanup-hooks as 3.1"
    }
}

Handling Translations in REST calls

TBD

Remote File Handling

To handle remote files via URLs, you can use the RemoteFileHandling extension. It will automatically download the file from the provided URL, check its hash, and save it to the DataObject.

Unfortunately, there is some manual work required to set the file relation on the DataObject.

The file relation must not have the same name as the File or DataObject relation.

We need some helper methods in the DataObject to handle remote file handling. The relation name must not be the same as the File or DataObject relation name, otherwise it will not work.

Remote File Handling

The RemoteFileHandling extension can be configured to process remote files via a queue instead of direct processing. This is configured on the owner class that uses the extension.

# Example: Enable queue for the Event page
My\Namespce\Page\Event:
  use_queue: true

When enabled, remote files will be enqueued using QueuedJobService (if available). By default, this is set to false.

You can configure the root folder for REST uploads by adding the following to your YAML configuration:

SilverStripe\Security\Member:
  rest_upload_folder: 'your-custom-folder/'

The default is ru/.

By default an upload folder for each member is created in that configured folder. If you want to disable this for specific members, add a method public function updateCanCreateRESTFolder(): bool to your Member object.

Example for a DataObject with remote file handling

class Event extends DataObject
{
    private static string $table_name = 'Event';

    private static array $db = [
        'Title' => 'Varchar',
        'Description' => 'Text'
        // other fields
    ];

    private static array $has_many = [
        'EventImages' => Image::class,
    ];
    
    private static array $owns = [
        'EventImages' => Image::class,
    ];

    private static array $extensions = [
        RemoteFileHandling::class,
    ];
    
    private static array $api_fields = [
        'Title',
        'Description',
        'Images', // this will call the getImages() method
    ];

    /**
     * Returns the file URLs for the Images relation.
     * This method uses the RemoteFileHandling extension to get the file URLs as a json array, e.g.
     * ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
     * 
     * Can be called via API as `Images` field.
     *
     * @return string
     */
    public function getImages(): string
    {
        return $this->getFileUrls($this->EventImages());
    }
    
    
}