通过
进行搜索
进行搜索klongchu / laravel-docuware-fix-budhosp
DocuWare与Laravel集成
dev-main
2024-04-24 09:43 UTC
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.5
- illuminate/contracts: ^9.0|^10.0|^11.0
- nesbot/carbon: ^2.64.0
- spatie/laravel-package-tools: ^1.14.0
Requires (Dev)
- laravel/pint: ^1.0
- nunomaduro/larastan: ^2.0.1
- orchestra/testbench: ^7.7|^8.0
- pestphp/pest: ^1.21
- phpstan/extension-installer: ^1.1
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- spatie/laravel-ray: ^1.26
This package is auto-updated.
Last update: 2024-09-24 10:33:27 UTC
README
本软件包旨在为您提供快速入门与DocuWare REST API通信。它用于查询最常用的端点。
⚠️ 本软件包不是官方DocuWare REST API的替代品。如需进一步的功能，请参阅文档。⚠️
💡 什么是DocuWare？
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 codebar-ag/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 CodebarAg\DocuWare\Facades\DocuWare; /** * Return all file cabinets. */ $cabinets = DocuWare::getFileCabinets(); /** * Return all fields of a file cabinet. */ $fields = DocuWare::getFields($fileCabinetId); /** * Return all dialogs of a file cabinet. */ $dialogs = DocuWare::getDialogs($fileCabinetId); /** * Return all used values for a specific field. */ $values = DocuWare::getSelectList($fileCabinetId, $dialogId, $fieldName); /** * Return a document. */ $document = DocuWare::getDocument($fileCabinetId, $documentId); /** * Return image preview of a document. */ $content = DocuWare::getDocumentPreview($fileCabinetId, $documentId); /** * Download single document. */ $content = DocuWare::downloadDocument($fileCabinetId, $documentId); /** * Download multiple documents. */ $content = DocuWare::downloadDocuments($fileCabinetId, $documentIds); /** * Update value of a indexed field. */ $value = DocuWare::updateDocumentValue($fileCabinetId, $documentId, $fieldName, $newValue); /** * Upload new document. */ $document = DocuWare::uploadDocument($fileCabinetId, $fileContent, $fileName); /** * Upload new document with index values. */ use CodebarAg\DocuWare\DTO\DocumentIndex; $indexes = collect([ DocumentIndex::make('DOCUMENT_TEXT', 'Indexed Text'), DocumentIndex::make('DOCUMENT_NUMBER', 42), ]); $document = DocuWare::uploadDocument( $fileCabinetId, $fileContent, $fileName, $indexes, ); /** * Delete document. */ DocuWare::deleteDocument($fileCabinetId, $documentId);
🔍 搜索使用
use CodebarAg\DocuWare\Facades\DocuWare; /** * Most basic example to search for documents. You only need to provide a valid * file cabinet id. */ $id = '87356f8d-e50c-450b-909c-4eaccd318fbf'; $paginator = DocuWare::search() ->fileCabinet($id) ->get(); /** * Search in multiple file cabinets. Provide an array of file cabinet ids. */ $fileCabinetIds = [ '0ee72de3-4258-4353-8020-6a3ff6dd650f', '3f9cb4ff-82f2-44dc-b439-dd648269064f', ]; $paginator = DocuWare::search() ->fileCabinets($fileCabinetIds) ->get(); /** * Find results on the next page. * * Default: 1 */ $paginator = DocuWare::search() ->fileCabinet($id) ->page(2) ->get(); /** * Define the number of results which should be shown per page. * * Default: 50 */ $paginator = DocuWare::search() ->fileCabinet($id) ->perPage(30) ->get(); /** * Use the full-text search. You have to activate full-text search in your file * cabinet before you can use this feature. */ $paginator = DocuWare::search() ->fileCabinet($id) ->fulltext('My secret document') ->get(); /** * Search documents which are created from the first of march. */ $paginator = DocuWare::search() ->fileCabinet($id) ->filterDate('DWSTOREDATETIME', '>=', Carbon::create(2021, 3, 1)) ->get(); /** * Search documents which are created until the first of april. */ $paginator = DocuWare::search() ->fileCabinet($id) ->filterDate('DWSTOREDATETIME', '<', Carbon::create(2021, 4, 1)) ->get(); /** * Order the results by field name. Supported values: 'asc', 'desc' */ $paginator = DocuWare::search() ->fileCabinet($id) ->orderBy('DWSTOREDATETIME', 'desc') ->get(); /** * Search documents filtered to the value. You can specify multiple filters. */ $paginator = DocuWare::search() ->fileCabinet($id) ->filter('TYPE', 'Order') ->filter('OTHER_FIELD', 'other') ->get(); /** * You can specify the dialog which should be used. */ $dialogId = 'bb42c30a-89fc-4b81-9091-d7e326caba62'; $paginator = DocuWare::search() ->fileCabinet($id) ->dialog($dialogId) ->get(); /** * You can also combine everything. */ $paginator = DocuWare::search() ->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();
🖼️ 创建加密URL
use CodebarAg\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示例
CodebarAg\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 }
CodebarAg\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 }
CodebarAg\DocuWare\DTO\Field { +name: "FAKE_FIELD" // string +label: "Fake Field" // string +type: "Memo" // string +scope: "User" // string
CodebarAg\DocuWare\DTO\Field { +name: "FAKE_FIELD" // string +label: "Fake Field" // string +type: "Memo" // string +scope: "User" // string
CodebarAg\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 => CodebarAg\DocuWare\DTO\DocumentField // DocumentField 1 => CodebarAg\DocuWare\DTO\DocumentField // DocumentField ] } }
CodebarAg\DocuWare\DTO\TableRow { +fields: Illuminate\Support\Collection { // Collection|DocumentField[] #items: array:2 [ 0 => CodebarAg\DocuWare\DTO\DocumentField // DocumentField 1 => CodebarAg\DocuWare\DTO\DocumentField // DocumentField ] }
CodebarAg\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 => CodebarAg\DocuWare\DTO\Document // Document 1 => CodebarAg\DocuWare\DTO\Document // Document ] } +error: CodebarAg\DocuWare\DTO\ErrorBag { // ErrorBag|null +code: 422 // int +message: "'000' is not valid cabinet id" // string } }
🔐 身份验证
您只需提供正确的凭据。其他一切都将由软件包自动处理。在底层，我们将在名为docuware.cookies的缓存中存储身份验证cookie。
您可以使用php artisan docuware:list-auth-cookie命令来获取您的认证会话，您可以在.env文件中的DOCUWARE_COOKIES键中使用此会话。
但如果您需要进一步的控制，您可以使用以下方法使用DocuWare进行登录和登出
use CodebarAg\DocuWare\Facades\DocuWare; /** * Login with your credentials. You only need to login once. Afterwards the * authentication cookie is stored in the cache `docuware.cookies` and is * used for all further requests. */ DocuWare::login(); /** * Logout your current session. Removes the authentication cookie in the cache. */ DocuWare::logout();
💥 异常说明
CodebarAg\DocuWare\Exceptions\UnableToMakeRequest
如果您没有权限发起请求，则会抛出此异常。
CodebarAg\DocuWare\Exceptions\UnableToProcessRequest
如果您传递了错误的属性，则会抛出此异常。例如，一个不存在的文件柜ID。
CodebarAg\DocuWare\Exceptions\UnableToLogin
如果凭据不匹配，则只能在登录过程中抛出此异常。
CodebarAg\DocuWare\Exceptions\UnableToFindPassphrase
如果无法找到密语，则只能在创建URL时抛出此异常。
CodebarAg\DocuWare\Exceptions\UnableToMakeUrl
在创建URL时发生错误。
Illuminate\Http\Client\RequestException
如果响应不是成功的所有其他情况。
✨ 事件
以下事件将被触发
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')), /* |-------------------------------------------------------------------------- | 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', 30), /* |-------------------------------------------------------------------------- | 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' => [], ], ], /* |-------------------------------------------------------------------------- | 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'), 'document_id' => (int) env('DOCUWARE_TESTS_DOCUMENT_ID'), 'document_file_size_preview' => (int) env('DOCUWARE_TESTS_DOCUMENT_FILE_SIZE_PREVIEW'), 'document_file_size' => (int) env('DOCUWARE_TESTS_DOCUMENT_FILE_SIZE'), 'document_ids' => json_decode(env('DOCUWARE_TESTS_DOCUMENTS_IDS')), 'documents_file_size' => (int) env('DOCUWARE_TESTS_DOCUMENTS_FILE_SIZE'), 'field_name' => env('DOCUWARE_TESTS_FIELD_NAME'), ], ];
🚧 测试
复制您的自己的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="30"/> <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_FIELD_NAME" value="UUID"/> <env name="DOCUWARE_TESTS_DOCUMENT_FILE_SIZE_PREVIEW" value=""/> <env name="DOCUWARE_TESTS_DOCUMENT_FILE_SIZE" value=""/> <env name="DOCUWARE_TESTS_DOCUMENTS_FILE_SIZE" value=""/> <env name="DOCUWARE_TESTS_DOCUMENT_ID" value=""/> <env name="DOCUWARE_TESTS_DOCUMENTS_IDS" value="[]"/>
运行测试
composer test
📝 更新日志
请参阅更新日志以获取有关最近更改的更多信息。
✏️ 贡献
有关详细信息，请参阅CONTRIBUTING。
🧑💻 安全漏洞
请查看我们的安全策略，了解如何报告安全漏洞。
🙏致谢
🎭许可
MIT许可（MIT）。请参阅许可文件获取更多信息。