Merge pull request 'reamde' (#1) from main into dev

Reviewed-on: #1

gen_pc_sidecar.php

@@ -15,7 +15,7 @@ $TARGET_EXTENSIONS = read_config_json("target_extensions");
 $LIST_FILTER_TYPE = read_config_json_string("list_filter_type");
 $EXTENSION_FILTER_LIST = read_config_json("extension_filter_list");
 $BLACKLISTED_TERMS = read_config_json("blacklisted_terms");
-$PREPEND_EXTENSIONS = read_config_json("prepend_extensions");
+$PREPEND_EXTENSIONS = read_config_json_object_list("prepend_extensions");
 
 function main(): void {
   global $TARGET_EXTENSIONS;
@@ -26,9 +26,9 @@ function main(): void {
 
   $pbdb = pull_db();
 
-  prepend_contact_list($pbdb);
   blacklist_terms($pbdb);
   filter_extensions($pbdb);
+  prepend_contact_list($pbdb);
 
 
   $mac_list = pull_mac_list();
@@ -41,8 +41,8 @@ function main(): void {
     $file = $PROVISION_DIR . '/' . $mac . '-features.cfg';
 
     $xml = pull_xml_file($file);
-    $attendant = remove_attendants($xml);
-    write_attendants($attendant, $pbdb);
+    $attendants = remove_attendants($xml);
+    write_attendants($attendants, $pbdb);
     write_to_file($file, $xml);
   }
 
@@ -78,7 +78,7 @@ function pull_db(): array {
     return $pbdb;
   }
 
-function filter_extensions(&$pbdb) {
+function filter_extensions(array &$pbdb) {
   global $LIST_FILTER_TYPE;
 
   if ($LIST_FILTER_TYPE == "whitelist") {
@@ -91,7 +91,7 @@ function filter_extensions(&$pbdb) {
   }
 }
 
-function blacklist_terms(&$pbdb) {
+function blacklist_terms(array &$pbdb) {
   global $BLACKLISTED_TERMS;
   
   $pbdb = array_values(array_filter($pbdb, function ($item) use ($BLACKLISTED_TERMS) {
@@ -110,7 +110,7 @@ function blacklist_terms(&$pbdb) {
   }));
 }
 
-function whitelist_extension_filter(&$pbdb) {
+function whitelist_extension_filter(array &$pbdb) {
   global $EXTENSION_FILTER_LIST;
    
   $allowed = array_fill_keys(
@@ -128,7 +128,7 @@ function whitelist_extension_filter(&$pbdb) {
   }));
 }
 
-function blacklist_extension_filter(&$pbdb) {
+function blacklist_extension_filter(array &$pbdb) {
   global $EXTENSION_FILTER_LIST;
 
   $blocked = array_fill_keys(
@@ -146,7 +146,7 @@ function blacklist_extension_filter(&$pbdb) {
   }));
 }
 
-function prepend_contact_list(&$pbdb) {
+function prepend_contact_list(array &$pbdb) {
   global $PREPEND_EXTENSIONS;
   array_unshift($pbdb, ...$PREPEND_EXTENSIONS);
 }
@@ -170,25 +170,17 @@ function pull_mac_list(): array {
 }
 
 
-function read_config_json_file($path){
-    if (!is_file($path)) {
-        throw new RuntimeException("Config file not found: {$path}");
-    }
+function read_config_json_file(string $path): array {
+    $json = file_get_contents($path);
+    $data = json_decode($json, true);
 
-    $raw = file_get_contents($path);
-    if ($raw === false) {
-        throw new RuntimeException("Unable to read config file: {$path}");
+    if ($data === null && json_last_error() !== JSON_ERROR_NONE) {
+        throw new RuntimeException("JSON decode error: " . json_last_error_msg());
     }
-
-    $data = json_decode($raw, true);
-    if (!is_array($data)) {
-        throw new RuntimeException("Invalid JSON in config file: {$path}");
-    }
-
     return $data;
 }
 
-function read_config_json($key) {
+function read_config_json(string $key): array {
     global $CONFIG;
     $value = $CONFIG[$key] ?? [];
 
@@ -200,24 +192,41 @@ function read_config_json($key) {
         $items = [];
     }
 
+    $items = array_values(array_filter($items, fn($v) => is_scalar($v)));
+
     $items = array_map(
         fn($v) => strtolower(trim((string)$v)),
         $items
     );
 
-    $items = array_values(array_filter($items, fn($v) => $v !== ''));
-
-    return $items;
+    return array_values(array_filter($items, fn($v) => $v !== ''));
 }
 
-function read_config_json_string($key) {
+function read_config_json_string(string $key): string {
     global $CONFIG;
     $value = $CONFIG[$key] ?? '';
     return strtolower(trim((string)$value));
 }
 
+function read_config_json_object_list(string $key): array {
+    global $CONFIG;
+    $value = $CONFIG[$key] ?? [];
 
-function pull_xml_file($file): DOMDocument {
+    if (!is_array($value)) return [];
+
+    $out = [];
+    foreach ($value as $row) {
+        if (is_array($row) && isset($row['name'], $row['extension'])) {
+            $out[] = [
+                'name' => (string)$row['name'],
+                'extension' => (string)$row['extension'],
+            ];
+        }
+    }
+    return $out;
+}
+
+function pull_xml_file(string $file): DOMDocument {
   if (!file_exists($file)) {
     $file = '/tftpboot/000000000000-features.cfg';
   }
@@ -252,7 +261,7 @@ function pull_xml_file($file): DOMDocument {
   return $xml;
 }
 
-function remove_attendants($xml): DOMElement {
+function remove_attendants(DOMDocument $xml): DOMElement {
   $xpath = new DOMXPath($xml);
   $attendantNodes = $xpath->query('/polycomConfig/attendant');
   if ($attendantNodes->length === 0) {
@@ -273,7 +282,7 @@ function remove_attendants($xml): DOMElement {
   return $attendant;
 }
 
-function write_attendants($attendant, $pbdb): void {
+function write_attendants(DOMElement $attendant, array $pbdb): void {
   $index =  1;
   foreach ($pbdb as $r) {
       $label = trim((string)($r['name'] ?? ''));
@@ -288,7 +297,7 @@ function write_attendants($attendant, $pbdb): void {
   }
 }
 
-function write_to_file($file, $xml): void {
+function write_to_file(string $file, DOMDocument $xml): void {
   global $PROVISION_DIR;
   if (!is_dir($PROVISION_DIR)) {
       fwrite(STDERR, "Provisioning directory not found: $PROVISION_DIR\n");
@@ -316,7 +325,7 @@ function write_to_file($file, $xml): void {
   echo "Wrote $file \n";
 }
 
-function notify($pbdb): void {
+function notify(array $pbdb): void {
     $notified = 0;
     foreach ($pbdb as $r) {
         $ext = trim((string)$r['extension']);

readme.md

@@ -0,0 +1,59 @@
+## Gen PC Sidecar Script
+The files are stored typically inside of `/var/lib/asterisk/PC-Contact-Sync` and the scripts should be run every 6 hours by a cron job.
+
+<br>
+
+## Quickstart
+#### Config Fields
+`config.json` has several fields. The config file needs to  be next to the script in order to be read.
+
+<div style="border-left: 6px solid #FFA500; padding: 10px;">
+<strong>⚠️ Warning:</strong> Make sure the config follows proper json syntax.
+</div>
+<br>
+
+```
+target_extensions
+list_filter_type
+extension_filter_list
+blacklisted_terms
+prepend_extensions
+```
+
+1. Add the phones that need a config pushed out for to the `target_extensions` list.
+2. Add the type of filter you want to use to filter out extensions from the contact list to `list_filter_type`.
+3. Add Extensions you want either black/white listed to the `extension_filter_list`.
+4. Add words that are in contacts you want removed to `blacklisted_terms`.
+5. Add extra contacts you want added to the phones in `prepend_extensions`.
+
+<br>
+
+## Process Walkthrough
+
+#### 1. Pull Contact List
+Initially the script formats together a contact list to be pushed to the phones. This php script will pull every contact from asterisk database which contains a **name** and **extension**.
+
+#### 2. Contact List Formatting
+The script will now filter the contact list before writing to the phones. It has 3 processes to format it:
+ 
+ 1. Filter extensions by black/white list
+ 2. Remove blacklisted terms
+ 3. Prepend a set of configured contacts listed
+
+The filter list will apply either a black/white list to the `extension_filter_list`.  If it is a white list `extension_filter_list` is kept and anything not in it is removed.  If it is a blacklist anything inside of `extension_filter_list` is removed.
+
+The script will remove any contact name that has words contained inside of `blacklisted_terms`.  
+
+Finally contacts specified in `prepend_extensions` are added to the beginning of the contact list.
+
+#### 3. Write to phones
+Polycom phones read their extension list to display on the phone from a file in `/tftboot` that is served by PBXact.  The phone looks for settings including its contact list in `/tftboot/phone_mac_address-features.cfg` replacing mac_address with the actual mac of the phone without any : in the number. The default if it cant find its mac is to use the file with 0s.
+
+##### Example:
+```
+/tftboot/000000000-features.cfg
+```
+
+The script will go down the list and read the .cfg for each phone in `target_extensions` and write in the contact list that was created earlier. It wites to a config file that matches the extensions mac address.
+
+Phones might need to be told to reconfigure to pull the updated cfg.