Add ApplicationSettings bounded context for issue #67

.github/workflows/license-check.yml

@@ -37,7 +37,7 @@ jobs:
         run: "composer update --no-interaction --no-progress --no-suggest"
 
       - name: "composer-license-checker"
-        run: "make lint-allowed-licenses"
+        run: "php vendor/bin/composer-license-checker"
 
       - name: "is allowed licenses check succeeded"
         if: ${{ success() }}

CHANGELOG.md

@@ -1,3 +1,96 @@
+
+
+
+## 0.1.2
+### Added
+- **ApplicationSettings bounded context** for application configuration management — [#67](https://github.com/mesilov/bitrix24-php-lib/issues/67)
+  - Full CRUD functionality with CQRS pattern (Create, Update, Delete use cases)
+  - Multi-scope support: Global, Departmental, and Personal settings with cascading resolution
+  - **SettingsFetcher service** with automatic deserialization support
+    - Cascading resolution logic (Personal → Departmental → Global)
+    - JSON deserialization to objects using Symfony Serializer
+    - Comprehensive logging with LoggerInterface
+  - **InstallSettings service** for bulk creation of default settings
+  - Soft-delete support with `ApplicationSettingStatus` enum (Active/Deleted)
+  - Event system with `ApplicationSettingsItemChangedEvent` for change tracking
+  - CLI command `app:settings:list` for viewing settings with scope filtering
+  - InMemory repository implementation for fast unit testing
+  - Unique constraint on (installation_id, key, user_id, department_id)
+  - Tracking fields: `changedByBitrix24UserId`, `isRequired`
+- Database schema updates
+  - Table `application_settings` with UUID v7 IDs
+  - Scope fields: `b24_user_id`, `b24_department_id`
+  - Status field with index for query optimization
+  - Timestamp tracking: `created_at_utc`, `updated_at_utc`
+- Comprehensive test coverage
+  - Unit tests for entity validation and business logic
+  - Functional tests for repository operations and use case handlers
+  - Tests for all scope types and soft-delete behavior
+
+### Changed
+- **Refactored ApplicationSettings entity naming**
+  - Renamed `ApplicationSetting` → `ApplicationSettingsItem`
+  - Renamed all interfaces and events accordingly
+  - Updated table name from `application_setting` → `application_settings`
+- **Separated Create/Update use cases**
+  - Create UseCase now only creates new settings (throws exception if exists)
+  - Update UseCase for modifying existing settings (throws exception if not found)
+  - Update automatically emits `ApplicationSettingsItemChangedEvent`
+- **Simplified repository API**
+  - Removed 6 redundant methods, kept only `findAllForInstallation()`
+  - Renamed `findAll()` → `findAllForInstallationByKey()` to avoid conflicts
+  - All find methods now filter by `status=Active` by default
+  - Added optimized `findAllForInstallationByKey()` method
+- **Enhanced SettingsFetcher**
+  - Renamed `getSetting()` → `getItem()`
+  - Renamed `getSettingValue()` → `getValue()`
+  - Added automatic deserialization with type-safe generics
+  - Non-nullable return types with exception throwing
+- **ApplicationSettingsItem improvements**
+  - UUID v7 generation moved inside entity constructor
+  - Key validation: only lowercase latin letters and dots
+  - Scope methods: `isGlobal()`, `isPersonal()`, `isDepartmental()`
+  - `updateValue()` method emits change events
+- **Makefile improvements**
+  - Updated to use Docker for `composer-license-checker`
+  - Aligns with other linting and analysis workflows
+- **Code quality improvements**
+  - Applied Rector automatic refactoring (arrow functions, type hints, naming)
+  - Added `#[\Override]` attributes to overridden methods
+  - Applied PHP-CS-Fixer formatting consistently
+  - Added symfony/property-access dependency for ObjectNormalizer
+- **Documentation improvements**
+  - Translated ApplicationSettings documentation to English
+  - Updated all code examples to reflect current codebase
+  - Corrected exception class names (SettingsItemAlreadyExistsException, SettingsItemNotFoundException)
+  - Improved best practices and security sections
+
+### Fixed
+- **PHPStan level 5 errors related to SDK interface compatibility** — [#67](https://github.com/mesilov/bitrix24-php-lib/issues/67)
+  - Removed invalid `#[\Override]` attributes from extension methods in `ApplicationInstallationRepository`
+  - Fixed `findByMemberId()` call with incorrect parameter count in `OnAppInstall\Handler`
+  - Added `@phpstan-ignore-next-line` comments for methods not yet available in SDK interface
+  - Added TODO comments to track SDK interface extension requirements
+- **Doctrine XML mapping**
+  - Fixed `enumType` → `enum-type` syntax for Doctrine ORM 3 compatibility
+- **Repository method naming conflicts**
+  - Renamed methods to avoid conflicts with EntityRepository base class
+- **Exception handling**
+  - Added `SettingsItemAlreadyExistsException` for Create use case
+  - Added `SettingsItemNotFoundException` for Get/Delete operations
+  - Updated all handlers to throw specific exceptions
+
+### Removed
+- **Get UseCase** - replaced with `SettingsFetcher` service (UseCases now only for data modification)
+- **Redundant repository methods**
+  - `findGlobalByKey()`, `findPersonalByKey()`, `findDepartmentalByKey()`
+  - `findAllGlobal()`, `findAllPersonal()`, `findAllDepartmental()`
+  - `deleteByApplicationInstallationId()`
+  - `softDeleteByApplicationInstallationId()`
+- **Hard delete from Delete UseCase** - replaced with soft-delete pattern
+- **Entity getStatus() method** - use `isActive()` instead for better encapsulation
+- **Static getRecommendedDefaults()** - developers should define their own defaults
+
 ## 0.1.1
 ### Added
 - Change php version requirements — [#44](https://github.com/mesilov/bitrix24-php-lib/pull/44)

Makefile

@@ -90,7 +90,7 @@ composer:
 
 # check allowed licenses
 lint-allowed-licenses:
-	vendor/bin/composer-license-checker
+	docker-compose run --rm php-cli php vendor/bin/composer-license-checker
 # linters
 lint-phpstan:
 	docker-compose run --rm php-cli php vendor/bin/phpstan analyse --memory-limit 2G

composer.json

@@ -59,17 +59,18 @@
     "symfony/dotenv": "^7"
   },
   "require-dev": {
-    "lendable/composer-license-checker": "^1.2",
+    "doctrine/migrations": "^3",
+    "fakerphp/faker": "^1",
     "friendsofphp/php-cs-fixer": "^3.64",
+    "lendable/composer-license-checker": "^1.2",
     "monolog/monolog": "^3",
-    "fakerphp/faker": "^1",
     "phpstan/phpstan": "^1",
     "phpunit/phpunit": "^11",
-    "doctrine/migrations": "^3",
     "psalm/phar": "^5",
     "rector/rector": "^1",
     "roave/security-advisories": "dev-master",
     "symfony/debug-bundle": "^7",
+    "symfony/property-access": "^7.3",
     "symfony/stopwatch": "^7"
   },
   "autoload": {

config/xml/Bitrix24.Lib.ApplicationSettings.Entity.ApplicationSettingsItem.dcm.xml

@@ -0,0 +1,42 @@
+<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                  xmlns:xs="https://www.w3.org/2001/XMLSchema"
+                  xmlns:orm="https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+    <entity name="Bitrix24\Lib\ApplicationSettings\Entity\ApplicationSettingsItem"
+            table="application_settings">
+        <id name="id" type="uuid" column="id">
+
+        </id>
+
+        <field name="applicationInstallationId" type="uuid" column="application_installation_id" nullable="false"/>
+
+        <field name="key" type="string" column="key" length="255" nullable="false"/>
+
+        <field name="value" type="text" column="value" nullable="false"/>
+
+        <field name="b24UserId" type="integer" column="b24_user_id" nullable="true"/>
+
+        <field name="b24DepartmentId" type="integer" column="b24_department_id" nullable="true"/>
+
+        <field name="changedByBitrix24UserId" type="integer" column="changed_by_b24_user_id" nullable="true"/>
+
+        <field name="isRequired" type="boolean" column="is_required" nullable="false"/>
+
+        <field name="status" enum-type="string" column="status" nullable="false"/>
+
+        <field name="createdAt" type="carbon_immutable" column="created_at_utc" precision="3" nullable="false"/>
+
+        <field name="updatedAt" type="carbon_immutable" column="updated_at_utc" precision="3" nullable="false"/>
+
+        <unique-constraints>
+            <unique-constraint columns="application_installation_id,key,b24_user_id,b24_department_id" name="unique_app_setting_scope"/>
+        </unique-constraints>
+
+        <indexes>
+            <index name="idx_application_installation_id" columns="application_installation_id"/>
+            <index name="idx_b24_user_id" columns="b24_user_id"/>
+            <index name="idx_b24_department_id" columns="b24_department_id"/>
+            <index name="idx_key" columns="key"/>
+            <index name="idx_status" columns="status"/>
+        </indexes>
+    </entity>
+</doctrine-mapping>

src/ApplicationInstallations/Infrastructure/Doctrine/ApplicationInstallationRepository.php

@@ -105,11 +105,12 @@ public function findByExternalId(string $externalId): array
     /**
      * Find application installation by application token.
      *
+     * TODO: Create issue in b24-php-sdk to add this method to ApplicationInstallationRepositoryInterface
+     *
      * @param non-empty-string $applicationToken
      *
      * @throws InvalidArgumentException
      */
-    #[\Override]
     public function findByApplicationToken(string $applicationToken): ?ApplicationInstallationInterface
     {
         if ('' === trim($applicationToken)) {
@@ -132,7 +133,9 @@ public function findByApplicationToken(string $applicationToken): ?ApplicationIn
         ;
     }
 
-    #[\Override]
+    /**
+     * TODO: Create issue in b24-php-sdk to add this method to ApplicationInstallationRepositoryInterface.
+     */
     public function findByBitrix24AccountMemberId(string $memberId): ?ApplicationInstallationInterface
     {
         if ('' === trim($memberId)) {

src/ApplicationInstallations/UseCase/Install/Handler.php

@@ -44,7 +44,8 @@
         ]);
 
         /** @var null|AggregateRootEventsEmitterInterface|ApplicationInstallationInterface $activeInstallation */
+        /** @phpstan-ignore-next-line Method exists in implementation but not in SDK interface - TODO: see ApplicationInstallationRepository */
         $activeInstallation = $this->applicationInstallationRepository->findByBitrix24AccountMemberId($command->memberId);
 
         if (null !== $activeInstallation) {
             $entitiesToFlush = [];

src/ApplicationInstallations/UseCase/OnAppInstall/Handler.php

@@ -39,7 +39,8 @@
         ]);
 
         /** @var null|AggregateRootEventsEmitterInterface|ApplicationInstallationInterface $applicationInstallation */
+        /** @phpstan-ignore-next-line Method exists in implementation but not in SDK interface - TODO: see ApplicationInstallationRepository */
         $applicationInstallation = $this->applicationInstallationRepository->findByBitrix24AccountMemberId($command->memberId);
 
         $applicationStatus = new ApplicationStatus($command->applicationStatus);
 
@@ -67,18 +68,23 @@
             $memberId,
             Bitrix24AccountStatus::active,
             null,
-            null,
-            true
+            null
+        );
+
+        // Filter for master accounts only
+        $masterAccounts = array_filter(
+            $bitrix24Accounts,
+            fn (Bitrix24AccountInterface $bitrix24Account): bool => $bitrix24Account->isMasterAccount()
         );
 
-        if ([] === $bitrix24Accounts) {
+        if ([] === $masterAccounts) {
             throw new Bitrix24AccountNotFoundException('Bitrix24 account not found for member ID '.$memberId);
         }
 
-        if (1 !== count($bitrix24Accounts)) {
+        if (1 !== count($masterAccounts)) {
             throw new MultipleBitrix24AccountsFoundException('Multiple Bitrix24 accounts found for member ID '.$memberId);
         }
 
-        return reset($bitrix24Accounts);
+        return reset($masterAccounts);
     }
 }

src/ApplicationInstallations/UseCase/Uninstall/Handler.php

@@ -43,7 +43,8 @@
         ]);
 
         /** @var AggregateRootEventsEmitterInterface|ApplicationInstallationInterface $activeInstallation */
+        /** @phpstan-ignore-next-line Method exists in implementation but not in SDK interface - TODO: see ApplicationInstallationRepository */
         $activeInstallation = $this->applicationInstallationRepository->findByApplicationToken($command->applicationToken);
 
         if (null !== $activeInstallation) {
             $this->logger->info(