PHP code example of seventhings / customer-api-php

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

seventhings / customer-api-php example snippets

use Seventhings\Client;

// Authenticate with credentials (recommended)
$client = Client::withCredentials($baseUrl, $username, $password, $clientId);

// Or use an existing token
$client = Client::withToken($baseUrl, $accessToken);

// Override the limit (requests per minute)
$client = Client::withToken($baseUrl, $accessToken, requestsPerMinute: 100);

// Disable throttling
$client = Client::withCredentials($baseUrl, $username, $password, $clientId, requestsPerMinute: 0);

// Health check (unauthenticated)
$client->auth->ping();

// Login
$token = $client->auth->login($username, $password, $clientId);

// Refresh token (uses stored clientId from login)
$refreshed = $client->auth->refresh($token->refreshToken);

// Revoke all tokens
$client->auth->revokeTokens();

use Seventhings\Models\ListOptions;
use Seventhings\Models\FilterEntry;
use Seventhings\Models\Enums\FilterOperator;
use Seventhings\Models\FileAttachment;

// List objects (one page of raw arrays)
$objects = $client->objects->list();

// Iterate every object across all pages (lazy; default page size 100).
// Each item is a type-safe Fields wrapper over the instance-defined body.
foreach ($client->objects->all() as $obj) {
    echo $obj->uuid(), ' ', $obj->string('inventory_name'), "\n";
    $price = $obj->float('purchasing_price');   // null if absent or non-numeric
}

// Create (field names are instance-specific)
$uuid = $client->objects->create([
    'inventory_name' => 'Laptop #42',
    'barcode' => 'INV-0042',
]);

// Get, patch, delete
$object = $client->objects->get($uuid);

// Look up by scancode, including archived objects. Pass the raw barcode;
// the SDK URL-encodes it as a single path segment.
$object = $client->objects->getByBarcode('INV/0042');

$client->objects->patch($uuid, ['inventory_name' => 'Laptop #43']);
$client->objects->delete($uuid);

// Count
$count = $client->objects->count();

// Archive / unarchive
$client->objects->archive($uuid);
$client->objects->unarchive($uuid);

// File attachments
$client->objects->addFiles($uuid, [new FileAttachment('documents', $fileUuid)]);
$client->objects->removeFiles($uuid, [new FileAttachment('documents', $fileUuid)]);

$rooms = $client->rooms->list();
$uuid = $client->rooms->create(['name' => 'Server Room', ...]);
$room = $client->rooms->get($uuid);
$client->rooms->patch($uuid, ['name' => 'Server Room A']);
$count = $client->rooms->count();
$client->rooms->delete($uuid);

$locations = $client->locations->list();
$uuid = $client->locations->create(['name' => 'Building A']);
$location = $client->locations->get($uuid);
$client->locations->patch($uuid, ['name' => 'Building B']);
$count = $client->locations->count();
$client->locations->delete($uuid);

use Seventhings\Models\UserListOptions;

$result = $client->users->list();
// $result->items, $result->total, $result->page, etc.

$user = $client->users->get($uuid);
$user = $client->users->getById($id);

use Seventhings\Models\PersonListOptions;
use Seventhings\Models\FilterObject;
use Seventhings\Models\Enums\SortDirection;

$result = $client->persons->list();
// $result->items, $result->total, $result->page, etc.

// Sorting uses the deep-object sort[field]=DIR format (a field => direction
// map), not sort_by/order. $result->sort echoes the applied sort back.
$result = $client->persons->list(new PersonListOptions(
    perPage: 25,
    sort: ['id' => SortDirection::Desc],
));

// Each PersonResponse exposes typed convenience props (uuid, email, firstname, …).
// Person fields are template-defined, so any custom field beyond those props is
// still available via the full raw map: $person->fields['custom_key'] or the
// null-safe $person->field('custom_key').
// Responses are flat field maps; ->uuid is read from person_uuid.

$count = $client->persons->count();

$person = $client->persons->get($uuid);
$person = $client->persons->getById($id);

// Create — returns the new person UUID.
// Field keys are template-defined (commonly first_name / last_name).
$uuid = $client->persons->create([
    'email' => '[email protected]',
    'first_name' => 'Max',
]);

// Update fields — the API returns no body, so re-fetch to read the result.
$client->persons->patch($uuid, ['last_name' => 'Mustermann']);
$person = $client->persons->get($uuid);

$client->persons->delete($uuid);

// Create a platform user from the person matched by a filter
$client->persons->createUser(new FilterObject(
    filter: ['email' => ['eq' => '[email protected]']],
));

// Upload a file
$fileUuid = $client->files->upload('report.pdf', $fileContents);

// List all files
$files = $client->files->list();

// Get metadata
$meta = $client->files->get($fileUuid);

// Download file data
$data = $client->files->getData($fileUuid);

// Download thumbnail
$thumbnail = $client->files->getThumbnail($fileUuid);

// Thumbnail fitted within 320x240 (aspect ratio preserved). Both dimensions
// must be 1–2000; the API caches new sizes and may reject excess sizes (422).
$small = $client->files->getThumbnail($fileUuid, 320, 240);

use Seventhings\Models\CreateTaskRequest;
use Seventhings\Models\UpdateTaskRequest;
use Seventhings\Models\TaskListOptions;
use Seventhings\Models\TaskReferenceInput;
use Seventhings\Models\TimeInterval;
use Seventhings\Models\Enums\TaskStatus;
use Seventhings\Models\Enums\TaskReferenceType;
use Seventhings\Models\Enums\TimeIntervalUnit;

// Create (lient->tasks->get($uuid);
$client->tasks->update($uuid, new UpdateTaskRequest(
    title: 'Updated title',
    deadline: '2026-12-31',
    assignees: [$userUuid],
    references: [new TaskReferenceInput(TaskReferenceType::Asset, $objectUuid)],
    reminders: [new TimeInterval(TimeIntervalUnit::Days, 1)],
    recurringSchedule: null,
));
$client->tasks->delete($uuid);

// Change status
$client->tasks->updateStatus($uuid, TaskStatus::Closed);

// List with filters
$tasks = $client->tasks->list(new TaskListOptions(status: TaskStatus::Open));

use Seventhings\Models\CreateRentalCaseRequest;
use Seventhings\Models\UpdateRentalCaseRequest;
use Seventhings\Models\RentalCaseReferenceInput;
use Seventhings\Models\RentalCaseRenter;
use Seventhings\Models\Enums\RentalCaseReferenceType;
use Seventhings\Models\Enums\RenterType;

$rentals = $client->rentals->list();

// Full-day rental (default when the kind and times are omitted)
$uuid = $client->rentals->create(new CreateRentalCaseRequest(
    title: 'Team event',
    issueDate: '2026-11-01',
    dueDate: '2026-11-03',
    comment: '',
    responsibleUserUuid: $userUuid,
    renter: new RentalCaseRenter(RenterType::Plain, 'Jane Doe'),
    references: [new RentalCaseReferenceInput(RentalCaseReferenceType::Asset, $objectUuid)],
    attachments: [],
));

// Timed rental: any offset is accepted and stored as UTC
$timed = $client->rentals->create(new CreateRentalCaseRequest(
    title: 'Projector',
    issueDate: '2026-11-01',
    dueDate: '2026-11-01',
    comment: '',
    responsibleUserUuid: $userUuid,
    renter: new RentalCaseRenter(RenterType::Plain, 'Jane Doe'),
    references: [new RentalCaseReferenceInput(RentalCaseReferenceType::Asset, $objectUuid)],
    attachments: [],
    isFullDay: false,
    issueAt: '2026-11-01T10:00:00+02:00',
    dueAt: '2026-11-01T12:00:00+02:00',
));

$rental = $client->rentals->get($timed);
$rental->isFullDay; // false
$rental->issueAt;   // "2026-11-01T08:00:00+00:00"

// update() is a full replacement (PUT): send the complete state, not a patch
$client->rentals->update($uuid, new UpdateRentalCaseRequest(/* same fields as create */));
$client->rentals->delete($uuid);

use Seventhings\Models\FilterEntry;
use Seventhings\Models\ListOptions;

$uuid = $client->catalogItems->create(['catalog_object_inventory_name' => 'Office chair']);
$item = $client->catalogItems->get($uuid);   // CatalogItem { uuid, fields: Fields }
$item->fields->string('catalog_object_inventory_name');

$page = $client->catalogItems->list(new ListOptions(
    perPage: 25,
    filters: [FilterEntry::like('catalog_object_inventory_name', 'chair')],
));                                          // items, page, perPage, total, sort
foreach ($client->catalogItems->all() as $item) { /* ... */ }

// PUT replaces all catalog fields; missing fields are emptied. Objects
// previously created from this item are not changed.
$client->catalogItems->update($uuid, ['catalog_object_inventory_name' => 'Desk chair'] + $item->fields->data);

// Deleting leaves objects created from the item intact.
$client->catalogItems->delete($uuid);

use Seventhings\Models\HistoryListOptions;

$options = new HistoryListOptions(page: 1, perPage: 25);
$history = $client->objects->history($objectUuid, $options);
// $history->items, ->page, ->perPage, ->total; newest changes first.

foreach ($history->items as $event) {
    echo $event['type']; // asset, task, rental_case, or object_merge
    // Dynamic maps retain properties and merge-specific payloads such as
    // user_id and absorbedObjectData.
}

// Other resources return typed history entries.
$history = $client->rooms->history($roomUuid, $options);
foreach ($history->items as $event) {
    echo $event->roomUuid, ' ', $event->occurredAt, ' ', $event->eventName;
    // Also: ->userUuid, ->description, ->details.
    // details remains a JSON-encoded snapshot string (or an empty string).
}

$client->locations->history($locationUuid, $options); // LocationHistoryEntry
$client->persons->history($personUuid, $options);    // PersonHistoryEntry
$client->tasks->history($taskUuid, $options);        // TaskHistoryEntry
$client->rentals->history($rentalUuid, $options);    // RentalCaseHistoryEntry

use Seventhings\Models\CreateReportRequest;

$templates = $client->reports->listTemplates(); // ReportTemplate[] (uuid, name)

if ($templates !== []) {
    $pdf = $client->reports->create(new CreateReportRequest(
        reportTemplateUuid: $templates[0]->uuid,
        objectUuids: [$objectUuid1, $objectUuid2], // At least one; order is preserved.
    ));
    file_put_contents('inventory.pdf', $pdf);
}

use Seventhings\Models\Enums\AssetTrackingTemplate;
use Seventhings\Models\CreateFieldDefinition;
use Seventhings\Models\FieldDefinitionFieldType;
use Seventhings\Models\FieldValueConstraint;
use Seventhings\Models\FieldAttribute;
use Seventhings\Models\Enums\FieldTypeName;

// List field definitions for a template
// (AssetTrackingTemplate::Asset, ::Room, or ::Person)
$fields = $client->fieldDefinitions->list(AssetTrackingTemplate::Asset);

// Inspect a definition: is it son);

// Fail fast: which ldType: new FieldDefinitionFieldType(FieldTypeName::Text, [
        new FieldValueConstraint('max_length', 255),
    ]),
    label: 'Serial Number',
    attributes: [
        new FieldAttribute('mandatory', 'no'),
        new FieldAttribute('mutable', 'yes'),
        new FieldAttribute('internal', 'no'),
    ],
    relations: [],
));

use Seventhings\Models\FilterObject;
use Seventhings\Models\AddObjectEntry;

// Suggest category
$suggestion = $client->circularityHub->suggestCategory(new FilterObject(filter: ['name' => 'Monitor']));

// Items
$items = $client->circularityHub->listItems();
$item = $client->circularityHub->getItem($id);
$client->circularityHub->updateItem($id, ['price' => '25.00']);
$client->circularityHub->deleteItem($id);

// Orders
$orders = $client->circularityHub->listOrders();
$orderId = $client->circularityHub->createOrder([$itemId1, $itemId2]);
$order = $client->circularityHub->getOrder($orderId);

// Add objects to CircularityHub
$client->circularityHub->addObjects([
    $objectUuid => new AddObjectEntry(category: 'Electronics', price: '50.00'),
]);

use Seventhings\Models\ApiException;
use Seventhings\Models\NetworkException;

try {
    $client->objects->get($uuid);
} catch (ApiException $e) {
    echo $e->statusCode; // e.g. 404
    echo $e->status;     // e.g. "Not Found"
    echo $e->body;       // raw response body
    $e->isStatusCode(404); // true

    // Convenience predicates for common statuses:
    if ($e->isNotFound()) { /* 404 */ }
    // also: isUnauthorized() 401, isForbidden() 403, isConflict() 409,
    //       isRateLimited() 429, isServerError() 5xx
    // isFeatureInactive() recognizes the API's explicit inactive-feature 403
    // response; ordinary permission denials return false.
} catch (NetworkException $e) {
    echo $e->getMessage(); // connection error details
}

if ($e->isRateLimited()) {
    $delay = $e->retryAfter(); // ?int seconds; pass a DateTimeInterface as "now" for tests
    if ($delay !== null) {
        // Requeue the operation no earlier than $delay seconds from now.
    } else {
        // Missing or invalid header: apply your own bounded backoff.
    }
}

use Seventhings\Models\ListOptions;
use Seventhings\Models\FilterEntry;
use Seventhings\Models\Enums\FilterOperator;
use Seventhings\Models\Enums\SortDirection;

$options = new ListOptions(
    page: 1,
    perPage: 25,
    sort: ['updated_at' => SortDirection::Desc],
    filters: [
        // Static constructors avoid spelling out the operator enum:
        FilterEntry::like('inventory_name', 'Laptop'),
        FilterEntry::in('status', 'active', 'reserved'),
        // equivalent to: new FilterEntry('inventory_name', FilterOperator::Like, ['Laptop'])
    ],
);

$objects = $client->objects->list($options);
$count = $client->objects->count($options);

// Or iterate every matching object across all pages:
foreach ($client->objects->all($options) as $obj) { /* ... */ }

// Tasks
$tasks = $client->tasks->list(new TaskListOptions(
    status: TaskStatus::Open,
    assignee: $userUuid,
));

// Users
$users = $client->users->list(new UserListOptions(
    page: 1,
    perPage: 50,
    sortBy: UserSortBy::Email,
    order: UserSortOrder::Asc,
));

bash
composer