Installation and Configuration

Installation and Configuration

The SDK expects a specific directory layout in order to locate and load custom applications correctly. This section explains the default structure, how it can be customized, and what each folder is used for.

Default Structure

By default, the SDK and all custom applications are placed inside a shared directory, typically:

[path-to-jobrouter-installation]/custom_applications

A typical setup might look like this:

custom_applications/
├── example-app/
│   └── index.php
├── another-app/
│   ├── index.php
│   └── helper.php
├── vendor/
│   └── ... (installed SDK files via Composer)
├── composer.json
└── composer.lock

Explanation

• example-app/ – a custom application. The folder name determines the application's URL.
• example-app/index.php – the entry point of your application. Must return a closure as defined by the SDK.
• vendor/ – contains all Composer-installed packages, including the SDK.
• composer.json – defines dependencies, including the SDK package.
• composer.lock – records exact versions of all dependencies to ensure consistency and reproducibility

Installing the SDK

To install the SDK using Composer, open a terminal in the custom_applications/ directory and run:

composer require jobrouter/sdk

The package can be found in the official JobRouter GitHub Repository.

This will generate the vendor/ directory and the composer.json / composer.lock files if they don’t exist yet.

Important

Please note: The SDK must be installed in the same directory as your custom applications — otherwise, it won't be available to them at runtime and dependency loading will fail.

Composer not installed?

Composer is a dependency manager for PHP. If it’s not installed on your system, follow the official installation guid at https://getcomposer.org/download/

Once installed, you can run composer commands from your terminal to manage packages like the SDK.

Important

Please note: On some systems, you may need to use php composer.phar instead of composer, depending on how it was installed.

Composer not allowed?

In the case that installing Composer on the server is not allowed due to company security policies, you can download and install the SDK on another machine and then copy and paste the vendor/ directory and the composer.json / composer.lock files manually to the custom_applications directory. You have to do that every time you update the SDK.

URL Mapping

The folder name of your custom application is part of the URL used to access the application:

http(s)://[jobrouter-url]/custom-applications/example-app/

Each application is isolated by its directory and can include additional PHP files or subfolders as needed.

Important

Please note: The path in the URL - custom-applications - is always the same and written with a dash instead of an underscore. Do not confuse it with the name of the directory where the custom applications are located. By default, that is custom_applications (written with an underscore, not a dash) but it has nothing to do with the URL. For more information check here.

Custom Path Configuration

If you want to use a different location for custom applications, this can be configured in your JobRouter® installation. To do this, go to the Configuration menu, then select JobRouter Settings and click on Paths.

In the input field Custom Application Directory, enter the directory you want to use.

This directory must be readable and executable by your web server user. Write permissions are only required for application developers.

Once configured, make sure to:

• Move all custom applications to the new directory.
• Run composer require jobrouter/sdk inside the new directory to (re)install the SDK and dependencies.

Important

Please note: Do not create a folder names custom-applications (with a dash) within the JobRouter root directory to use it as custom path. More information can be found here.