Skip to content

Commit ba42613

Browse files
jorikfonjorikfon
committed
docs: update README and add Russian translation
Rewrite README.md with improved structure: installation guide, usage examples, API integration docs, architecture overview, and database schema. Add README.ru.md with full Russian translation.
1 parent 4ac0ed9 commit ba42613

2 files changed

Lines changed: 291 additions & 134 deletions

File tree

‎README.md‎

Lines changed: 122 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -1,181 +1,169 @@
1-
# Phone Book Module for MIKOPBX
1+
# Phone Book Module for MikoPBX
22

3-
A comprehensive phone book management module for MIKOPBX that provides caller ID management, contact storage, and integration with the PBX system's inbound and outbound calls.
3+
[![GitHub release](https://img.shields.io/github/v/release/mikopbx/ModulePhoneBook)](https://github.com/mikopbx/ModulePhoneBook/releases)
4+
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
45

5-
## Features
6-
7-
- Real-time caller ID lookup for inbound and outbound calls
8-
- Contact management with formatted number display
9-
- Excel file import support
10-
- Full-text search capabilities
11-
- Input mask toggling for phone number formatting
12-
- Asterisk AGI integration for call processing
13-
- DataTable-based web interface
6+
Contact management module for MikoPBX with real-time caller ID lookup on incoming and outgoing calls.
147

15-
## System Requirements
8+
## Features
169

17-
- MIKOPBX version 2024.1.114 or higher
18-
- Modern web browser with JavaScript enabled
10+
- **Caller ID Lookup** — automatic name display for incoming and outgoing calls
11+
- **External API Integration** — lookup caller ID from external services with caching
12+
- **Excel Import** — bulk contact import from Excel files (.xlsx, .xls)
13+
- **Web Interface** — contact management via DataTable with search and pagination
14+
- **Input Masking** — automatic phone number formatting (optional)
15+
- **Multi-language** — 26 languages supported
1916

20-
## Database Structure
17+
## Requirements
2118

22-
The module uses SQLite database located at:
23-
`/storage/usbdisk1/mikopbx/custom_modules/ModulePhoneBook/db/module.db`
19+
- MikoPBX 2024.1.114 or higher
2420

25-
### Phone Book Table (m_PhoneBook)
21+
## Installation
2622

27-
Main table storing contact information:
23+
1. Go to **Modules** → **Marketplace** in MikoPBX admin panel
24+
2. Find **Phone Book** module
25+
3. Click **Install**
2826

29-
```sql
30-
CREATE TABLE m_PhoneBook (
31-
id INTEGER PRIMARY KEY AUTO_INCREMENT,
32-
number INTEGER, -- Normalized number (1 + last 9 digits)
33-
number_rep VARCHAR(255), -- Display format (e.g., +7(906)555-43-43)
34-
call_id VARCHAR(255), -- Caller ID display name
35-
search_index TEXT, -- Combined search field for full-text search
36-
created INTEGER DEFAULT 0 -- Created timestamp or 0
37-
);
27+
Or install from GitHub release:
28+
1. Download the latest `.zip` release
29+
2. Go to **Modules** → **Module Installation**
30+
3. Upload the archive
3831

39-
-- Indexes
40-
CREATE INDEX number ON m_PhoneBook (number);
41-
CREATE INDEX CallerID ON m_PhoneBook (call_id);
42-
CREATE INDEX Created ON m_PhoneBook (created);
43-
```
32+
## Usage
4433

45-
### Settings Table (m_ModulePhoneBook)
34+
### Adding Contacts
4635

47-
Module configuration storage:
36+
1. Navigate to **Phone Book** module
37+
2. Click **Add** button
38+
3. Enter name and phone number
39+
4. Press Enter or click outside the field to save
4840

49-
```sql
50-
CREATE TABLE m_ModulePhoneBook (
51-
id INTEGER PRIMARY KEY AUTO_INCREMENT,
52-
disableInputMask INTEGER DEFAULT 0, -- Toggle for input mask functionality
53-
phoneBookApiUrl TEXT, -- Url for CallerID search
54-
phoneBookLifeTime INTEGER DEFAULT 0 -- Lifetime in seconds
55-
);
56-
```
41+
### Excel Import
5742

58-
## Phone Number Format
43+
Prepare an Excel file with two columns:
5944

60-
The module uses a specific format for storing phone numbers:
61-
1. Original number gets cleaned from any non-digit characters
62-
2. Only the last 9 digits are kept
63-
3. Digit "1" is added at the beginning
64-
4. The result is stored in the 'number' field
45+
| Name | Phone Number |
46+
|------|--------------|
47+
| John Doe | +1 555 123-4567 |
48+
| ACME Corp | 18005551234 |
6549

66-
Example:
67-
```
68-
Original: +7 (906) 555-43-43
69-
Cleaned: 79065554343
70-
Last 9: 065554343
71-
Stored: 1065554343
72-
```
50+
1. Go to **Import** tab
51+
2. Select Excel file
52+
3. Click **Import**
7353

74-
This format ensures:
75-
- Consistent number storage
76-
- Quick lookups
77-
- Independence from country codes
78-
- Compatibility with various number formats
54+
Phone numbers are normalized automatically — any format is accepted.
7955

80-
## Core Components
56+
### External API Lookup
8157

82-
### Business Logic (Lib/)
58+
Configure external API for caller ID lookup:
8359

84-
1. **PhoneBookConf.php** - Core configuration and PBX integration:
85-
- Manages Asterisk dialplan integration
86-
- Processes incoming/outgoing call routing
60+
1. Go to **Settings** tab
61+
2. Enter API URL with `%number%` placeholder:
62+
```
63+
https://api.example.com/lookup?phone=%number%
64+
```
65+
3. Set cache lifetime (seconds, 0 = no cache)
66+
4. Click **Save**
8767

88-
2. **PhoneBookAgi.php** - Asterisk AGI integration:
89-
- Real-time caller ID lookup
90-
- Handles both incoming and outgoing calls
91-
- Sets caller ID display names
68+
The API should return plain text with the caller name.
9269

93-
3. **PhoneBookImport.php** - Data import functionality:
94-
- Excel file processing
95-
- Data validation and normalization
96-
- Bulk contact import
70+
## How It Works
9771

98-
### Frontend Features
72+
### Phone Number Normalization
9973

100-
The module includes several JavaScript components:
74+
Numbers are normalized for consistent storage and fast lookups:
10175

102-
1. **DataTable Integration:**
103-
- Server-side processing
104-
- Real-time search
105-
- Automatic page length calculation
106-
- Saved state persistence
76+
```
77+
Input: +7 (906) 555-43-43
78+
Step 1: 79065554343 (digits only)
79+
Step 2: 065554343 (last 9 digits)
80+
Step 3: 1065554343 (prefix "1" added)
81+
```
10782

108-
2. **Input Masking:**
109-
- Dynamic phone number formatting
110-
- Multiple format support
111-
- Configurable masks
112-
- Toggle functionality
83+
This ensures matching works regardless of how numbers are dialed.
11384

114-
3. **Excel Import:**
115-
- File upload with progress tracking
116-
- Background processing
117-
- Error handling
118-
- Automatic data normalization
85+
### Call Flow
11986

120-
## Usage
87+
**Incoming calls:**
88+
```
89+
Asterisk → AGI script → PhoneBook lookup → Set CALLERID(name)
90+
```
12191

122-
### Managing Contacts
123-
124-
```php
125-
// Example: Adding a new contact
126-
$contact = new PhoneBook();
127-
$contact->number = '1065554343'; // Normalized format
128-
$contact->number_rep = '+7(906)555-43-43'; // Display format
129-
$contact->call_id = 'John Doe';
130-
$contact->search_index = 'johndoe1065554343+7(906)555-43-43';
131-
$contact->save();
132-
133-
// OR:
134-
$contact = new PhoneBook();
135-
$contact->setPhonebookRecord('John Doe', '+7(906)555-43-43');
136-
$contact->save();
92+
**Outgoing calls:**
93+
```
94+
Asterisk → CONNECTED_LINE_SEND_SUB → PhoneBook lookup → Set CONNECTEDLINE(name)
13795
```
13896

139-
### Excel Import Format
97+
## Architecture
14098

141-
The module accepts Excel files with the following structure:
14299
```
143-
| Name/Company | Phone Number |
144-
|-----------------|-------------------|
145-
| John Doe | +1 (555) 123-4567 |
146-
| ACME Corp | +1-777-888-9999 |
100+
ModulePhoneBook/
101+
├── agi-bin/
102+
│ └── agi_phone_book.php # Asterisk AGI entry point
103+
├── App/
104+
│ ├── Controllers/ # Phalcon MVC controllers
105+
│ ├── Forms/ # Form definitions
106+
│ └── Views/ # Volt templates
107+
├── Lib/
108+
│ ├── PhoneBookConf.php # Asterisk dialplan integration
109+
│ ├── PhoneBookAgi.php # AGI caller ID handler
110+
│ ├── PhoneBookFind.php # External API lookup
111+
│ └── PhoneBookImport.php # Excel import processor
112+
├── Models/
113+
│ ├── PhoneBook.php # Contact model
114+
│ └── Settings.php # Settings model
115+
├── public/assets/
116+
│ ├── css/ # Module styles
117+
│ └── js/ # JavaScript (ES6 source + compiled)
118+
└── Messages/ # Translations (26 languages)
147119
```
148120

149-
Phone numbers are automatically normalized during import.
121+
## Database
122+
123+
SQLite database at `/storage/usbdisk1/mikopbx/custom_modules/ModulePhoneBook/db/module.db`
124+
125+
**m_PhoneBook** — contacts:
126+
- `id` — primary key
127+
- `number` — normalized number for lookup
128+
- `number_rep` — display format
129+
- `call_id` — contact name
130+
- `search_index` — full-text search field
131+
- `created` — timestamp (for API cache expiration)
132+
133+
**m_ModulePhoneBook** — settings:
134+
- `disableInputMask` — toggle input masking
135+
- `phoneBookApiUrl` — external API URL
136+
- `phoneBookLifeTime` — cache lifetime in seconds
150137

151138
## Development
152139

153-
### Class Structure
140+
### Build JavaScript
154141

142+
```bash
143+
# Compile ES6 to ES5 with Babel
144+
babel public/assets/js/src/module-phonebook-datatable.js \
145+
--out-dir public/assets/js \
146+
--source-maps inline \
147+
--presets airbnb
155148
```
156-
ModulePhoneBook/
157-
├── Lib/
158-
│ ├── PhoneBookConf.php # PBX integration
159-
│ ├── PhoneBookAgi.php # Asterisk AGI handler
160-
│ └── PhoneBookImport.php # Import processor
161-
├── Models/
162-
│ ├── PhoneBook.php # Contact storage
163-
│ └── Settings.php # Configuration
164-
├── public/
165-
└── assets/
166-
└── js/
167-
└── src/
168-
├── module-phonebook-datatable.js
169-
├── module-phonebook-import.js
170-
└── module-phonebook-index.js
149+
150+
### PHP Syntax Check
151+
152+
```bash
153+
php -l Lib/PhoneBookConf.php
171154
```
172155

173-
## License
156+
## Links
174157

175-
GNU General Public License v3.0 - see LICENSE file for details.
158+
- [Documentation (EN)](https://docs.mikopbx.com/mikopbx/english/modules/miko/module-phone-book)
159+
- [Documentation (RU)](https://docs.mikopbx.com/mikopbx/modules/miko/phone-book)
160+
- [MikoPBX Website](https://mikopbx.com)
176161

177162
## Support
178163

179-
- Documentation: [https://docs.mikopbx.com/mikopbx/modules/miko/phone-book](https://docs.mikopbx.com/mikopbx/modules/miko/phone-book)
180164
- Email: help@miko.ru
181-
- Issues: GitHub issue tracker
165+
- Issues: [GitHub Issues](https://github.com/mikopbx/ModulePhoneBook/issues)
166+
167+
## License
168+
169+
GPL-3.0 — see [LICENSE](LICENSE) file.

0 commit comments

Comments
 (0)