Merge pull request #20 from mikopbx/develop

refactor: migrate to REST API v3 for employee management

Author: jorikfon

App/Controllers/ModuleLdapSyncController.php

@@ -69,7 +69,7 @@ public function indexAction(): void
      *
      * @return void
      */
-    public function modifyAction(string $id = null): void
+    public function modifyAction(?string $id = null): void
     {
         $this->view->showModuleStatusToggle = false;
         $footerCollection = $this->assets->collection(AssetProvider::FOOTER_JS);

CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ModuleLdapSync is a MikoPBX extension module that synchronizes employees from LDAP/Active Directory servers into MikoPBX. It creates user accounts automatically and supports bidirectional sync - extension details can be synchronized back to the domain.
+
+## Build & Development Commands
+
+### PHP Syntax Check
+```bash
+php -l <file.php>
+```
+
+### JavaScript Compilation
+```bash
+/Users/nb/PhpstormProjects/mikopbx/MikoPBXUtils/node_modules/.bin/babel "public/assets/js/src/<file>.js" --out-dir "public/assets/js/" --source-maps inline --presets airbnb
+```
+
+### Code Quality
+```bash
+phpstan analyse <file.php>
+```
+
+## Architecture
+
+### Directory Structure
+- `App/` - Phalcon MVC components (Controllers, Forms)
+- `Lib/` - Core business logic (LDAP sync, connectors, workers)
+- `Models/` - Database models (Phalcon ORM)
+- `Messages/` - i18n translation files
+- `public/assets/` - Frontend assets (JS source in `js/src/`, compiled in `js/`)
+- `Setup/` - Module installation/uninstallation logic
+
+### Key Components
+
+**LdapSyncMain** (`Lib/LdapSyncMain.php`)
+- Main orchestrator for LDAP synchronization
+- `syncAllUsers()` - syncs all enabled LDAP servers
+- `syncUsersPerServer()` - syncs single server, returns AnswerStructure
+- `updateUserData()` - bidirectional sync logic using hash comparison
+- Uses MikoPBX REST API for user CRUD operations
+
+**LdapSyncConnector** (`Lib/LdapSyncConnector.php`)
+- LDAP connection management using `ldaprecord/ldaprecord` library
+- Supports ActiveDirectory, OpenLDAP, DirectoryServer, FreeIPA
+- Handles user queries with pagination via Redis cache
+- `getUsersList()` - fetches users from LDAP with attribute mapping
+- `updateDomainUser()` - writes changes back to LDAP
+
+**WorkerLdapSync** (`Lib/Workers/WorkerLdapSync.php`)
+- Background worker for periodic sync (hourly by default)
+- Uses Redis cache for sync frequency management
+- Increases frequency to 5 minutes when changes detected
+
+**Constants** (`Lib/Constants.php`)
+- User attribute mappings (name, mobile, extension, email, avatar, password)
+- Sync result states (UPDATED, SKIPPED, CONFLICT)
+- Conflict tracking constants
+
+### Data Flow
+1. Worker triggers `LdapSyncMain::syncAllUsers()`
+2. For each enabled server, `LdapSyncConnector` fetches LDAP users
+3. Hash comparison determines which side changed (domain vs PBX)
+4. Updates applied via MikoPBX REST API or `LdapSyncConnector::updateDomainUser()`
+5. Conflicts recorded in `Conflicts` model
+
+### Models
+- `LdapServers` - LDAP server configurations (host, port, credentials, attribute mappings)
+- `ADUsers` - Tracks synced users with domain/local hashes for change detection
+- `Conflicts` - Records sync conflicts for manual resolution
+
+### REST API Endpoints (via ModuleLdapSyncController + ApiController)
+- `get-available-ldap-users` - Test LDAP connection and fetch users
+- `sync-ldap-users` - Trigger manual sync
+- `get-server-conflicts` / `delete-server-conflict(s)` - Conflict management
+- `get-disabled-ldap-users` - List disabled domain users in PBX
+
+### Frontend
+- `module-ldap-sync-modify.js` - Main config form (server settings, attribute mapping, manual sync)
+- `module-ldap-sync-index.js` - Server list management
+- Uses Semantic UI components and MikoPBX Form/PbxApi utilities
+
+## CI/CD
+
+GitHub Actions workflow (`.github/workflows/build.yml`) uses shared MikoPBX workflow for building and publishing to MikoPBX marketplace.

Lib/LdapSyncMain.php

@@ -24,7 +24,6 @@
 use MikoPBX\Common\Models\Users;
 use MikoPBX\Common\Providers\PBXCoreRESTClientProvider;
 use MikoPBX\Modules\Logger;
-use MikoPBX\PBXCoreREST\Lib\Extensions\DataStructure;
 use Modules\ModuleLdapSync\Lib\Workers\WorkerLdapSync;
 use Modules\ModuleLdapSync\Models\ADUsers;
 use Modules\ModuleLdapSync\Models\LdapServers;
@@ -355,13 +354,13 @@ public static function getUserOnMikoPBX(string $userId): array
     }
 
     /**
-     * Creates or updates a user using provided data.
+     * Creates or updates a user using provided data via REST API v3.
      *
      * @param array $userDataFromLdap - User data to be created or updated.
      * @param ?string $currentUserId The current user id.
      * @return AnswerStructure
      */
-    public static function createUpdateUser(array $userDataFromLdap, string $currentUserId = null): AnswerStructure
+    public static function createUpdateUser(array $userDataFromLdap, ?string $currentUserId = null): AnswerStructure
     {
         $pbxUserData = self::findUserInMikoPBX($userDataFromLdap, $currentUserId);
 
@@ -374,91 +373,134 @@ public static function createUpdateUser(array $userDataFromLdap, string $current
             return $result;
         }
 
-        // Get user data from the API
-        $di=MikoPBXVersion::getDefaultDi();
-        $restAnswer = $di->get(PBXCoreRESTClientProvider::SERVICE_NAME, [
-            '/pbxcore/api/extensions/getRecord',
-            PBXCoreRESTClientProvider::HTTP_METHOD_GET,
-            ['id' => $pbxUserData['extension_id'] ?? '']
-        ]);
+        $di = MikoPBXVersion::getDefaultDi();
+        $isNewEmployee = empty($pbxUserData['user_id']);
+
+        // Get existing employee data or defaults for new employee
+        if ($isNewEmployee) {
+            // Get default template for new employee
+            $restAnswer = $di->get(PBXCoreRESTClientProvider::SERVICE_NAME, [
+                '/pbxcore/api/v3/employees:getDefault',
+                PBXCoreRESTClientProvider::HTTP_METHOD_GET
+            ]);
+        } else {
+            // Get existing employee data by user_id
+            $restAnswer = $di->get(PBXCoreRESTClientProvider::SERVICE_NAME, [
+                '/pbxcore/api/v3/employees/' . $pbxUserData['user_id'],
+                PBXCoreRESTClientProvider::HTTP_METHOD_GET
+            ]);
+        }
+
         if (!$restAnswer->success) {
             return new AnswerStructure($restAnswer);
         }
 
-        // Create a new data structure for user data
-        $dataStructure = new DataStructure($restAnswer->data);
+        $employeeData = $restAnswer->data;
 
         // Check if provided phone number is available
-        $number = $userDataFromLdap[Constants::USER_EXTENSION_ATTR];
-        if (!empty($number) && $number !== $dataStructure->number) {
+        $number = $userDataFromLdap[Constants::USER_EXTENSION_ATTR] ?? null;
+        if (!empty($number) && $number !== ($employeeData['number'] ?? '')) {
             $restAnswer = $di->get(PBXCoreRESTClientProvider::SERVICE_NAME, [
-                '/pbxcore/api/extensions/available',
-                PBXCoreRESTClientProvider::HTTP_METHOD_GET,
-                ['number' => $number]
+                '/pbxcore/api/v3/extensions:available',
+                PBXCoreRESTClientProvider::HTTP_METHOD_POST,
+                ['number' => $number],
+                ['Content-Type' => 'application/json']
             ]);
-            if ($restAnswer->success || $restAnswer->data['userId'] == $pbxUserData['user_id']) {
-                $dataStructure->number = $number;
+            if ($restAnswer->success || ($restAnswer->data['userId'] ?? null) == $pbxUserData['user_id']) {
+                $employeeData['number'] = $number;
             }
         }
 
         // Check if provided mobile number is available
-        $mobileFromDomain = $userDataFromLdap[Constants::USER_MOBILE_ATTR];
-        if (!empty($mobileFromDomain) && $mobileFromDomain !== $dataStructure->mobile_number) {
+        $mobileFromDomain = $userDataFromLdap[Constants::USER_MOBILE_ATTR] ?? null;
+        if (!empty($mobileFromDomain) && $mobileFromDomain !== ($employeeData['mobile_number'] ?? '')) {
             $restAnswer = $di->get(PBXCoreRESTClientProvider::SERVICE_NAME, [
-                '/pbxcore/api/extensions/available',
-                PBXCoreRESTClientProvider::HTTP_METHOD_GET,
-                ['number' => $mobileFromDomain]
+                '/pbxcore/api/v3/extensions:available',
+                PBXCoreRESTClientProvider::HTTP_METHOD_POST,
+                ['number' => $mobileFromDomain],
+                ['Content-Type' => 'application/json']
             ]);
-            if ($restAnswer->success || $restAnswer->data['userId'] == $pbxUserData['user_id']) {
+            if ($restAnswer->success || ($restAnswer->data['userId'] ?? null) == $pbxUserData['user_id']) {
                 // Update mobile number and forwarding settings
-                $oldMobileNumber = $dataStructure->mobile_number;
-                $dataStructure->mobile_number = $mobileFromDomain;
-                $dataStructure->mobile_dialstring = $mobileFromDomain;
+                $oldMobileNumber = $employeeData['mobile_number'] ?? '';
+                $employeeData['mobile_number'] = $mobileFromDomain;
+                $employeeData['mobile_dialstring'] = $mobileFromDomain;
 
-                if ($oldMobileNumber === $dataStructure->fwd_forwardingonunavailable) {
-                    $dataStructure->fwd_forwardingonunavailable = $mobileFromDomain;
+                if ($oldMobileNumber === ($employeeData['fwd_forwardingonunavailable'] ?? '')) {
+                    $employeeData['fwd_forwardingonunavailable'] = $mobileFromDomain;
                 }
-                if ($oldMobileNumber === $dataStructure->fwd_forwarding) {
-                    $dataStructure->fwd_forwarding = $mobileFromDomain;
+                if ($oldMobileNumber === ($employeeData['fwd_forwarding'] ?? '')) {
+                    $employeeData['fwd_forwarding'] = $mobileFromDomain;
                 }
-                if ($oldMobileNumber === $dataStructure->fwd_forwardingonbusy) {
-                    $dataStructure->fwd_forwardingonbusy = $mobileFromDomain;
+                if ($oldMobileNumber === ($employeeData['fwd_forwardingonbusy'] ?? '')) {
+                    $employeeData['fwd_forwardingonbusy'] = $mobileFromDomain;
                 }
             }
         }
 
         // Check if provided email is available
-        $email = $userDataFromLdap[Constants::USER_EMAIL_ATTR]??null;
-        if (!empty($email) && $email !== $dataStructure->user_email) {
+        $email = $userDataFromLdap[Constants::USER_EMAIL_ATTR] ?? null;
+        if (!empty($email) && $email !== ($employeeData['user_email'] ?? '')) {
             $restAnswer = $di->get(PBXCoreRESTClientProvider::SERVICE_NAME, [
-                '/pbxcore/api/users/available',
+                '/pbxcore/api/v3/users:available',
                 PBXCoreRESTClientProvider::HTTP_METHOD_GET,
                 ['email' => $email]
             ]);
-            if ($restAnswer->success || $restAnswer->data['userId'] == $pbxUserData['user_id']) {
-                $dataStructure->user_email = $email;
+            if ($restAnswer->success || ($restAnswer->data['userId'] ?? null) == $pbxUserData['user_id']) {
+                $employeeData['user_email'] = $email;
             }
         }
 
-        // Check provided sip password
-        $sipPassword = $userDataFromLdap[Constants::USER_PASSWORD_ATTR] ?? $dataStructure->sip_secret;
-        if (!empty($sipPassword) && $sipPassword != $dataStructure->sip_secret) {
-            $dataStructure->sip_secret = $sipPassword;
+        // Update SIP password if provided
+        $sipPassword = $userDataFromLdap[Constants::USER_PASSWORD_ATTR] ?? null;
+        if (!empty($sipPassword) && $sipPassword !== ($employeeData['sip_secret'] ?? '')) {
+            $employeeData['sip_secret'] = $sipPassword;
         }
 
-        $dataStructure->user_username = $userDataFromLdap[Constants::USER_NAME_ATTR] ?? $dataStructure->user_username;
-
-        $dataStructure->user_avatar = $userDataFromLdap[Constants::USER_AVATAR_ATTR] ?? $dataStructure->user_avatar;
+        // Update username
+        if (!empty($userDataFromLdap[Constants::USER_NAME_ATTR])) {
+            $employeeData['user_username'] = $userDataFromLdap[Constants::USER_NAME_ATTR];
+        }
 
-        $dataStructure->sip_transport = trim($dataStructure->sip_transport);
+        // Update avatar
+        if (!empty($userDataFromLdap[Constants::USER_AVATAR_ATTR])) {
+            $employeeData['user_avatar'] = $userDataFromLdap[Constants::USER_AVATAR_ATTR];
+        }
 
+        // Trim transport value
+        if (isset($employeeData['sip_transport'])) {
+            $employeeData['sip_transport'] = trim($employeeData['sip_transport']);
+        }
 
-        // Save user data through the CORE API
-        $restAnswer = $di->get(PBXCoreRESTClientProvider::SERVICE_NAME, [
-            '/pbxcore/api/extensions/saveRecord',
-            PBXCoreRESTClientProvider::HTTP_METHOD_POST,
-            $dataStructure->toArray()
-        ]);
+        // Remove read-only fields before saving
+        unset(
+            $employeeData['extensions_length'],
+            $employeeData['sip_networkfilterid_represent'],
+            $employeeData['fwd_forwarding_represent'],
+            $employeeData['fwd_forwardingonbusy_represent'],
+            $employeeData['fwd_forwardingonunavailable_represent'],
+            $employeeData['represent'],
+            $employeeData['search_index']
+        );
+
+        // Save employee data through the REST API v3
+        if ($isNewEmployee) {
+            // Create new employee
+            $restAnswer = $di->get(PBXCoreRESTClientProvider::SERVICE_NAME, [
+                '/pbxcore/api/v3/employees',
+                PBXCoreRESTClientProvider::HTTP_METHOD_POST,
+                $employeeData,
+                ['Content-Type' => 'application/json']
+            ]);
+        } else {
+            // Update existing employee using PATCH (partial update)
+            $restAnswer = $di->get(PBXCoreRESTClientProvider::SERVICE_NAME, [
+                '/pbxcore/api/v3/employees/' . $pbxUserData['user_id'],
+                PBXCoreRESTClientProvider::HTTP_METHOD_PATCH,
+                $employeeData,
+                ['Content-Type' => 'application/json']
+            ]);
+        }
 
         return new AnswerStructure($restAnswer);
     }
@@ -470,7 +512,7 @@ public static function createUpdateUser(array $userDataFromLdap, string $current
      * @param ?string $currentUserId The current user id.
      * @return array The user data if found, otherwise an empty array.
      */
-    public static function findUserInMikoPBX(array $userDataFromLdap, string $currentUserId = null): array
+    public static function findUserInMikoPBX(array $userDataFromLdap, ?string $currentUserId = null): array
     {
         $parameters = [
             'models' => [

Messages/az.php

@@ -35,13 +35,13 @@
     'module_ldap_LdapBaseDN' => 'Domen kökü',
     'module_ldap_LdapPassword' => 'parol',
     'module_ldap_LdapAttributesHeader' => 'MikoPBX-də verilənlərlə uyğunluq üçün domendəki atributlar',
-    'module_ldap_UserExtensionAttribute' => 'istifadəçi uzantı nömrəsi',
-    'module_ldap_UserMobileAttribute' => 'mobil telefon',
+    'module_ldap_UserExtensionAttribute' => 'İstifadəçinin daxili nömrəsi',
+    'module_ldap_UserMobileAttribute' => 'Mobil telefon',
     'module_ldap_UserEmailAttribute' => 'E-poçt ünvanı',
-    'module_ldap_UserNameAttribute' => 'istifadəçinin adı və soyadı',
-    'module_ldap_UserAccountControl' => 'istifadəçinin kilid statusunun saxlandığı atribut',
-    'module_ldap_UserAvatarAttribute' => 'foto atribut',
-    'module_ldap_UpdateAttributes' => 'MikoPBX-də dəyişdikdə domendəki telefon nömrələrini yeniləyin (yazma icazələri tələb olunur)',
+    'module_ldap_UserNameAttribute' => 'İstifadəçinin adı və soyadı',
+    'module_ldap_UserAccountControl' => 'İstifadəçinin bloklama statusunun saxlandığı atribut',
+    'module_ldap_UserAvatarAttribute' => 'Foto ilə atribut',
+    'module_ldap_UpdateAttributes' => 'Domendəki məlumatları MikoPBX-də dəyişdirərkən yeniləyin (yazma hüquqları tələb olunur)',
     'module_ldap_LdapOrganizationalUnit' => 'Bölmə',
     'module_ldap_LdapUserFilter' => 'Əlavə istifadəçi filtri',
     'module_ldap_LdapCheckGetListHeader' => 'LDAP istifadəçilərinin siyahısını əldə etmək üçün test edin',
@@ -88,7 +88,7 @@
     'module_ldap_UserName' => 'İstifadəçi adı',
     'module_ldap_UserNumber' => 'Uzatma nömrəsi',
     'module_ldap_findExtension' => 'İstifadəçilər siyahısında tapın',
-    'module_ldap_DeletedUsersHeader' => 'LDAP/AD-də uzaqdan işləyən işçilər',
-    'module_ldap_DeletedUsersEmpty' => 'Uzaqdan işçilər yoxdur',
+    'module_ldap_DeletedUsersHeader' => 'LDAP/AD-də əlil olan işçilər',
+    'module_ldap_DeletedUsersEmpty' => 'Əlil işçi yoxdur',
     'module_ldap_UserEmail' => 'E-poçt',
 ];

Messages/cs.php

@@ -35,13 +35,13 @@
     'module_ldap_LdapBaseDN' => 'Kořen domény',
     'module_ldap_LdapPassword' => 'Heslo',
     'module_ldap_LdapAttributesHeader' => 'Atributy v doméně pro párování s daty v MikoPBX',
-    'module_ldap_UserExtensionAttribute' => 'číslo uživatelské pobočky',
-    'module_ldap_UserMobileAttribute' => 'mobilní telefon',
-    'module_ldap_UserEmailAttribute' => 'Emailová adresa',
-    'module_ldap_UserNameAttribute' => 'jméno a příjmení uživatele',
-    'module_ldap_UserAccountControl' => 'atribut, kde je uložen stav uzamčení uživatele',
-    'module_ldap_UserAvatarAttribute' => 'atribut fotografie',
-    'module_ldap_UpdateAttributes' => 'Aktualizace telefonních čísel v doméně, když se změní v MikoPBX (vyžaduje oprávnění k zápisu)',
+    'module_ldap_UserExtensionAttribute' => 'Interní číslo uživatele',
+    'module_ldap_UserMobileAttribute' => 'Mobilní telefon',
+    'module_ldap_UserEmailAttribute' => 'E-mailová adresa',
+    'module_ldap_UserNameAttribute' => 'Jméno a příjmení uživatele',
+    'module_ldap_UserAccountControl' => 'Atribut, kde je uložen stav blokování uživatele',
+    'module_ldap_UserAvatarAttribute' => 'Atribut s fotografií',
+    'module_ldap_UpdateAttributes' => 'Aktualizace dat v doméně při její změně v MikoPBX (vyžaduje se oprávnění k zápisu)',
     'module_ldap_LdapOrganizationalUnit' => 'Pododdělení',
     'module_ldap_LdapUserFilter' => 'Další uživatelský filtr',
     'module_ldap_LdapCheckGetListHeader' => 'Otestujte a získejte seznam uživatelů LDAP',
@@ -88,7 +88,7 @@
     'module_ldap_UserName' => 'Uživatelské jméno',
     'module_ldap_UserNumber' => 'Číslo pobočky',
     'module_ldap_findExtension' => 'Najděte v seznamu uživatelů',
-    'module_ldap_DeletedUsersHeader' => 'Zaměstnanci vzdálení v LDAP/AD',
-    'module_ldap_DeletedUsersEmpty' => 'Žádní vzdálení zaměstnanci',
+    'module_ldap_DeletedUsersHeader' => 'Zaměstnanci zakázaní v LDAP/AD',
+    'module_ldap_DeletedUsersEmpty' => 'Žádní zaměstnanci se zdravotním postižením',
     'module_ldap_UserEmail' => 'E-mail',
 ];