Skip to content

Commit 423ef68

Browse files
jorikfonjorikfon
committed
Fix preg_match_all pass-by-reference error; add README and CLAUDE.md
Remove `??[]` from third argument of preg_match_all in WorkerProvisioningServerPnP::getSettings — expressions cannot be passed by reference. Properties are already initialized as empty arrays.
1 parent 0ba813b commit 423ef68

4 files changed

Lines changed: 228 additions & 2 deletions

File tree

‎CLAUDE.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Module Overview
6+
7+
ModuleAutoprovision is a MikoPBX extension module for automatic IP phone provisioning. It discovers phones on the local network via PnP multicast (224.0.1.75:5060), generates vendor-specific configuration files, and delivers them over HTTP. Supported vendors: Yealink, Snom, Fanvil, Grandstream.
8+
9+
## Build Commands
10+
11+
### JavaScript compilation (ES6 to ES5)
12+
```bash
13+
/Users/nb/PhpstormProjects/mikopbx/MikoPBXUtils/node_modules/.bin/babel \
14+
public/assets/js/src/module-autoprovision-index.js \
15+
--out-dir public/assets/js/ \
16+
--source-maps inline \
17+
--presets airbnb
18+
```
19+
20+
### PHP static analysis
21+
```bash
22+
phpstan analyse
23+
```
24+
25+
### CI/CD
26+
Pushes to `master` or `develop` trigger `.github/workflows/build.yml`, which uses the shared `mikopbx/.github-workflows` extension-publish workflow (initial version: 1.62).
27+
28+
## Architecture
29+
30+
### Namespace
31+
All PHP classes use `Modules\ModuleAutoprovision\` namespace with PSR-4 autoloading rooted at `/`.
32+
33+
### Key Layers
34+
35+
**MVC (Phalcon Framework):**
36+
- `App/Controllers/ModuleAutoprovisionController.php` — Web UI controller (settings tabs: phones, templates, URIs, phonebook, PnP config)
37+
- `App/Forms/ModuleAutoprovisionForm.php` — Form field definitions
38+
- `App/Views/index.volt` — Phalcon Volt template with Semantic UI
39+
40+
**Business Logic (`Lib/`):**
41+
- `AutoprovisionConf.php` — Extends `ConfigClass`. Registers workers, defines REST API routes, constants (`BASE_URI = /pbxcore/api/autoprovision-http`)
42+
- `Autoprovision.php` — Core config generation. Routes to vendor-specific classes, sends SIP NOTIFY for phone reboot, AGI entry point
43+
- `ConfManager.php` — Interface with single method `generateConfig($req_data, $sip_peers): string`
44+
- `AutoprovisionYealink.php`, `AutoprovisionSnom.php`, `AutoprovisionFanvil.php` — Vendor-specific implementations of `ConfManager`
45+
- `WorkerProvisioningServerPnP.php` — Background worker: multicast PnP server, MAC filtering, device discovery
46+
- `RestAPI/Controllers/GetController.php` — REST API: config delivery, phonebook, device/user CRUD
47+
48+
**Models (Phalcon ORM, `Models/`):**
49+
- `ModuleAutoprovision` — Global settings (extension pattern, PBX host, MAC white/blacklists, additional INI params)
50+
- `ModuleAutoprovisionDevice` — Phone devices (MAC, model, IP). Has many `Users` and `BLF`
51+
- `ModuleAutoprovisionUsers` — Maps users to device lines. Belongs to `Users` (core) and `Device`
52+
- `ModuleAutoprovisionBLF` — BLF button configs per device
53+
- `Templates`, `TemplatesUri`, `TemplatesUsers` — Template system for config file generation
54+
- `OtherPBX` — External PBX phonebook entries
55+
56+
All models extend `ModulesModelsBase`. Table names use `m_` prefix (e.g., `m_ModuleAutoprovisionDevice`).
57+
58+
**Setup:**
59+
- `Setup/PbxExtensionSetup.php` — DB table creation, default data, extension registration. Extends `PbxExtensionSetupBase`
60+
61+
**AGI:**
62+
- `agi-bin/ModuleAutoprovisionAGI.php` — Asterisk AGI script triggered by dial pattern (e.g., `*2*XXXX`). Resolves phone IP → MAC → device registration
63+
64+
### Frontend
65+
- Source: `public/assets/js/src/module-autoprovision-index.js` (ES6)
66+
- Compiled: `public/assets/js/module-autoprovision-index.js`
67+
- Uses Semantic UI components, dynamic table management, AJAX form submission
68+
69+
### REST API Flow
70+
Phones request configs via `GET /pbxcore/api/autoprovision-http/*` → `AutoprovisionConf::moduleRestAPICallback()` → `GetController::getConfigStatic()` → vendor-specific `ConfManager::generateConfig()`.
71+
72+
### Adding a New Phone Vendor
73+
1. Create `Lib/AutoprovisionNewVendor.php` implementing `ConfManager` interface
74+
2. Add MAC prefix detection in `GetController::getConfigStatic()`
75+
3. Add config generation routing in `Autoprovision::generateConfigPhone()`
76+
77+
## Translations
78+
30 language files in `Messages/`. Key file: `en.php`. Translation keys prefixed with `module_autoprovision_` or `mod_autoprovision_`.

‎Lib/WorkerProvisioningServerPnP.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,12 +52,12 @@ public function getSettings($debug = false):void
5252

5353
$re = '/\w{2}:?\w{2}:?\w{2}:?\w{2}:?\w{2}:?\w{2}/m';
5454

55-
preg_match_all($re, strtolower(str_replace(':', '', $data->mac_white??'')), $this->mac_white??[], PREG_SET_ORDER);
55+
preg_match_all($re, strtolower(str_replace(':', '', $data->mac_white??'')), $this->mac_white, PREG_SET_ORDER);
5656
if (count($this->mac_white) > 0) {
5757
$this->mac_white = array_merge(...$this->mac_white);
5858
}
5959

60-
preg_match_all($re, strtolower(str_replace(':', '', $data->mac_black??'')), $this->mac_black??[], PREG_SET_ORDER);
60+
preg_match_all($re, strtolower(str_replace(':', '', $data->mac_black??'')), $this->mac_black, PREG_SET_ORDER);
6161
if (count($this->mac_black) > 0) {
6262
$this->mac_black = array_merge(...$this->mac_black);
6363
}

‎README.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# ModuleAutoprovision for MikoPBX
2+
3+
<a href="README.ru.md">Документация на русском</a>
4+
5+
<img src="public/assets/img/logo.png" alt="ModuleAutoprovision" width="160">
6+
7+
Automatic IP phone provisioning module for [MikoPBX](https://github.com/mikopbx/Core). Discovers phones on the local network via Plug-and-Play (PnP) multicast, generates vendor-specific configuration files, and delivers them over HTTP.
8+
9+
## Supported Phones
10+
11+
- **Yealink** — T18P, T19D, T21D, T28P, W52P (DECT)
12+
- **Snom**
13+
- **Fanvil**
14+
- **Grandstream** (phonebook only)
15+
16+
## How It Works
17+
18+
1. The module enables a special SIP account **apv-miko-pbx** on the PBX.
19+
2. A PnP server listens on multicast address `224.0.1.75:5060` and discovers phones on the local network.
20+
3. When a phone is reset to factory settings and connects for the first time, it registers to the **apv-miko-pbx** account.
21+
4. To assign an extension, dial the provision pattern (e.g. `*2*XXX`) from the phone, where `XXX` is the desired internal number.
22+
5. The module generates a vendor-specific configuration and delivers it via the REST API at `/pbxcore/api/autoprovision-http`.
23+
24+
## Features
25+
26+
- Automatic phone discovery and registration via PnP
27+
- MAC address whitelisting and blacklisting
28+
- Template-based configuration with variables (`{SIP_USER_NAME}`, `{SIP_NUM}`, `{SIP_PASS}`)
29+
- URI pattern matching for flexible config delivery
30+
- Shared phonebook across multiple PBX instances
31+
- BLF (Busy Lamp Field) button configuration
32+
- Vendor-specific INI parameters
33+
34+
## Requirements
35+
36+
- MikoPBX **2024.1.42** or later
37+
38+
## Installation
39+
40+
Install from the MikoPBX marketplace via the admin panel:
41+
**Modules** > **Marketplace** > **Autoprovision module**
42+
43+
## Configuration
44+
45+
After installation, the module settings are available at:
46+
**Modules** > **Autoprovision module**
47+
48+
The settings page has five tabs:
49+
50+
| Tab | Description |
51+
|-----|-------------|
52+
| **Phone Settings** | Assign employees to MAC addresses with templates |
53+
| **Settings Templates** | Define configuration templates with variable substitution |
54+
| **URI Settings** | Map URI patterns to templates (supports `%` wildcard) |
55+
| **Phone Book** | Add external PBX addresses for shared phonebook |
56+
| **PnP Settings** | Extension pattern, PBX host, MAC lists, additional params |
57+
58+
## REST API
59+
60+
Base path: `/pbxcore/api/autoprovision-http`
61+
62+
| Endpoint | Description |
63+
|----------|-------------|
64+
| `/*` | Phone configuration delivery (auto-detects vendor by MAC) |
65+
| `/phonebook` | Phonebook in vendor-specific format (XML for Yealink, text for Grandstream) |
66+
67+
## Documentation
68+
69+
- [English documentation](https://docs.mikopbx.com/mikopbx/english/modules/miko/module-autoprovision)
70+
- [Документация на русском](https://docs.mikopbx.ru/mikopbx/modules/miko/module-autoprovision)
71+
72+
## License
73+
74+
GPL-3.0-or-later. See [LICENSE](LICENSE).

‎README.ru.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# ModuleAutoprovision для MikoPBX
2+
3+
<a href="README.md">English documentation</a>
4+
5+
<img src="public/assets/img/logo.png" alt="ModuleAutoprovision" width="160">
6+
7+
Модуль автоматической настройки IP-телефонов для [MikoPBX](https://github.com/mikopbx/Core). Обнаруживает телефоны в локальной сети через Plug-and-Play (PnP) мультикаст, генерирует конфигурационные файлы для каждого производителя и доставляет их по HTTP.
8+
9+
## Поддерживаемые телефоны
10+
11+
- **Yealink** — T18P, T19D, T21D, T28P, W52P (DECT)
12+
- **Snom**
13+
- **Fanvil**
14+
- **Grandstream** (только телефонная книга)
15+
16+
## Принцип работы
17+
18+
1. Модуль создаёт на АТС служебную SIP-учётную запись **apv-miko-pbx**.
19+
2. PnP-сервер слушает мультикаст-адрес `224.0.1.75:5060` и обнаруживает телефоны в локальной сети.
20+
3. При сбросе телефона к заводским настройкам он подключается к АТС и регистрируется на учётной записи **apv-miko-pbx**.
21+
4. Для привязки внутреннего номера наберите с телефона шаблон провижининга (например `*2*XXX`), где `XXX` — желаемый внутренний номер.
22+
5. Модуль генерирует конфигурацию для конкретного производителя и отдаёт её через REST API по адресу `/pbxcore/api/autoprovision-http`.
23+
24+
## Возможности
25+
26+
- Автоматическое обнаружение и регистрация телефонов через PnP
27+
- Белый и чёрный списки MAC-адресов
28+
- Шаблоны конфигурации с переменными (`{SIP_USER_NAME}`, `{SIP_NUM}`, `{SIP_PASS}`)
29+
- Маршрутизация по URI-шаблонам с подстановочным символом `%`
30+
- Общая телефонная книга между несколькими АТС
31+
- Настройка кнопок BLF (Busy Lamp Field)
32+
- Дополнительные INI-параметры для каждого производителя
33+
34+
## Требования
35+
36+
- MikoPBX версии **2024.1.42** или выше
37+
38+
## Установка
39+
40+
Установите из маркетплейса MikoPBX через панель администратора:
41+
**Модули** > **Маркетплейс** > **Модуль автоматической настройки телефонов**
42+
43+
## Настройка
44+
45+
После установки настройки модуля доступны в:
46+
**Модули** > **Модуль автоматической настройки телефонов**
47+
48+
Страница настроек содержит пять вкладок:
49+
50+
| Вкладка | Описание |
51+
|---------|----------|
52+
| **Настройки телефонов** | Привязка сотрудников к MAC-адресам с шаблонами |
53+
| **Шаблоны настроек** | Конфигурационные шаблоны с подстановкой переменных |
54+
| **Настройки URI** | Маршрутизация URI-шаблонов к конфигурациям (поддержка `%`) |
55+
| **Телефонная книга** | Адреса внешних АТС для общей телефонной книги |
56+
| **PnP настройка** | Шаблон номера, адрес сервера, списки MAC, доп. параметры |
57+
58+
## REST API
59+
60+
Базовый путь: `/pbxcore/api/autoprovision-http`
61+
62+
| Эндпоинт | Описание |
63+
|----------|----------|
64+
| `/*` | Выдача конфигурации телефона (автоопределение производителя по MAC) |
65+
| `/phonebook` | Телефонная книга в формате производителя (XML для Yealink, текст для Grandstream) |
66+
67+
## Документация
68+
69+
- [Документация на русском](https://docs.mikopbx.ru/mikopbx/modules/miko/module-autoprovision)
70+
- [English documentation](https://docs.mikopbx.com/mikopbx/english/modules/miko/module-autoprovision)
71+
72+
## Лицензия
73+
74+
GPL-3.0-or-later. См. [LICENSE](LICENSE).

0 commit comments

Comments
 (0)