Polish README & comments

Use full paths in .gitignore

.gitignore

@@ -1,4 +1,4 @@
-config.php
-storage/*
-!storage/.htaccess
-!storage/index.php
+/includes/config.php
+/storage/*
+!/storage/.htaccess
+!/storage/index.php

README.md

@@ -1,43 +1,44 @@
 # Microsoft contacts integration for Cisco IP Phones
-This toolbox of PHP scripts integrates Outlook.com contacts into Cisco IP Phones.
+This set of PHP scripts integrates Outlook.com contacts into Cisco IP Phones.
 
 It provides:
 
 ## Endpoints for Cisco IP Phones
 located in [`cisco/`](cisco/)
- - [`directory.php`](cisco/directory.php) - To bring up your Outlook.com contacts on the phone as soon as you press the directory button, set this as [`directoryURL` in its `SEP<MAC>.cnf.xml` config file](https://usecallmanager.nz/sepmac-cnf-xml.html#directoryURL).
- - [`authenticate.php`](cisco/authenticate.php) - To assign credentials to the phone, you can set this as [`authenticationURL` in its `SEP<MAC>.cnf.xml` config file](https://usecallmanager.nz/sepmac-cnf-xml.html#authenticationURL).  
-   (these are required when you are calling the phone's [CGI Execute](https://usecallmanager.nz/cgi-execute-xml.html) endpoint, e. g. using [`call.php`](#browser-endpoints))
+ - `directory.php` - To bring up your Outlook.com contacts on the phone as soon as you press the directory button, set this as [`directoryURL` in its `SEP<MAC>.cnf.xml` config file](https://usecallmanager.nz/sepmac-cnf-xml.html#directoryURL).  
+   (this is still in an early state as there's no search function and a maximum of 100 entries is shown)
+ - `authenticate.php` - To assign credentials to the phone, you can set this as [`authenticationURL` in its `SEP<MAC>.cnf.xml` config file](https://usecallmanager.nz/sepmac-cnf-xml.html#authenticationURL).  
+   (these are required when you are using the phone's [CGI Execute](https://usecallmanager.nz/cgi-execute-xml.html) endpoint, e.g. with [`call.php`](#browser-endpoints))
 
  ## Browser Endpoints
-  - [`call.php`](#notes-on-callphpcallphp) - Start a call from your browser on an IP Phone whose credentials you know!  
+  - [`call.php`](#notes-on-callphp) - Start a call from your browser on an IP Phone whose credentials you know!  
  (suggests telephone numbers based on your contacts as you type)
- - [`vcard.php`](vcard.php) - export all contacts as ``*.vcf`` file  
-  (will hopefully be expanded to a CardDAV endpoint that can be used to sync contacts with a telephone system such as a [FRITZ!Box router](https://service.avm.de/help/en/FRITZ-Box-Fon-WLAN-7490/019/hilfe_howto_carddav_kontakte))
-- [`index.php`](index.php) - overview of all functions
-- [`oauth-grant.php`](oauth-grant.php) - (Re-)authorize access to your contacts [via Microsoft's Graph API](https://docs.microsoft.com/en-us/graph/api/user-list-contacts)
+ - `vcard.php` - export all contacts as ``.vcf`` file  
+  (originally, a pretty naive attempt for a CardDAV endpoint that can be used to sync contacts with a telephone system such as a [FRITZ!Box router](https://service.avm.de/help/en/FRITZ-Box-Fon-WLAN-7490/019/hilfe_howto_carddav_kontakte))
+- `index.php` - overview of all functions
+- `oauth-grant.php` - (Re-)authorize access to your contacts [via Microsoft's Graph API](https://docs.microsoft.com/en-us/graph/api/user-list-contacts)
 
 # Setup
 1. Clone or download this repository and put the files on a web server that supports PHP (tested on apache2 with libapache2-mod-php and libapache2-mod-fcgid).
 2. [Register an app for OAuth 2.0 in the Microsoft Azure app registration portal](https://docs.microsoft.com/en-us/graph/auth-v2-user#1-register-your-app).
-3. There, add the URL of the [`oauth-grant.php`](oauth-grant.php) on your web server as a redirect URI. For example, `https://example.com/ipphones/oauth-grant.php`.
+3. There, add the URL of the `oauth-grant.php` on your web server as a redirect URI. For example, `https://example.com/ipphones/oauth-grant.php`.
 4. Rename or copy [`config.example.php`](includes/config.example.php) in [`includes`](includes/) to `config.php` and replace the default values with your Client ID and Client Secret.
 5. Also, add your IP Phones if you want to use [`call.php`](#browser-endpoints) or [`cisco/authenticate.php`](#endpoints-for-cisco-ip-phones).
-   - [`authenticate.php`](cisco/authenticate.php) requires `devicename`, `username` and `password` per phone,
-   - [`call.php`](#notes-on-callphpcallphp) uses `label`, `devicename` (and optionally `host`)  
+   - `authenticate.php` requires `devicename`, `username` and `password` per phone,
+   - `call.php` uses `label`, `devicename` (and optionally `host`)  
      (specify a `host` to contact the phone at `http[s]://<host>/` rather than `http[s]://<devicename>/`, e.g. if the latter doesn't work for you)
-6. Open your [`oauth-grant.php`](oauth-grant.php) in a web browser and connect your first Microsoft account.
+6. Open your `oauth-grant.php` in a web browser and connect your first Microsoft account.
 7. At the function overview that you are greeted with, note the key from the URL somewhere safe: `https://example.org/ipphones/?key=`__f53fe305ad73b3ff33cf__
-   - __Be careful: everyone with this key and the ability to reach the URL can view this Microsoft account's contacts!__
-   - If you lose the key, you can look it up in [`storage/`](#notes-on-storage-of-keys--connected-microsoft-accounts) on your web server. However, as soon as you connect another account, you'll be unable to distinguish between the two [(see the corresponding section)](#notes-on-storage-of-keys--connected-microsoft-accounts).
+   - __Be careful: anyone with this key and the ability to reach the URL can view this Microsoft account's contacts!__
+   - If you lose the key, you can look it up in [`storage/`](#notes-on-storage-of-keys--connected-microsoft-accounts) on your web server. However, as soon as you connect another account, you'll be unable to distinguish between the two.
 
 8. Add the shown [`directoryURL`](#endpoints-for-cisco-ip-phones) to your phone's `SEP<MAC>.cnf.xml`, and optionally [`authenticationURL`](#endpoints-for-cisco-ip-phones)  
-   (e. g. `https://example.org/ipphones/cisco/directory.php?key=`f53fe305ad73b3ff33cf)
+   (e.g. `https://example.org/ipphones/cisco/directory.php?key=`f53fe305ad73b3ff33cf)
 
 # Notes on [`call.php`](call.php)
 Suggestions are based on contacts of Microsoft account(s) stored under the provided key(s) (see table below).
 
-Also, [phone books of a FRITZ!Box router](https://service.avm.de/help/en/FRITZ-Box-Fon-WLAN-7490/019/hilfe_fon_telefonbuch) can be integrated using [fritzco](https://github.com/SkyhawkXava/fritzco), see [`config.php`](includes/config.example.php). However, note that fritzco's phone books won't be supported in [`directory.php`](cisco/directory.php) since that's a function fritzco itself offers.
+Also, [phone books of a FRITZ!Box router](https://service.avm.de/help/en/FRITZ-Box-Fon-WLAN-7490/019/hilfe_fon_telefonbuch) can be integrated using [fritzco](https://github.com/SkyhawkXava/fritzco), see [`config.example.php`](includes/config.example.php). However, note that fritzco's phone books won't be supported in [`directory.php`](#endpoints-for-cisco-ip-phones) since that's a function fritzco itself offers.
 
 Using query parameters in the URL, you can prefill the input fields:
 

includes/config.example.php

@@ -5,7 +5,8 @@
     // Don't forget to add redirect uri(s) at the Azure Portal
 
     // --- Cisco IP Phones ---
-    // used by authenticate.php & call.php
+    // authenticate.php requires devicename, username and password
+    // call.php uses label, devicename (and optionally host)
     const PHONES = array(
         array(
             "label" => "Example Phone 1",
@@ -29,13 +30,14 @@
         // open genkey.php in browser to get a random key
         "changeme868d490d4e99" => array(
             "bookid" => "0"
-            // 'telefonbuch' number from fritzco's directory.config.inc.php
+            // 'telefonbuch' number from fritzco's directory.config.inc.php or higher
             // (https://github.com/SkyhawkXava/fritzco/blob/master/config/directory.config.inc.php)
         ),
         "random20charhex23159" => array(
             "url" => "https://another.example.com/fritzco", // if different than FRITZCO_URL
             "bookid" => "240"
             // phone books synced with your FRITZ!Box from an external source usually start at 240
+            // I added support for these in my fork of fritzco: https://github.com/jyevon/fritzco/tree/directory
         )
     );
 

includes/util.php

@@ -67,7 +67,7 @@ function is_ssl() { // stolen from wordpress
     /**
      * Gets the path to the root directory (if this file is in it)
      * 
-     * @param boolean	$absolute	Whether the path should be absolute, otherwise relative to the querried file
+     * @param boolean	$absolute	Whether the path should be absolute, otherwise relative to the queried file
      * @param boolean	$force_ssl	Whether the protocol should be changed to ssl
      * 
      * @return string the path to the root directory
@@ -110,7 +110,7 @@ function pageroot(bool $absolute = false, bool $force_ssl = false) {
     }
 
     /**
-     * Gets the querried url
+     * Gets the queried url
      * 
      * @param bool	$force_ssl Whether the protocol should be replaced by https
      * 

storage/index.php

@@ -1,5 +1,5 @@
 <?php
-    // Prevent directory from beeing browsable on webservers disregarding .htaccess
+    // Prevent directory from being browsable on web servers disregarding .htaccess
     http_response_code(403);
     echo "Forbidden";
 ?>

vcard.php

@@ -1,8 +1,6 @@
 <?php
     require(__DIR__ . "/includes/shared.php");
 
-    // TODO carddav endpoint
-
     $key = get_key();
     if($key === false) { // request key
 ?>