Mikopbx Module

Target Platform

PHP: 8.3
min_pbx_version: 2025.1.1
Framework: Phalcon 5.8
NO legacy compatibility (no MikoPBXVersion.php)

Core Workflow

Mode 1: Create New Module

Phase 1 — Discovery Dialog

Parse user's natural language description and determine:

1. Module purpose — what problem it solves
2. Module name — suggest ModuleXxxYyy following MikoPBX conventions
3. Target location — ask user:
   • Extensions/ — for production modules
   • Extensions/EXAMPLES/{Category}/ — for example/learning modules
4. Required recipes — analyze description and propose:

5. Confirm plan — present proposed structure and get user approval before generating

Ask many questions! It's better to clarify intent than to guess wrong. Examples:

• "Модуль будет иметь свою страницу настроек в админке?"
• "Нужен ли REST API для внешних интеграций?"
• "Модуль должен реагировать на события звонков?"
• "Есть ли данные, которые нужно хранить в базе?"

Phase 2 — Generation

Generate files using reference templates in templates/ directory. For each recipe, create the corresponding files.

File generation order:

1. module.json — module metadata
2. Setup/PbxExtensionSetup.php — installer
3. Models/*.php — database models
4. Lib/{Name}Conf.php — configuration class with hooks
5. Lib/{Name}Main.php — business logic (if needed)
6. App/Controllers/ — web controllers (if ui recipe)
7. App/Forms/ — Phalcon forms (if ui recipe)
8. App/Views/ — Volt templates (if ui recipe)
9. App/Providers/ — Asset and Menu providers (if ui recipe)
10. public/assets/js/src/ — ES6+ JavaScript (if ui recipe)
11. public/assets/css/ — CSS styles (if ui recipe)
12. Lib/RestAPI/ — REST API controllers and actions (if rest-api recipe)
13. bin/ — Worker scripts (if workers recipe)
14. agi-bin/ — AGI scripts (if agi recipe)
15. Messages/ — Translation files (call /translations skill)

Code references: When generating code, study existing EXAMPLES for patterns:

• REST API v3: Extensions/EXAMPLES/REST-API/ModuleExampleRestAPIv3/
• Web UI: Extensions/EXAMPLES/WebInterface/ModuleExampleForm/
• AMI Workers: Extensions/EXAMPLES/AMI/ModuleExampleAmi/
• REST API v1/v2: Extensions/EXAMPLES/REST-API/ModuleExampleRestAPIv{1,2}/

Read the actual source code from these examples before generating — they are the canonical reference.

Phase 3 — Post-Generation Checks

After generating all files, run:

# 1. PHP syntax check on all generated PHP files
find {module_dir} -name "*.php" -exec php -l {} \;

# 2. Babel transpilation for JS files (if ui recipe)
# Use /babel-compiler skill

# 3. module.json validation
php -r "json_decode(file_get_contents('{module_dir}/module.json'), true) ?: exit(1);"

Report results and suggest fixes for any issues found.

Phase 4 — Report

Module: ModuleBlackList
Location: Extensions/ModuleBlackList/
Recipes: base, ui, rest-api, dialplan, agi

Files created:
  Setup/PbxExtensionSetup.php
  Lib/BlackListConf.php
  Lib/BlackListMain.php
  Models/BlackListNumbers.php
  App/Controllers/ModuleBlackListController.php
  App/Forms/ModuleBlackListForm.php
  App/Views/ModuleBlackList/index.volt
  App/Providers/AssetProvider.php
  App/Providers/MenuProvider.php
  public/assets/js/src/module-black-list.js
  public/assets/css/module-black-list.css
  Lib/RestAPI/Numbers/Controller.php
  Lib/RestAPI/Numbers/Processor.php
  Lib/RestAPI/Numbers/DataStructure.php
  Lib/RestAPI/Numbers/Actions/GetListAction.php
  ...
  agi-bin/check-blacklist.php
  Messages/ru.php (+ 28 languages via /translations)
  module.json

Checks:
  PHP syntax: PASS (18/18 files)
  Babel: PASS
  module.json: VALID

Next steps:
  1. Review generated code
  2. Install module in MikoPBX
  3. Test functionality
  4. Customize business logic

Mode 2: Augment Existing Module

Phase 1 — Analysis

1. Read module directory structure
2. Identify what's already implemented:
   • Which recipes are present
   • Which hooks are used in Conf.php
   • Models, controllers, workers count
3. Check for anti-patterns (see Anti-Patterns section)
4. Present findings to user

Phase 2 — Plan Changes

Based on user request, determine:

• New files to create
• Existing files to modify (especially Conf.php)
• Dependencies between changes

Phase 3 — Implementation

Apply changes following the same patterns as Mode 1. When modifying Conf.php, add new hook methods without breaking existing ones.

Phase 4 — Optimization (if requested)

Run anti-pattern checker and suggest improvements.

Mode 3: Optimize Module

Analyze module code against best practices:

1. Read all module files
2. Check anti-patterns (see reference/anti-patterns.md)
3. Report findings with severity and fix suggestions
4. Apply fixes if user approves

Code Standards

PHP 8.3 Features to Use

// Typed properties (for non-model classes: Conf, Main, Worker, etc.)
public string $name = '';
public readonly string $moduleUniqueId;

// Constructor promotion
public function __construct(
    private readonly string $moduleUniqueId,
) {}

// Match expressions
$result = match($action) {
    'check' => $this->check(),
    'reload' => $this->reload(),
    default => throw new \InvalidArgumentException("Unknown action: $action"),
};

// Named arguments
PBX::dialplanReload(timeout: 30);

// Enums where appropriate
enum CallDirection: string {
    case Incoming = 'incoming';
    case Outgoing = 'outgoing';
}

Phalcon ORM Model Properties (IMPORTANT)

Model column properties follow Phalcon/SQLite conventions — do NOT apply PHP 8.3 typed properties rules here:

// Primary key — ALWAYS untyped
public $id;

// String columns — nullable with string default
public ?string $name = '';

// Integer columns stored as string in SQLite
public ?string $enabled = '0';

// Integer foreign keys — nullable int
public ?int $userid = null;

This pattern matches core models in src/Common/Models/. See Extensions.php, Sip.php, CallQueues.php for reference.

Import Rules

// CORRECT
use Phalcon\Di\Di;

// WRONG - will cause errors
use Phalcon\Di;

Naming Conventions

File Headers

All PHP files must start with:

<?php

declare(strict_types=1);

No closing ?> tag.

Recipe Details

See recipes.md for detailed recipe specifications.

Hook Reference

See hook-reference.md for complete list of 60+ hooks with signatures and examples.

Anti-Patterns

See anti-patterns.md for common mistakes to detect and fix.

Templates

See templates/ directory for code generation templates.

Translation Integration

After generating PHP code, invoke the /translations skill to create Messages files for all 29 languages.

Workflow:

1. Collect all translation keys used in generated code (controllers, views, forms)
2. Create Russian translations first (Messages/ru.php)
3. Call /translations skill to translate to remaining 28 languages

Important Directories

• Production modules: /Users/nb/PhpstormProjects/mikopbx/Extensions/
• Example modules: /Users/nb/PhpstormProjects/mikopbx/Extensions/EXAMPLES/
• Core module system: /Users/nb/PhpstormProjects/mikopbx/Core/src/Modules/
• Core configs: /Users/nb/PhpstormProjects/mikopbx/Core/src/Core/Asterisk/Configs/

Task Activation Patterns

This skill activates when you say:

• "Создай модуль ..." / "Create module ..."
• "Сгенерируй модуль ..." / "Generate module ..."
• "Добавь в модуль ..." / "Add to module ..."
• "Оптимизируй модуль ..." / "Optimize module ..."
• "Как сделать модуль ..." / "How to make module ..."
• "Доработай модуль ..." / "Improve module ..."
• "/mikopbx-module ..."