通过 
搜索
搜索kylongchu / laravel-docuware
Laravel 与 DocuWare 集成
3.4.8
2024-04-24 09:28 UTC
Requires
- php: ^8.2
- guzzlehttp/guzzle: ^7.8
- illuminate/contracts: ^10.0
- nesbot/carbon: ^2.72
- saloonphp/cache-plugin: ^3.0
- saloonphp/laravel-plugin: ^3.2
- saloonphp/saloon: ^3.4
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- laravel/pint: ^1.13
- nunomaduro/larastan: ^2.8
- orchestra/testbench: ^8.20
- pestphp/pest: ^2.31
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
- spatie/laravel-ray: ^1.33
This package is auto-updated.
Last update: 2024-09-24 10:29:51 UTC
README
此包旨在帮助您快速开始与 DocuWare REST API 进行通信。它用于查询最常用的端点。
⚠️ 此包不是官方 DocuWare REST API 的替代品。如需进一步功能，请参阅文档。⚠️
💡 什么是 DocuWare？
DocuWare 提供云文档管理和工作流自动化软件，使您能够数字化、安全地处理业务文档，并优化推动您业务核心的流程。
🛠️ 要求
> = v3.0
- PHP: `^8.2``
- Laravel:
^10.* - DocuWare 云访问
> = v2.0
- PHP:
^8.1|^8.2 - Laravel:
^9.*|^10.* - DocuWare 云访问
> = v1.2
- PHP:
^8.1 - Laravel:
^9.* - DocuWare 云访问
< v1.2
- PHP:
^8.0 - Laravel:
^8.* - DocuWare 云访问
⚙️ 安装
您可以通过 composer 安装此包
composer require klongchu/laravel-docuware
将以下环境变量添加到您的 .env 文件中： "DOCUWARE_COOKIES" 变量是可选的，并且仅在您想手动设置请求 cookie 时使用。
DOCUWARE_URL=https://domain.docuware.cloud DOCUWARE_USERNAME=user@domain.test DOCUWARE_PASSWORD=password DOCUWARE_PASSPHRASE="passphrase" DOCUWARE_COOKIES="cookie"
使用密码，我们可以加密 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\\#"
🏗️ 使用方法
use Klongchu\DocuWare\Connectors\DocuWareWithoutCookieConnector; // Will use user credentials to authenticate and store cookie in cache $connector = new DocuWareWithoutCookieConnector(); // OR // Will use the cookie provided $connector = new DocuWareWithCookieConnector($cookie); /** * Return an organization. */ $organization = $connector->send(new GetOrganizationRequest($id))->dto(); /** * Return all organizations. */ $organizations = $connector->send(new GetOrganizationsRequest())->dto(); /** * Return all file cabinets. */ $fileCabinets = $connector->send(new GetCabinetsRequest())->dto(); /** * Return all fields of a file cabinet. */ $fields = $connector->send(new GetFieldsRequest($fileCabinetId))->dto(); /** * Return all dialogs of a file cabinet. */ $dialogs = $connector->send(new GetDialogsRequest($fileCabinetId))->dto(); /** * Return all used values for a specific field. */ $values = $connector->send(new GetSelectListRequest($fileCabinetId, $dialogId, $fieldName))->dto(); /** * Return a document. */ $document = $connector->send(new GetDocumentRequest($fileCabinetId, $documentId))->dto(); /** * Return all documents for a file cabinet. */ $documents = $connector->send(new GetDocumentRequest($fileCabinetId))->dto(); /** * Return image preview of a document. */ $content = $connector->send(new GetDocumentPreviewRequest($fileCabinetId, $documentId))->dto(); /** * Download single document. */ $content = $connector->send(new GetDocumentDownloadRequest($fileCabinetId, $documentId))->dto(); /** * Download multiple documents. * * Although there are no mentioned limits in the documentation, * it is not advisable to download more than 100 documents at once. * * Also note there is a default request timeout of 30 seconds. */ $content = $connector->send(new GetDocumentsDownloadRequest($fileCabinetId, $documentIds))->dto(); /** * Download a document thumbnail. */ $thumbnail = $connector->send(new GetDocumentDownloadThumbnailRequest($fileCabinetId, $documentId, $section))->dto(); /** * Update value of a indexed field. */ $value = $connector->send(new PutDocumentFieldsRequest($fileCabinetId, $documentId, [$fieldName => $newValue]))->dto()[$fieldName]; /** * Update multiple values of indexed fields. */ $values = $connector->send(new PutDocumentFieldsRequest($fileCabinetId, $documentId, [ $fieldName => $newValue, $field2Name => $new2Value, ]))->dto(); /** * Upload new document. */ $document = $connector->send(new PostDocumentRequest($fileCabinetId, $fileContent, $fileName))->dto(); /** * Get total document count. */ $content = $connector->send(new GetDocumentCountRequest($fileCabinetId, $dialogId))->dto(); /** * Upload new document with index values. */ use Klongchu\DocuWare\DTO\DocumentIndex; $indexes = collect([ DocumentIndex::make('DOCUMENT_TEXT', 'Indexed Text'), DocumentIndex::make('DOCUMENT_NUMBER', 42), ]); $document = $connector->send(new PostDocumentRequest( $fileCabinetId, $fileContent, $fileName, $indexes, ))->dto(); /** * Delete document. */ $connector->send(new DeleteDocumentRequest($fileCabinetId, $document->id))->dto();
🔍 搜索使用
use Klongchu\DocuWare\Facades\DocuWare; use Klongchu\DocuWare\Connectors\DocuWareWithoutCookieConnector; $connector = new DocuWareWithoutCookieConnector(); /** * Most basic example to search for documents. You only need to provide a valid * file cabinet id. */ $fileCabinetId = '87356f8d-e50c-450b-909c-4eaccd318fbf'; $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($fileCabinetId) ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * Search in multiple file cabinets. Provide an array of file cabinet ids. */ $fileCabinetIds = [ '0ee72de3-4258-4353-8020-6a3ff6dd650f', '3f9cb4ff-82f2-44dc-b439-dd648269064f', ]; $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinets($fileCabinetIds) ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * Find results on the next page. * * Default: 1 */ $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($id) ->page(2) ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * Define the number of results which should be shown per page. * * Default: 50 */ $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($id) ->perPage(30) ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * Use the full-text search. You have to activate full-text search in your file * cabinet before you can use this feature. */ $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($id) ->fulltext('My secret document') ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * Search documents which are created from the first of march. */ $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($id) ->filterDate('DWSTOREDATETIME', '>=', Carbon::create(2021, 3, 1)) ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * Search documents which are created until the first of april. */ $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($id) ->filterDate('DWSTOREDATETIME', '<', Carbon::create(2021, 4, 1)) ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * Order the results by field name. Supported values: 'asc', 'desc' */ $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($id) ->orderBy('DWSTOREDATETIME', 'desc') ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * Search documents filtered to the value. You can specify multiple filters. */ $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($id) ->filter('TYPE', 'Order') ->filter('OTHER_FIELD', 'other') ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * You can specify the dialog which should be used. */ $dialogId = 'bb42c30a-89fc-4b81-9091-d7e326caba62'; $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($id) ->dialog($dialogId) ->get(); $paginator = $connector->send($paginatorRequest)->dto(); /** * You can also combine everything. */ $paginatorRequest = DocuWare::searchRequestBuilder() ->fileCabinet($id) ->page(2) ->perPage(30) ->fulltext('My secret document') ->filterDate('DWSTOREDATETIME', '>=', Carbon::create(2021, 3, 1)) ->filterDate('DWSTOREDATETIME','<',Carbon::create(2021, 4, 1)) ->filter('TYPE', 'Order') ->filter('OTHER_FIELD', 'other') ->orderBy('DWSTOREDATETIME', 'desc') ->dialog($dialogId) ->get(); $paginator = $connector->send($paginatorRequest)->dto();
🖼️ 创建加密 URL
use Klongchu\DocuWare\Facades\DocuWare; /** * Make encrypted URL for a document in a file cabinet. */ $fileCabinetId = '87356f8d-e50c-450b-909c-4eaccd318fbf'; $documentId = 42; $url = DocuWare::url() ->fileCabinet($fileCabinetId) ->document($documentId) ->make(); /** * Make encrypted URL for a document in a basket. */ $basketId = 'b_87356f8d-e50c-450b-909c-4eaccd318fbf'; $url = DocuWare::url() ->basket($basketId) ->document($documentId) ->make(); /** * Make encrypted URL valid for a specific amount of time. In the example below * the URL is valid for one week. Afterwards the URL is no longer working. */ $url = DocuWare::url() ->fileCabinet($fileCabinetId) ->document($documentId) ->validUntil(now()->addWeek()) ->make();
请参阅 测试 获取更多详细信息。
🏋️ DTO 展示
Klongchu\DocuWare\DTO\OrganizationIndex { +id: "2f071481-095d-4363-abd9-29ef845a8b05" // string +name: "Fake File Cabinet" // string +guid: "1334c006-f095-4ae7-892b-fe59282c8bed" // string|null }
Klongchu\DocuWare\DTO\Organization { +id: "2f071481-095d-4363-abd9-29ef845a8b05" // string +name: "Fake File Cabinet" // string +guid: "1334c006-f095-4ae7-892b-fe59282c8bed" // string|null +additionalInfo: [] // array +configurationRights: [] // array }
Klongchu\DocuWare\DTO\FileCabinet { +id: "2f071481-095d-4363-abd9-29ef845a8b05" // string +name: "Fake File Cabinet" // string +color: "Yellow" // string +isBasket: true // bool +assignedCabinet: "889c13cc-c636-4759-a704-1e6500d2d70f" // string }
Klongchu\DocuWare\DTO\Dialog { +id: "fae3b667-53e9-48dd-9004-34647a26112e" // string +type: "ResultList" // string +label: "Fake Dialog" // string +isDefault: true // boolean +fileCabinetId: "1334c006-f095-4ae7-892b-fe59282c8bed" // string }
Klongchu\DocuWare\DTO\Field { +name: "FAKE_FIELD" // string +label: "Fake Field" // string +type: "Memo" // string +scope: "User" // string
Klongchu\DocuWare\DTO\Field { +name: "FAKE_FIELD" // string +label: "Fake Field" // string +type: "Memo" // string +scope: "User" // string
Klongchu\DocuWare\DTO\Document { +id: 659732 // integer +file_size: 765336 // integer +total_pages: 100 // integer +title: "Fake Title" // string +extension: ".pdf" // string +content_type: "application/pdf" // string +file_cabinet_id: "a233b03d-dc63-42dd-b774-25b3ff77548f" // string +created_at: Illuminate\Support\Carbon // Carbon +updated_at: Illuminate\Support\Carbon // Carbon +fields: Illuminate\Support\Collection { // Collection|DocumentField[] #items: array:2 [ 0 => Klongchu\DocuWare\DTO\DocumentField // DocumentField 1 => Klongchu\DocuWare\DTO\DocumentField // DocumentField ] } }
Klongchu\DocuWare\DTO\DocumentThumbnail { +mime: "image/png" // string +data: "somedata" // string +base64: "data:image/png;base64,WXpJNWRGcFhVbWhrUjBVOQ==" // string }
Klongchu\DocuWare\DTO\TableRow { +fields: Illuminate\Support\Collection { // Collection|DocumentField[] #items: array:2 [ 0 => Klongchu\DocuWare\DTO\DocumentField // DocumentField 1 => Klongchu\DocuWare\DTO\DocumentField // DocumentField ] }
Klongchu\DocuWare\DTO\DocumentPaginator +total: 39 // integer +per_page: 10 // integer +current_page: 9 // integer +last_page: 15 // integer +from: 1 // integer +to: 10 // integer +documents: Illuminate\Support\Collection { // Collection|Document[] #items: array:2 [ 0 => Klongchu\DocuWare\DTO\Document // Document 1 => Klongchu\DocuWare\DTO\Document // Document ] } +error: Klongchu\DocuWare\DTO\ErrorBag { // ErrorBag|null +code: 422 // int +message: "'000' is not valid cabinet id" // string } }
🔐 身份验证
您只需提供正确的凭据。其他一切都将由包自动处理。在底层，我们将身份验证 cookie 存储在名为 docuware.cookies 的缓存中。
您可以通过运行 php artisan docuware:list-auth-cookie 命令来获取您的身份验证会话，您可以在 .env 文件的 DOCUWARE_COOKIES 键中使用它。
但是，如果您需要进一步的控制，您可以使用以下方法使用 DocuWare 登录和注销
use Klongchu\DocuWare\Facades\DocuWare; /** * Login with your credentials. You only need to login once. Afterwards the * authentication cookie is stored in the cache as `docuware.cookies` and * is used for all further requests. */ DocuWare::login(); /** * Logout your current session. Removes the authentication cookie in the cache. */ DocuWare::logout();
手动身份验证
如果您想提供自己的身份验证 cookie，可以使用以下连接器使用 DocuWare REST API 进行身份验证
use Klongchu\DocuWare\Connectors\StaticCookieConnector;
💥 异常解释
Klongchu\DocuWare\Exceptions\UnableToMakeRequest
如果您没有权限进行请求，则会抛出此异常。
Klongchu\DocuWare\Exceptions\UnableToProcessRequest
如果传递了错误的属性，则会抛出此异常。例如，一个不存在的文件柜 ID。
Klongchu\DocuWare\Exceptions\UnableToLogin
如果凭据不匹配，则此异常只能在登录时抛出。
Klongchu\DocuWare\Exceptions\UnableToLoginNoCookies
如果 API 响应中没有 cookie，则此异常只能在登录时抛出。
Klongchu\DocuWare\Exceptions\UnableToFindPassphrase
如果无法找到密码短语，则此异常只能在创建 URL 时抛出。
Klongchu\DocuWare\Exceptions\UnableToMakeUrl
创建 URL 时出现错误。
Klongchu\DocuWare\Exceptions\UnableToUpdateFields
未提供任何字段。
Klongchu\DocuWare\Exceptions\UnableToGetDocumentCount
获取文档计数响应有误。
Illuminate\Http\Client\RequestException
如果响应不是成功的所有其他情况。
✨ 事件
以下事件将被触发
use Klongchu\DocuWare\Events\DocuWareResponseLog; // Log each response from the DocuWare REST API. DocuWareResponseLog::class => [ // ],
🔧 配置文件
您可以使用以下命令发布配置文件
php artisan vendor:publish --provider="Klongchu\DocuWare\DocuWareServiceProvider" --tag="docuware-config"
这是发布配置文件的内容
<?php return [ /* |-------------------------------------------------------------------------- | Connection |-------------------------------------------------------------------------- | Select a connector to authenticate with. You can choose between: WITHOUT_COOKIE, STATIC_COOKIE | */ 'connection' => ConnectionEnum::WITHOUT_COOKIE, /* |-------------------------------------------------------------------------- | 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')), /* |-------------------------------------------------------------------------- | Cookies |-------------------------------------------------------------------------- | This variable is optional and only used if you want to set the request cookie manually. | */ 'cookies' => env('DOCUWARE_COOKIES'), /* |-------------------------------------------------------------------------- | 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'), /* |-------------------------------------------------------------------------- | Authentication Cookie Lifetime |-------------------------------------------------------------------------- | | Here you may define the amount of minutes the authentication cookie is | valid. Afterwards it will be removed from the cache and you need to | provide a fresh one. By default, the lifetime lasts for one year. | */ 'cookie_lifetime' => (int) env('DOCUWARE_COOKIE_LIFETIME', 525600), /* |-------------------------------------------------------------------------- | 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' => false, '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), ], ], /* |-------------------------------------------------------------------------- | Tests |-------------------------------------------------------------------------- | */ 'tests' => [ 'file_cabinet_id' => env('DOCUWARE_TESTS_FILE_CABINET_ID'), 'dialog_id' => env('DOCUWARE_TESTS_DIALOG_ID'), 'basket_id' => env('DOCUWARE_TESTS_BASKET_ID'), 'organization_id' => env('DOCUWARE_TESTS_ORGANIZATION_ID'), ], ];
🚧 测试
复制您自己的phpunit.xml文件。
cp phpunit.xml.dist phpunit.xml
修改phpunit.xml文件中的环境变量
<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_COOKIES" value="cookies"/> <env name="DOCUWARE_TIMEOUT" value="15"/> <env name="DOCUWARE_CACHE_LIFETIME_IN_SECONDS" value="0"/> // Disable caching for tests <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）。请查看许可证文件以获取更多信息。