codebar-ag / laravel-docuware
DocuWare integration with Laravel
Installs: 8 988
Dependents: 0
Suggesters: 0
Security: 0
Stars: 10
Watchers: 4
Forks: 6
Open Issues: 2
Requires
- php: >=8.2
- guzzlehttp/guzzle: ^7.8
- illuminate/contracts: ^11.0
- nesbot/carbon: ^2.72
- saloonphp/cache-plugin: ^3.0
- saloonphp/laravel-plugin: ^3.5
- saloonphp/saloon: ^3.7
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- laravel/pint: ^1.14
- nunomaduro/larastan: ^2.9
- orchestra/testbench: ^9.0
- pestphp/pest: ^2.34
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
- phpunit/phpunit: ^10.5
- spatie/laravel-ray: ^1.35
- dev-main
- v11.06
- v11.05
- v11.04
- v11.03
- v11.0.2
- v11.0.1
- v11.0
- v5.2
- v5.1
- v5.0
- v4.3
- v4.2
- v4.1
- v4.0
- v3.6.4
- v3.6.3
- v3.6.2
- v3.6.1
- v3.6
- v3.5.1
- v3.5
- v3.4.1
- v3.4
- v3.3.0
- v3.2.0
- v3.1.1
- v3.1.0
- v3.0.1
- v2.1.1
- v2.1.0
- v2.0.2
- v2.0.1
- v2.0
- v1.3.0
- v1.2.2
- v1.2.1
- 1.2.0
- 1.1.1
- 1.1.0
- 1.0.0
- 0.7.0
- 0.6.0
- 0.5.0
- 0.4.0
- 0.3.1
- 0.3.0
- 0.2.0
- 0.1.0
- 0.0.0
- dev-feature-l11
- dev-feature-l11-annotations
This package is auto-updated.
Last update: 2024-10-23 20:05:38 UTC
README
This package was developed to give you a quick start to communicate with the DocuWare REST API. It is used to query the most common endpoints.
⚠️ This package is not designed as a replacement of the official DocuWare REST API. See the documentation if you need further functionality. ⚠️
Navigation
- 💡 What is DocuWare?
- 🛠 Requirements
- ⚙️ Installation
- 🏗 Usage
- Extending the connector (EXAMPLE)
- 🖼 Make encrypted URLs
- 🏋️ Document Index Fields DTO showcase
- 📦 Caching requests
- 💥 Exceptions explained
- ✨ Events
- 🔧 Configuration file
- 🚧 Testing
- 📝 Changelog
- ✏️ Contributing
- 🧑💻 Security Vulnerabilities
- 🙏 Credits
- 🎭 License
💡 What is DocuWare?
DocuWare provides cloud document management and workflow automation software that enables you to digitize, secure and work with business documents, then optimize the processes that power the core of your business.
🛠 Requirements
Version Support
Current Support
⚙️ Installation
You can install the package via composer:
composer require codebar-ag/laravel-docuware
Add the following environment variables to your .env
file:
DOCUWARE_URL=https://domain.docuware.cloud
DOCUWARE_USERNAME=user@domain.test
DOCUWARE_PASSWORD=password
DOCUWARE_PASSPHRASE="passphrase"
With the passphrase we are able to encrypt the URLs.
⚠️ You need to escape backslashes in your passphrase with another backslash:
# ❌ Passphrase contains a backslash and is not escaped: DOCUWARE_PASSPHRASE="a#bcd>2~C1'abc\#" # ✅ We need to escape the backslash with another backslash: DOCUWARE_PASSPHRASE="a#bcd>2~C1'abc\\#"
🏗 Usage
Getting Started with OAuth
This package automatically handles the generation of OAuth token for you and stores them in cache.
Getting a new token via Username & Password:
use CodebarAg\DocuWare\Connectors\DocuWareConnector; use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentials; $connector = new DocuWareConnector( configuration: new ConfigWithCredentials( username: 'username', password: 'password', ) );
Getting a new token via Username & Password (Trusted User):
use CodebarAg\DocuWare\Connectors\DocuWareConnector; use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentialsTrustedUser; $connector = new DocuWareConnector( configuration: new ConfigWithCredentialsTrustedUser( username: 'username', password: 'password', impersonatedUsername: 'impersonatedUsername', ) );
Available Requests
Extending the connector (EXAMPLE)
We understand it may be repetitive to pass the configuration every time you create a new connector.
You can extend the connector and set the configuration once.
Create a new connector
<?php namespace App\Connectors; use CodebarAg\DocuWare\Connectors\DocuWareConnector; use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentials; class YourOwnDocuWareConnector extends DocuWareConnector { public function __construct() { $configuration = new ConfigWithCredentials( username: 'username', password: 'password', ); parent::__construct($configuration); } }
Use the new connector
use App\Connectors\YourOwnDocuWareConnector; use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentials; $connector = new YourOwnDocuWareConnector();
🖼 Make encrypted URLs
🏋️ Document Index Fields DTO showcase
📦 Caching requests
💥 Exceptions explained
✨ Events
The Following events will be fired:
use CodebarAg\DocuWare\Events\DocuWareResponseLog; // Log each response from the DocuWare REST API. DocuWareResponseLog::class => [ // ],
🔧 Configuration file
You can publish the config file with:
php artisan vendor:publish --provider="CodebarAg\DocuWare\DocuWareServiceProvider" --tag="docuware-config"
This is the contents of the published config file:
<?php return [ /* |-------------------------------------------------------------------------- | Cache driver |-------------------------------------------------------------------------- | You may like to define a different cache driver than the default Laravel cache driver. | */ 'cache_driver' => env('DOCUWARE_CACHE_DRIVER', env('CACHE_DRIVER', 'file')), /* |-------------------------------------------------------------------------- | Requests timeout |-------------------------------------------------------------------------- | This variable is optional and only used if you want to set the request timeout manually. | */ 'timeout' => env('DOCUWARE_TIMEOUT', 15), /* |-------------------------------------------------------------------------- | DocuWare Credentials |-------------------------------------------------------------------------- | | Before you can communicate with the DocuWare REST-API it is necessary | to enter your credentials. You should specify a url containing the | scheme and hostname. In addition add your username and password. | */ 'credentials' => [ 'url' => env('DOCUWARE_URL'), 'username' => env('DOCUWARE_USERNAME'), 'password' => env('DOCUWARE_PASSWORD'), ], /* |-------------------------------------------------------------------------- | Passphrase |-------------------------------------------------------------------------- | | In order to create encrypted URLs we need a passphrase. This enables a | secure exchange of DocuWare URLs without anyone being able to modify | your query strings. You can find it in the organization settings. | */ 'passphrase' => env('DOCUWARE_PASSPHRASE'), /* |-------------------------------------------------------------------------- | Configurations |-------------------------------------------------------------------------- | */ 'configurations' => [ 'search' => [ 'operation' => 'And', /* * Force Refresh * Determine if result list is retrieved from the cache when ForceRefresh is set * to false (default) or always a new one is executed when ForceRefresh is set to true. */ 'force_refresh' => true, 'include_suggestions' => false, 'additional_result_fields' => [], ], 'cache' => [ 'driver' => env('DOCUWARE_CACHE_DRIVER', env('CACHE_DRIVER', 'file')), 'lifetime_in_seconds' => env('DOCUWARE_CACHE_LIFETIME_IN_SECONDS', 60), ], ], ];
🚧 Testing
Copy your own phpunit.xml-file.
cp phpunit.xml.dist phpunit.xml
Modify environment variables in the phpunit.xml-file:
<env name="DOCUWARE_TOKEN" value=""/> <env name="DOCUWARE_URL" value="https://domain.docuware.cloud"/> <env name="DOCUWARE_USERNAME" value="user@domain.test"/> <env name="DOCUWARE_PASSWORD" value="password"/> <env name="DOCUWARE_PASSPHRASE" value="passphrase"/> <env name="DOCUWARE_TIMEOUT" value="30"/> <env name="DOCUWARE_CACHE_LIFETIME_IN_SECONDS" value="0"/> <env name="DOCUWARE_TESTS_FILE_CABINET_ID" value=""/> <env name="DOCUWARE_TESTS_DIALOG_ID" value=""/> <env name="DOCUWARE_TESTS_BASKET_ID" value=""/> <env name="DOCUWARE_TESTS_ORGANIZATION_ID" value=""/>
Run the tests:
composer test
📝 Changelog
Please see CHANGELOG for more information on what has changed recently.
✏️ Contributing
Please see CONTRIBUTING for details.
🧑💻 Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
🙏 Credits
- Sebastian Fix
- Rhys Lees
- All Contributors
- Skeleton Repository from Spatie
- Laravel Package Training from Spatie
🎭 License
The MIT License (MIT). Please see License File for more information.