Feature/489 add documentgenerator v3

.php-cs-fixer.php

@@ -18,6 +18,7 @@
     ->in(__DIR__ . '/src/Services/CRM/Documentgenerator/Numerator/')
     ->in(__DIR__ . '/src/Services/CRM/Documentgenerator/Document/')
     ->in(__DIR__ . '/src/Services/CRM/Documentgenerator/Template/')
+    ->in(__DIR__ . '/src/Services/Documentgenerator/')
     ->in(__DIR__ . '/src/Services/Entity/Section/')
     ->in(__DIR__ . '/src/Services/Department/')
     ->in(__DIR__ . '/src/Services/Landing/')

.tasks/489/plan.md

@@ -0,0 +1,190 @@
+# Plan: Add support for documentgenerator.document.* and documentgenerator.template.* methods (issue #489)
+
+## Context
+
+This issue adds SDK support for the `documentgenerator.document.*` REST API methods — the
+**non-CRM** Document Generator scope. Unlike `crm.documentgenerator.document.*`, these methods
+work with any data provider, not just CRM entities.
+
+Key differences from the CRM scope (`src/Services/CRM/Documentgenerator/Document/`):
+
+| Aspect | CRM scope | documentgenerator scope |
+|---|---|---|
+| Method prefix | `crm.documentgenerator.document.` | `documentgenerator.document.` |
+| `add` params | `templateId`, `entityTypeId`, `entityId` | `templateId`, `providerClassName`, `value` |
+| `update` extra params | `values`, `stampsEnabled` | `values`, `fields`, `stampsEnabled` |
+| SDK scope | `['crm']` | `['documentgenerator']` |
+| Builder access | `getCRMScope()->documentgeneratorDocument()` | `getDocumentgeneratorScope()->document()` |
+
+Response shape for `list`: `result.documents[]` (same key as CRM).
+Response shape for `get/add`: `result.document{}` (same key as CRM).
+
+Custom `Batch` class is required because the API uses lowercase `id` for delete/update and
+wraps list results under the `documents` key (same as CRM version).
+
+---
+
+## Files Created
+
+### Source files
+1. `src/Services/Documentgenerator/Document/Result/DocumentItemResult.php` — item result with field type casting
+2. `src/Services/Documentgenerator/Document/Result/DocumentResult.php` — single document result
+3. `src/Services/Documentgenerator/Document/Result/DocumentsResult.php` — list of documents result
+4. `src/Services/Documentgenerator/Document/Result/AddedDocumentResult.php` — add result
+5. `src/Services/Documentgenerator/Document/Result/AddedDocumentBatchResult.php` — batch add result
+6. `src/Services/Documentgenerator/Document/Result/DeletedDocumentResult.php` — delete result
+7. `src/Services/Documentgenerator/Document/Result/DeletedDocumentBatchResult.php` — batch delete result
+8. `src/Services/Documentgenerator/Document/Result/UpdatedDocumentResult.php` — update result
+9. `src/Services/Documentgenerator/Document/Result/UpdatedDocumentBatchResult.php` — batch update result
+10. `src/Services/Documentgenerator/Document/Result/DocumentFieldsResult.php` — getFields result
+11. `src/Services/Documentgenerator/Document/Result/PublicUrlResult.php` — enablePublicUrl result
+12. `src/Services/Documentgenerator/Document/Batch.php` — custom Batch override (lowercase id, documents wrapper)
+13. `src/Services/Documentgenerator/Document/Service/Batch.php` — service-level batch wrapper
+14. `src/Services/Documentgenerator/Document/Service/Document.php` — main service class
+15. `src/Services/Documentgenerator/DocumentgeneratorServiceBuilder.php` — scope builder
+
+### Test files
+16. `tests/Integration/Services/Documentgenerator/Document/Service/DocumentTest.php`
+17. `tests/Integration/Services/Documentgenerator/Document/Service/BatchTest.php`
+
+---
+
+## Files Modified
+
+### 1. `src/Services/ServiceBuilder.php`
+- Added `use Bitrix24\SDK\Services\Documentgenerator\DocumentgeneratorServiceBuilder;`
+- Added `getDocumentgeneratorScope(): DocumentgeneratorServiceBuilder` method
+
+### 2. `rector.php`
+- Added paths for `src/Services/Documentgenerator` and `tests/Integration/Services/Documentgenerator`
+
+### 3. `phpunit.xml.dist`
+- Added `integration_tests_scope_documentgenerator` and `integration_tests_documentgenerator_document` test suites
+
+### 4. `Makefile`
+- Added `integration_tests_scope_documentgenerator` and `integration_tests_documentgenerator_document` targets
+
+### 5. `CHANGELOG.md`
+- Added entry under `## 3.3.0 – UNRELEASED → ### Added`
+
+---
+
+## Deptrac compliance
+
+New code lives in `src/Services/Documentgenerator/` which belongs to the `Services` layer.
+It depends only on `Core` (AbstractItem, AbstractResult, AddedItemResult, etc.). No new violations.
+
+---
+
+## Verification
+
+```bash
+make lint-rector
+make lint-phpstan
+make lint-deptrac
+make test-unit
+make integration_tests_documentgenerator_document
+make integration_tests_documentgenerator_template
+make integration_tests_documentgenerator_template_annotations
+```
+
+---
+
+## Phase 2: documentgenerator.template.* (added 2026-05-26)
+
+Template methods are implemented in `src/Services/Documentgenerator/Template/`.
+
+Key differences from CRM variant:
+- `getFields` requires only `id` (no `entityTypeId`)
+- `add` supports `code` and `fileId` fields
+- `update` supports `providers` in fields
+- List response: `result.templates` keyed by id
+- Single-item response: `result.template`
+- Template fields response: `result.templateFields`
+
+### Files Created (Phase 2)
+
+1. `src/Services/Documentgenerator/Template/Result/TemplateItemResult.php`
+2. `src/Services/Documentgenerator/Template/Result/TemplateResult.php`
+3. `src/Services/Documentgenerator/Template/Result/TemplatesResult.php`
+4. `src/Services/Documentgenerator/Template/Result/AddedTemplateResult.php`
+5. `src/Services/Documentgenerator/Template/Result/UpdatedTemplateResult.php`
+6. `src/Services/Documentgenerator/Template/Result/DeletedTemplateResult.php`
+7. `src/Services/Documentgenerator/Template/Result/AddedTemplateBatchResult.php`
+8. `src/Services/Documentgenerator/Template/Result/UpdatedTemplateBatchResult.php`
+9. `src/Services/Documentgenerator/Template/Result/DeletedTemplateBatchResult.php`
+10. `src/Services/Documentgenerator/Template/Result/TemplateFieldsResult.php`
+11. `src/Services/Documentgenerator/Template/Batch.php`
+12. `src/Services/Documentgenerator/Template/Service/Batch.php`
+13. `src/Services/Documentgenerator/Template/Service/Template.php`
+14. `tests/Integration/Services/Documentgenerator/Template/Service/TemplateTest.php`
+15. `tests/Integration/Services/Documentgenerator/Template/Service/BatchTest.php`
+16. `tests/Integration/Services/Documentgenerator/Template/Result/TemplateItemResultAnnotationsTest.php`
+
+### Files Modified (Phase 2)
+
+- `src/Services/Documentgenerator/DocumentgeneratorServiceBuilder.php` — added `template()` method
+- `phpunit.xml.dist` — added 3 new test suites for template
+- `Makefile` — added 3 new make targets
+- `.php-cs-fixer.php` — added `src/Services/Documentgenerator/`
+- `phpstan.neon.dist` — added `tests/Integration/Services/Documentgenerator`
+- `CHANGELOG.md` — added Template entry under `## 3.3.0 – UNRELEASED`
+
+---
+
+## Plan: Add support for documentgenerator.region.* methods (issue #489)
+
+## Context
+
+The Bitrix24 REST API exposes a set of methods for managing document generator regions:
+- `documentgenerator.region.add` — creates a new custom region
+- `documentgenerator.region.update` — updates an existing region by `id` + `fields`
+- `documentgenerator.region.get` — returns a region by `id`
+- `documentgenerator.region.list` — returns a paginated list of regions
+- `documentgenerator.region.delete` — deletes a region by `id` (returns null on success)
+
+All methods belong to scope `documentgenerator`.
+
+API response envelope (verified against `documentgenerator.region.delete` via MCP):
+- Add → `result.region = {...}` (matching pattern of numerator.add)
+- Update → `result = null` (boolean cast = true on success)
+- Get → `result.region = {...}`
+- List → `result.regions = [...]`
+- Delete → `result = null` (boolean cast on result)
+
+Region entity fields (based on API docs):
+- `id` — int
+- `languageId` — string
+- `name` — string
+- `code` — string
+
+All REST methods use lowercase `id` parameter (not `ID`), matching the Numerator pattern.
+A custom `Batch` class (like `Numerator\Batch`) is required to override lowercase `id`
+and `regions` result key handling.
+
+---
+
+## Files to Create
+
+- `src/Services/Documentgenerator/Region/Result/RegionItemResult.php`
+- `src/Services/Documentgenerator/Region/Result/RegionResult.php`
+- `src/Services/Documentgenerator/Region/Result/RegionsResult.php`
+- `src/Services/Documentgenerator/Region/Result/AddedRegionResult.php`
+- `src/Services/Documentgenerator/Region/Result/AddedRegionBatchResult.php`
+- `src/Services/Documentgenerator/Region/Result/UpdatedRegionResult.php`
+- `src/Services/Documentgenerator/Region/Result/UpdatedRegionBatchResult.php`
+- `src/Services/Documentgenerator/Region/Result/DeletedRegionResult.php`
+- `src/Services/Documentgenerator/Region/Result/DeletedRegionBatchResult.php`
+- `src/Services/Documentgenerator/Region/Batch.php`
+- `src/Services/Documentgenerator/Region/Service/Batch.php`
+- `src/Services/Documentgenerator/Region/Service/Region.php`
+- `tests/Integration/Services/Documentgenerator/Region/Service/RegionTest.php`
+- `tests/Integration/Services/Documentgenerator/Region/Service/BatchTest.php`
+- `tests/Integration/Services/Documentgenerator/Region/Result/RegionItemResultAnnotationsTest.php`
+
+## Files to Modify
+
+- `src/Services/Documentgenerator/DocumentgeneratorServiceBuilder.php`
+- `phpunit.xml.dist`
+- `Makefile`
+- `CHANGELOG.md`

CHANGELOG.md

@@ -3,6 +3,51 @@
 
 ### Added
 
+- Added service `Services\Documentgenerator\Role` with support for `documentgenerator.role.*` methods,
+  see [documentgenerator.role.* methods](https://apidocs.bitrix24.com/api-reference/document-generator/role/index.html) ([#489](https://github.com/bitrix24/b24phpsdk/issues/489)):
+    - `add` creates a new role, with batch calls support
+    - `list` gets the list of roles, with batch calls support
+    - `update` updates an existing role, with batch calls support
+    - `delete` deletes a role, with batch calls support
+    - `get` gets information about the role by its identifier (includes permissions)
+    - `fillAccesses` completely replaces the role-to-access-code binding map
+    - `count` counts roles
+- Added service `Services\Documentgenerator\Region` with support for `documentgenerator.region.*` methods,
+  see [documentgenerator.region.* methods](https://apidocs.bitrix24.com/api-reference/document-generator/region/index.html) ([#489](https://github.com/bitrix24/b24phpsdk/issues/489)):
+    - `add` creates a new region, with batch calls support
+    - `list` gets the list of regions, with batch calls support
+    - `update` updates an existing region, with batch calls support
+    - `delete` deletes a region, with batch calls support
+    - `get` gets information about the region by its identifier
+    - `count` counts regions
+- Added service `Services\Documentgenerator\Numerator` with support for `documentgenerator.numerator.*` methods,
+  see [documentgenerator.numerator.* methods](https://apidocs.bitrix24.com/api-reference/document-generator/numerators/index.html) ([#489](https://github.com/bitrix24/b24phpsdk/issues/489)):
+    - `add` creates a new numerator, with batch calls support
+    - `list` gets the list of numerators, with batch calls support
+    - `update` updates an existing numerator, with batch calls support
+    - `delete` deletes a numerator, with batch calls support
+    - `get` gets information about the numerator by its identifier
+    - `count` counts numerators
+- Added service `Services\Documentgenerator\Template` with support for `documentgenerator.template.*` methods,
+  see [documentgenerator.template.* methods](https://apidocs.bitrix24.com/api-reference/document-generator/templates/index.html) ([#489](https://github.com/bitrix24/b24phpsdk/issues/489)):
+    - `add` creates a new template, with batch calls support
+    - `list` gets the list of templates, with batch calls support
+    - `update` updates an existing template, with batch calls support
+    - `delete` deletes a template, with batch calls support
+    - `get` gets information about the template by its identifier
+    - `getFields` returns the description of template fields
+    - `count` counts templates
+- Added service `Services\Documentgenerator\Document` with support for `documentgenerator.document.*` methods,
+  see [documentgenerator.document.* methods](https://apidocs.bitrix24.com/api-reference/document-generator/index.html) ([#489](https://github.com/bitrix24/b24phpsdk/issues/489)):
+    - `add` creates a new document based on a template and data provider, with batch calls support
+    - `list` gets the list of documents, with batch calls support
+    - `update` updates an existing document, with batch calls support
+    - `delete` deletes a document, with batch calls support
+    - `get` gets information about the document by its identifier
+    - `getFields` returns the description of document fields
+    - `enablePublicUrl` enables or disables public URL for a document
+    - `count` counts documents
+
 ### Changed
 
 ### Fixed

Makefile

@@ -635,6 +635,62 @@ integration_tests_crm_documentgenerator_document:
 integration_tests_crm_documentgenerator_template:
 	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_crm_documentgenerator_template
 
+.PHONY: integration_tests_scope_documentgenerator
+integration_tests_scope_documentgenerator:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_scope_documentgenerator
+
+.PHONY: integration_tests_documentgenerator_document
+integration_tests_documentgenerator_document:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_document
+
+.PHONY: integration_tests_documentgenerator_template
+integration_tests_documentgenerator_template:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_template
+
+.PHONY: integration_tests_documentgenerator_template_service
+integration_tests_documentgenerator_template_service:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_template_service
+
+.PHONY: integration_tests_documentgenerator_template_annotations
+integration_tests_documentgenerator_template_annotations:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_template_annotations
+
+.PHONY: integration_tests_documentgenerator_numerator
+integration_tests_documentgenerator_numerator:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_numerator
+
+.PHONY: integration_tests_documentgenerator_numerator_service
+integration_tests_documentgenerator_numerator_service:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_numerator_service
+
+.PHONY: integration_tests_documentgenerator_numerator_annotations
+integration_tests_documentgenerator_numerator_annotations:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_numerator_annotations
+
+.PHONY: integration_tests_documentgenerator_region
+integration_tests_documentgenerator_region:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_region
+
+.PHONY: integration_tests_documentgenerator_region_service
+integration_tests_documentgenerator_region_service:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_region_service
+
+.PHONY: integration_tests_documentgenerator_region_annotations
+integration_tests_documentgenerator_region_annotations:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_region_annotations
+
+.PHONY: integration_tests_documentgenerator_role
+integration_tests_documentgenerator_role:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_role
+
+.PHONY: integration_tests_documentgenerator_role_service
+integration_tests_documentgenerator_role_service:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_role_service
+
+.PHONY: integration_tests_documentgenerator_role_annotations
+integration_tests_documentgenerator_role_annotations:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_documentgenerator_role_annotations
+
 # work dev environment
 .PHONY: php-dev-server-up
 php-dev-server-up:

phpstan.neon.dist

@@ -38,6 +38,7 @@ parameters:
     - tests/Integration/Services/CRM/Documentgenerator/Numerator
     - tests/Integration/Services/CRM/Documentgenerator/Document
     - tests/Integration/Services/CRM/Documentgenerator/Template
+    - tests/Integration/Services/Documentgenerator
   excludePaths:
     # TODO: Fix type errors in RequisiteUserfieldUseCaseTest and remove this exclusion
     # Tracking: https://github.com/bitrix24/b24phpsdk/issues

phpunit.xml.dist

@@ -329,6 +329,48 @@
         <testsuite name="integration_tests_crm_documentgenerator_template">
             <directory>./tests/Integration/Services/CRM/Documentgenerator/Template/</directory>
         </testsuite>
+        <testsuite name="integration_tests_scope_documentgenerator">
+            <directory>./tests/Integration/Services/Documentgenerator/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_document">
+            <directory>./tests/Integration/Services/Documentgenerator/Document/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_template">
+            <directory>./tests/Integration/Services/Documentgenerator/Template/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_template_service">
+            <directory>./tests/Integration/Services/Documentgenerator/Template/Service/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_template_annotations">
+            <file>./tests/Integration/Services/Documentgenerator/Template/Result/TemplateItemResultAnnotationsTest.php</file>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_numerator">
+            <directory>./tests/Integration/Services/Documentgenerator/Numerator/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_numerator_service">
+            <directory>./tests/Integration/Services/Documentgenerator/Numerator/Service/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_numerator_annotations">
+            <file>./tests/Integration/Services/Documentgenerator/Numerator/Result/NumeratorItemResultAnnotationsTest.php</file>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_region">
+            <directory>./tests/Integration/Services/Documentgenerator/Region/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_region_service">
+            <directory>./tests/Integration/Services/Documentgenerator/Region/Service/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_region_annotations">
+            <file>./tests/Integration/Services/Documentgenerator/Region/Result/RegionItemResultAnnotationsTest.php</file>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_role">
+            <directory>./tests/Integration/Services/Documentgenerator/Role/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_role_service">
+            <directory>./tests/Integration/Services/Documentgenerator/Role/Service/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_documentgenerator_role_annotations">
+            <file>./tests/Integration/Services/Documentgenerator/Role/Result/RoleItemResultAnnotationsTest.php</file>
+        </testsuite>
         <testsuite name="integration_tests_scope_sonet_group">
             <directory>./tests/Integration/Services/SonetGroup/</directory>
         </testsuite>