README

本包旨在快速入门，用于与DocuWare REST API通信。它用于查询最常见的端点。

⚠️ 本包不是官方DocuWare REST API的替代品。如需进一步功能，请参阅文档。⚠️

💡 什么是DocuWare？
🛠 要求
⚙️ 安装
🏗 使用
扩展连接器（示例）
- 创建新的连接器
- 使用新的连接器
🖼 创建加密URL
🏋️ 文档索引字段DTO示例
📦 缓存请求
💥 异常说明
✨ 事件
🔧 配置文件
🚧 测试
📝 更新日志
✏️ 贡献
🧑‍💻 安全漏洞
🙏 致谢
🎭 许可证

💡 什么是DocuWare？

DocuWare提供云文档管理和工作流自动化软件，使您能够数字化、安全地处理商业文档，然后优化推动您业务核心的流程。

🛠 要求

版本支持

当前支持

⚙️ 安装

您可以通过composer安装此包

composer require codebar-ag/laravel-docuware

将以下环境变量添加到您的.env文件中

DOCUWARE_URL=https://domain.docuware.cloud
DOCUWARE_USERNAME=user@domain.test
DOCUWARE_PASSWORD=password
DOCUWARE_PASSPHRASE="passphrase"

使用密码我们可以加密URL。

⚠️ 您需要在密码中用另一个反斜杠转义反斜杠

# ❌ 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\\#"

🏗 使用

使用OAuth入门

此包自动为您生成OAuth令牌并将其存储在缓存中。

通过用户名和密码获取新令牌

use CodebarAg\DocuWare\Connectors\DocuWareConnector;
use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentials;

$connector = new DocuWareConnector(
    configuration: new ConfigWithCredentials(
        username: 'username',
        password: 'password',
    )
);

通过用户名和密码（受信任用户）获取新令牌

use CodebarAg\DocuWare\Connectors\DocuWareConnector;
use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentialsTrustedUser;

$connector = new DocuWareConnector(
    configuration: new ConfigWithCredentialsTrustedUser(
        username: 'username',
        password: 'password',
        impersonatedUsername: 'impersonatedUsername',
    )
);

可用请求

扩展连接器（示例）

我们理解，每次创建新的连接器时传递配置可能很繁琐。

您可以扩展连接器并一次性设置配置。

创建新的连接器

<?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 App\Connectors\YourOwnDocuWareConnector;
use CodebarAg\DocuWare\DTO\Config\ConfigWithCredentials;

$connector = new YourOwnDocuWareConnector();

🖼 创建加密URL

加密URL

🏋️ 文档索引字段DTO示例

文档索引字段DTO

📦 缓存请求

缓存请求

💥 异常说明

异常

✨ 事件

以下事件将被触发

use CodebarAg\DocuWare\Events\DocuWareResponseLog;

// Log each response from the DocuWare REST API.
DocuWareResponseLog::class => [
    //
],

🔧 配置文件

您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="CodebarAg\DocuWare\DocuWareServiceProvider" --tag="docuware-config"

这是发布配置文件的内容

<?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),
        ],
    ],
];

🚧 测试

复制您的自己的phpunit.xml文件。

cp phpunit.xml.dist phpunit.xml

在phpunit.xml文件中修改环境变量

<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=""/>

运行测试

composer test

📝 更新日志

有关最近更改的更多信息，请参阅更新日志。

✏️ 贡献

有关详细信息，请参阅贡献。

🧑‍💻 安全漏洞

有关如何报告安全漏洞，请参阅我们的安全策略。

🙏 致谢

🎭 许可证

MIT许可（MIT）。请参阅许可文件获取更多信息。

codebar-ag / laravel-docuware

维护者

详细信息