innobraingmbh/onoffice-structure

Package to extract the enterprise configuration

v1.0.1 2025-10-18 10:34 UTC

Requires

• php: ^8.4
• illuminate/contracts: ^12.32
• innobrain/laravel-onoffice-adapter: ^1.10
• prism-php/prism: >=v0.89.0 < v1.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• driftingly/rector-laravel: ^2.0.7
• larastan/larastan: ^3.7.2
• laravel/pint: ^1.25.1
• nunomaduro/collision: ^8.8.2
• orchestra/testbench: ^10.6.0
• pestphp/pest: ^4.1
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• pestphp/pest-plugin-type-coverage: ^4.0
• phpstan/extension-installer: ^1.4.3
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0.7

MIT

• Konstantin Auffinger

• laravel
• Innobrain
• onoffice-structure

README

This package provides a structured way to extract and work with the onOffice enterprise field configuration (Modul- und Feldkonfiguration) within a Laravel application. It fetches the configuration via the innobrain/laravel-onoffice-adapter and transforms it into a collection of Data Transfer Objects (DTOs). These DTOs can then be converted into various formats, such as arrays or Laravel validation rules, using a flexible strategy pattern.

Features

• Fetch onOffice field configurations for various modules (Address, Estate, etc.).
• Structured DTOs for Modules, Fields, Permitted Values, Dependencies, and Filters.
• Convert DTOs to arrays.
• Convert DTOs to Laravel validation rules.
• Extensible converter strategy pattern.
• Facade for easy access.
• Configuration file for future extensions.
• Includes a basic Artisan command.

Installation

You can install the package via Composer:

composer require innobraingmbh/onoffice-structure

Configuration

You can publish the configuration file using:

php artisan vendor:publish --provider="Innobrain\Structure\StructureServiceProvider" --tag="onoffice-structure-config"

This will publish the onoffice-structure.php file to your config directory. Currently, this file is a placeholder for future configuration options.

Usage

The primary way to interact with the package is through the Structure facade or by injecting the Innobrain\Structure\Services\Structure class.

Fetching Structure Data

To fetch the field configuration, you need to provide OnOfficeApiCredentials from the innobrain/laravel-onoffice-adapter package.

use Innobrain\OnOfficeAdapter\Dtos\OnOfficeApiCredentials;
use Innobrain\Structure\Facades\Structure;
use Innobrain\Structure\Collections\ModulesCollection;

// Instantiate your API credentials
$credentials = new OnOfficeApiCredentials('your-token', 'your-secret');

// Fetch the structure
$modulesCollection = Structure::forClient($credentials)->getModules();

// $modulesCollection is an instance of Innobrain\Structure\Collections\ModulesCollection
// which extends Illuminate\Support\Collection. It contains Module DTOs.

foreach ($modulesCollection as $moduleKey => $module) {
    echo "Module: " . $module->label . " (" . $module->key->value . ")\n";
    foreach ($module->fields as $fieldKey => $field) {
        echo "  Field: " . $field->label . " (" . $field->key . ") - Type: " . $field->type->value . "\n";
    }
}

You can also access specific modules:

use Innobrain\Structure\Enums\FieldConfigurationModule;

$addressModule = $modulesCollection->get(FieldConfigurationModule::Address->value);
if ($addressModule) {
    // Work with the address module
}

Direct Field Configuration Access

If you only need to retrieve the configuration without the Structure wrapper, you can use the FieldConfiguration facade or class:

use Innobrain\OnOfficeAdapter\Dtos\OnOfficeApiCredentials;
use Innobrain\Structure\Facades\FieldConfiguration;

$credentials = new OnOfficeApiCredentials('your-token', 'your-secret');
$modules = FieldConfiguration::retrieveForClient($credentials);

Converting Data

The DTOs and ModulesCollection implement the Convertible interface, allowing them to be transformed using a ConvertStrategy.

1. Array Conversion (ArrayConvertStrategy)

This strategy converts the DTOs into nested arrays.

use Innobrain\Structure\Converters\Array\ArrayConvertStrategy;

// Convert the entire collection of modules
$strategy = new ArrayConvertStrategy(dropEmpty: false); // or true to remove null/empty values
$arrayOfModules = $modulesCollection->convert($strategy);

// Convert a single module
$addressModuleArray = $addressModule->convert($strategy);

// Convert a single field
$emailField = $addressModule->fields->get('Email');
$emailFieldArray = $emailField->convert($new ArrayConvertStrategy());

The ArrayConvertStrategy constructor accepts a bool $dropEmpty (default false). If true, it will recursively remove keys with null, empty string, or empty array values from the output.

2. Laravel Validation Rules Conversion (LaravelRulesConvertStrategy)

This strategy converts module or field DTOs into Laravel validation rules.

use Innobrain\Structure\Converters\LaravelRules\LaravelRulesConvertStrategy;

// For a specific module (e.g., Address)
$addressModule = $modulesCollection->get(FieldConfigurationModule::Address->value);

// Get rules as pipe-separated strings (default), including 'nullable' for fields without defaults
$strategyPipe = new LaravelRulesConvertStrategy(pipeSyntax: true, includeNullable: true);
$addressValidationRules = $addressModule->convert($strategyPipe);
/*
Example output for $addressValidationRules:
[
    'KdNr' => 'integer|nullable',
    'Email' => 'string|max:100|nullable',
    'Beziehung' => 'array|distinct|nullable',
    'Beziehung.*' => 'in:0,1,2,3', // if Beziehung is a multiselect
    // ... other fields
]
*/

// Get rules as arrays, excluding 'nullable' by default
$strategyArray = new LaravelRulesConvertStrategy(pipeSyntax: false, includeNullable: false);
$addressValidationRulesArray = $addressModule->convert($strategyArray);
/*
Example output for $addressValidationRulesArray:
[
    'KdNr' => ['integer'],
    'Email' => ['string', 'max:100'],
    'Beziehung' => ['array', 'distinct'],
    'Beziehung.*' => ['in:0,1,2,3'],
    // ... other fields
]
*/

// Convert a single field
$emailField = $addressModule->fields->get('Email');
$emailFieldRules = $emailField->convert($strategyPipe); // e.g., 'string|max:100|nullable'

Constructor options for LaravelRulesConvertStrategy:

• bool $pipeSyntax (default true): If true, rules are returned as a pipe-separated string (e.g., 'string|max:80|nullable'). If false, rules are an array (e.g., ['string', 'max:80', 'nullable']).
• bool $includeNullable (default true): If true, the 'nullable' rule is automatically added to fields that do not have a default value defined in the onOffice configuration.

3. Prism Schema Conversion (PrismSchemaConvertStrategy)

This strategy converts module or field DTOs into Prism PHP schemas, which can be used for structured data generation with AI providers.

use Innobrain\Structure\Converters\PrismSchema\PrismSchemaConvertStrategy;
use Prism\Prism;
use Prism\Providers\OpenRouter\OpenRouter;

// Convert an entire module to a Prism ObjectSchema
$addressModule = $modulesCollection->get(FieldConfigurationModule::Address->value);
$strategy = new PrismSchemaConvertStrategy(
    includeNullable: true,     // Mark fields without defaults as nullable
    includeDescriptions: true   // Include field labels as descriptions
);
$addressSchema = $addressModule->convert($strategy);
// Returns an ObjectSchema with properties for each field

// Convert a single field to its appropriate Prism schema
$emailField = $addressModule->fields->get('Email');
$emailSchema = $emailField->convert($strategy);
// Returns a StringSchema with max length constraint in description

// Use the schema with Prism for AI-powered data generation

$prism = Prism::using(OpenRouter::instance())
    ->withStructuredOutput($addressSchema);

$response = $prism->generate('Create a realistic address entry');

The PrismSchemaConvertStrategy maps field types as follows:

• VarChar/Text/Blob → StringSchema (with length constraint in description)
• Integer → NumberSchema
• Float → NumberSchema
• Boolean → BooleanSchema
• Date/DateTime → StringSchema (with format hint in description)
• SingleSelect → EnumSchema (with permitted values as options)
• MultiSelect → ArraySchema (containing EnumSchema items)

Constructor options for PrismSchemaConvertStrategy:

• bool $includeNullable (default true): If true, fields without default values are marked as nullable.
• bool $includeDescriptions (default true): If true, field labels are included as schema descriptions.

4. JsonSchema Conversion (JsonSchemaConvertStrategy)

This strategy converts module or field DTOs into JsonSchema Laravel format.

use Innobrain\Structure\Converters\JsonSchema\JsonSchemaConvertStrategy;

// Convert an entire module to a JsonSchema ObjectType
$addressModule = $modulesCollection->get(FieldConfigurationModule::Address->value);
$strategy = new JsonSchemaConvertStrategy(
    includeNullable: true,     // Mark fields without defaults as nullable
    includeDescriptions: true   // Include field labels as descriptions
);
$addressSchema = $addressModule->convert($strategy);
// Returns an ObjectType with properties for each field

// Convert a single field to its appropriate JsonSchema
$emailField = $addressModule->fields->get('Email');
$emailSchema = $emailField->convert($strategy);
// Returns a StringType with max length constraint, also mentioned in the description

Data Transfer Objects (DTOs)

The package uses the following DTOs to represent the structure:

• Innobrain\Structure\DTOs\Module: Represents a module (e.g., Address, Estate).
  • key: FieldConfigurationModule (enum)
  • label: string
  • fields: Illuminate\Support\Collection of Field DTOs.
• Innobrain\Structure\DTOs\Field: Represents a field within a module.
  • key: string
  • label: string
  • type: FieldType (enum)
  • length: ?int
  • permittedValues: Illuminate\Support\Collection of PermittedValue DTOs.
  • default: ?string
  • filters: Illuminate\Support\Collection of FieldFilter DTOs.
  • dependencies: Illuminate\Support\Collection of FieldDependency DTOs.
  • compoundFields: Illuminate\Support\Collection of strings.
  • fieldMeasureFormat: ?string
• Innobrain\Structure\DTOs\PermittedValue: Represents a permitted value for select fields.
  • key: string
  • label: string
• Innobrain\Structure\DTOs\FieldDependency: Represents a dependency between fields.
  • dependentFieldKey: string
  • dependentFieldValue: string
• Innobrain\Structure\DTOs\FieldFilter: Represents a filter configuration for a field.
  • name: string
  • config: Illuminate\Support\Collection

All DTOs implement Innobrain\Structure\Contracts\Convertible.

Enums

• Innobrain\Structure\Enums\FieldConfigurationModule: Defines the available onOffice modules (e.g., Address, Estate).
• Innobrain\Structure\Enums\FieldType: Defines the types of fields (e.g., VarChar, Integer, MultiSelect).

Collections

• Innobrain\Structure\Collections\ModulesCollection: A custom collection that extends Illuminate\Support\Collection and holds Module DTOs. It also implements Convertible.

Testing

To run the test suite:

composer test

To run tests with coverage:

composer test-coverage

To run static analysis (PHPStan):

composer analyse

To format code (Rector & Pint):

composer format

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md (if available) or open an issue/pull request. For bug reports, please use the Bug Report Template.

Security Vulnerabilities

If you discover a security vulnerability within this package, please send an e-mail to Konstantin Auffinger via the email address in composer.json. All security vulnerabilities will be promptly addressed.

Credits

• Konstantin Auffinger
• All Contributors

This package was generated using Spatie's Laravel Package Tools.

License

This is proprietary to InnoBrain GmbH & Konstantin Auffinger. There is no license. It is only source-available.