Download the PHP package codebar-ag/laravel-docuware without Composer

An opinionated, modern integration for the DocuWare Platform REST API. You work with resources and immutable data objects — never raw HTTP.

This package is not designed as a replacement for the official DocuWare REST API. It is an opinionated convenience layer on top of it.

Table of contents

• Highlights
• Requirements
• Installation
• Configuration
• Authentication & grants
• Connecting (config file or runtime DTO)
• Quickstart
• Resources
• Search builder
• Index field values
• Immutable data & withers
• Enums
• Encrypted document URLs
• Endpoint catalog
• Data object (DTO) reference
• Caching
• Error handling
• Events
• Security
• Testing
• Credits
• License

Highlights

• 🎯 Small, domain-shaped API — DocuWare::documents($cabinet)->search()->cursor().
• 🧊 Immutable data via spatie/laravel-data with ->copyWith(...) withers.
• 🏢 Multi-tenant first-class — by config name or a runtime connection DTO.
• 🔢 Typed index fields — IndexFields::make()->text(...)->number(...)->date(...)->table(...) converts PHP values into the exact DocuWare wire format for you.
• 🔒 Secure by default — secrets are never logged, evented, or thrown.
• ♻️ Resilient — encrypted + lock-guarded token store, retry with backoff honoring Retry-After.
• 🧯 One error model — every failure descends from DocuWareException.
• 🧪 Fully fakeable & typed — PHPStan max, offline fixture replay.

Requirements

v14 raises the minimum PHP to 8.4. Laravel 13 stays the target framework.

Installation

Configure the default instance in .env:

Configuration

The default instance reads the flat DOCUWARE_* env keys above. Everything else has sane defaults; publish the config to tune caching, retries, rate limiting, and multi-tenant instances.

Authentication & grants

OAuth is handled for you: the package discovers the identity service, exchanges credentials for an access token, encrypts it, caches it per instance, and refreshes it under a lock before it expires. You never call the token endpoint yourself.

Three grants are supported:

Connecting (config file or runtime DTO)

There are two ways to connect — pick whichever fits your tenancy model.

1. Named instances in config

Best when tenants are known ahead of time. Add them to config/laravel-docuware.php:

2. A runtime connection DTO (database-driven multi-tenancy)

Multi-tenancy is not limited to config files. When connections live in your database — the common case — build a typed config DTO at runtime and hand it to DocuWare::connection():

Each grant has a typed for() factory that fills sensible defaults (cache driver, lifetime, timeout, client id, scope) — override any of them as named arguments:

DocuWare::instance(...) also accepts a DTO directly, so DocuWare::instance($config) and DocuWare::connection($config) are equivalent. Runtime connections are not name-cached, so two tenants may safely reuse a name; their tokens stay isolated by URL + credentials.

Every connection is independent: its own connector, cache namespace, encrypted token entry, and rate limiter.

Quickstart

Resources

Every resource is reached from the DocuWare facade (default instance) or from a resolved client (DocuWare::instance('acme')->…, DocuWare::connection($config)->…). Each returns immutable *Data objects or collections of them.

Documents — DocuWare::documents($cabinetId)

The documents resource is broad, so its methods are grouped by area below.

Core (search, read, write, lifecycle)

Sections (a document is composed of one or more file sections)

Annotations & application properties

Structure operations (clip/staple, transfer, batch & upload)

File cabinets & structure — fileCabinets, dialogs, selectLists

Cabinet metadata, the search/store dialogs defined on a cabinet, and the option lists behind select fields.

Organization & users — organizations, users, groups, roles

Tenant-level directory: the organization, its users, and the groups/roles they belong to.

Workflows — workflows

Trash (recycle bin) — trash

Documents deleted from a cabinet land here until purged or restored.

Search builder

DocuWare::documents($cabinetId)->search() returns a fluent SearchQuery. Conditions and ordering are chainable; a terminal method runs the request.

Index field values

DocuWare expects each index value in a specific wire shape (FieldName / Item / ItemElementName). You don't build that by hand — pass PHP values to the IndexFields builder and it converts each one to the correct typed field. This is the answer to "how do I pass an int / string / table and get the right index field?"

IndexFields::make() starts a builder; isEmpty() tells you whether anything was added; and toCollection() returns the underlying index objects. store() and update() also accept that raw Collection directly if you need to build the DTOs yourself, but IndexFields is the recommended path.

Updating index fields

update() writes index values on an existing document — every field type uses the same call, including tables. It returns a Collection<string, DocumentFieldData> keyed by field name (the server's view of the fields after the write):

Pass forceUpdate: false (the default) to let DocuWare reject writes to protected fields; pass true to force them through where the cabinet permits.

Table fields

A table field holds rows of typed cells. The same table($name, $rows) builder is used for both create (store()) and update (update()), and accepts rows in either form:

• Simple — an associative [column => value] map per row; cell types are auto-detected (string → String, int → Int, float → Decimal, Carbon → DateTime):

• Explicit — build each cell with an index DTO when you need exact typing that auto-detection can't infer (a date-only cell, a keyword, or a memo):

Tables are written wholesale. A store()/update() call replaces every row of the field, so always pass the complete set of rows you want stored. To append, read the current rows first (see below) and re-send them along with the new ones.

Reading a table back, the field's ->value is a Collection<TableRowData>; each row exposes its cells as a Collection<string, DocumentFieldData> keyed by column name (cell values already parsed to native PHP types):

Reading values back

The reverse conversion is automatic. Index values read from DocuWare are exposed on DocumentFieldData->value already cast to the matching PHP type:

Immutable data & withers

Every response is an immutable spatie/laravel-data object:

Enums

Encrypted document URLs

Endpoint catalog

The resources above are the public API. Under the hood they send Saloon requests that map 1:1 to DocuWare Platform REST endpoints. This catalog documents that internal mapping for transparency and advanced use. Paths are relative to <DOCUWARE_URL>/{platform_path}/ (default DocuWare/Platform). Cached = the request implements Saloon's Cacheable (TTL from configurations.cache.*).

Data object (DTO) reference

Responses are mapped into immutable *Data objects under CodebarAg\DocuWare\Data. The most-used shapes and their properties:

Caching

GET metadata and search requests implement Saloon's Cacheable (see the Cached column in the endpoint catalog). Cached responses use the configurations.cache.driver store with a TTL of configurations.cache.lifetime_in_seconds. Set the lifetime to 0 to disable caching. Search requests honor a per-call force-refresh; write operations are never cached.

Error handling

Operations return data or throw — there is no error-carrying result object. Every package exception descends from DocuWareException, so you can catch the base type to handle any DocuWare failure, or a specific subclass for a specific status.

Each exception exposes redacted, structured context for logging and reporting:

Secrets are never present in any exception message or context.

Events

• ResponseReceived — a redacted snapshot (instance, method, path, status, request id). The body is attached only when docuware.debug.capture_bodies is enabled, and is redacted even then.
• TokenRefreshed — instance + url, no secret.

Security

• Structural redaction: Authorization, passwords, tokens, cookies, and the passphrase are stripped from every log, event, and exception. An architecture test asserts no sentinel secret can leak.
• Token store: access tokens are Crypt-encrypted, namespaced per instance, and refreshed under a cache lock to avoid stampedes.

Testing

In your own app, fake DocuWare with Saloon's mock client, or assert against the recorded fixtures under tests/Fixtures/saloon.

Credits

• Sebastian Bürgin-Fix
• codebar Solutions AG
• Ricoh Schweiz AG
• All Contributors

License

The MIT License (MIT). See License File for more information.