Merge branch 'update-docs' into 'master'

update docs

See merge request !5

docs/20_Usage.md

@@ -14,7 +14,7 @@ As an example I create a hash named $aConfig and save it as "inc_config.php".
 return [
       ...
 
-       'ldap' => [
+       'ldap-master' => [
            'server'     => 'ldaps://ldap.example.com',
            'DnLdapUser' => 'cn=Lookup,ou=Service,dc=some,dc=example.com',
            'PwLdapUser' => 'PasswordOfLookupUser',
@@ -31,34 +31,49 @@ return [
 ];
 ```
 
-## initialize connection
+## Initialize connection
 
 ```php
 $aConfig = require_once('inc_config.php');
 require_once '[APPROOT]/classes/ldap.class.php';
 
-$oLdap=new imlldap($aConfig['ldap']);
+$oLdap=new imlldap($aConfig['ldap-maser']);
 ```
 
 ## Methods
 
+### LDAP Connection
+
+You can reconfigure the connetction data of a current ldap object:
+
+* setConfig(array $aConfig = []): void<br>Set new connection values.
+
+These methods are used internally - it is not a must to use them:
+
+* connect(): void<br>Connect to host and port
+* bind(string $sUser = '', string $sPw = ''): bool<br>with bind a user and password to access ldap data
+* unbind(): void
+
 ### Object handling
 
-* objAdd(string $sDn, array $aItem): bool
-* objGet(string $sDn, string $sSearchFilter = '(objectclass=*)', array $aAttributesToGet = ["*"]): bool|array
-* objUpdate(string $sDn, array $aItem): bool
-* objDelete(string $sDn): bool
+* DnExists(string $sDn): bool<br>Check if a DN exists
+* objAdd(string $sDn, array $aItem): bool<br>Create a new object
+* objGet(string $sDn, string $sSearchFilter = '(objectclass=*)', array $aAttributesToGet = ["*"]): bool|array<br>Get object data of a given DN
+* objUpdate(string $sDn, array $aItem): bool<br>Update values of a given object
+* objDelete(string $sDn): bool<br>Delete an object
 
 ### Attributes
 
 * objAddAttr(string $sDn, array $aItem): bool
 * objDeleteAttr(string $sDn, array $aItem): bool
-* objectAttributeExists(string $sDn, string $sAttribute): bool
-* objectAttributeAndValueExist(string $sDn, string $sAttribute, string $sAttrValue): bool - check only
-* objectAttributeAndValueMustExist(string $sDn, string $sAttribute, string $sAttrValue): bool - force the existence of attribute and value
+* objectAttributeExists(string $sDn, string $sAttribute): bool<br>Check if an attribute exists
+* objectAttributeAndValueExist(string $sDn, string $sAttribute, string $sAttrValue): bool<br>Check if an attribute exists and has a given value
+* objectAttributeAndValueMustExist(string $sDn, string $sAttribute, string $sAttrValue): bool<br>Force the existence of an attribute that must have a given value
 
 ### User functions
 
+You need to set `$aConfig['DnUserNode']` to a base DN where are the user objects.
+
 * userAdd(array $aItem, string $sDn = "")
 * getUserInfo(string $sUser, array $aAttributesToGet = ["*"]): bool|array
 * userDelete(string $sUserDn)
@@ -68,40 +83,7 @@ $oLdap=new imlldap($aConfig['ldap']);
 
 ### Debugging
 
-Turn debugging on or off
+Turn debugging on or off.
 
 * debugOff()
 * debugOn()
-
-## Examples
-
-### read user attributes
-
-Use the username or an email address to get user data. The 2nd parameter defines the attributes to fetch (`["*"]` is default).
-
-```php
-$aUser = $oLdap->getUserInfo("john@example.com", []);
-$aUser = $oLdap->getUserInfo("john@example.com", ["memberof", "uid"]);        
-
-// simplify result array:
-print_r($oLdap->normalizeSearchentry($aUser));
-```
-
-### Verify user and password for login
-
-```php
-// set values from $_FORM or $_POST data of your login form here
-// The variable $bAuthenticated is true if authentication of the user was successful.
-$bAuthenticated=oLdap->verifyPassword($sUser, $sPassword);
-```
-
-### Example: search
-
-When using special chars in search then you can sanitize the search string.
-
-```php
-$sCn = 'John Smith (john)';
-$sSearchFilter = '(cn='.$oLdap->sanitizeFilter($sCn).')';
-$aResults = $oLdap->searchDn("<DN here>", $sSearchFilter, ["*"]);
-$oLdap->close();
-```

docs/40_Configuration.md

+## Configuration
+
+When initializing a new imlldap object or use setConfig then you can apply these values:
+
+Var            | Type    | Desciption                                     | Example
+--             |--       |--                                              |--
+'server'       | string  | Server connection with "ldap(s)://host[:port]" | 'ldaps://ldap.example.com'
+'DnLdapUser'   | string  | Bind user as ldap rdn or dn                    | 'cn=Lookup,ou=ServiceAccounts,dc=org,dc=example.com'
+'PwLdapUser'   | string  | password for bind user                         |
+'DnUserNode'   | string  | for user metods: set a DN where users are      | 'ou=People,ou=ORG,dc=org,dc=example.com'
+'protoVersion' | integer | ldap protocol version                          | 3
+'debugLevel'   | integer | Value for LDAP_OPT_DEBUG_LEVEL                 | 7

docs/50_Examples.md

+## Read user attributes
+
+Use the username or an email address to get user data. The 2nd parameter defines the attributes to fetch (`["*"]` is default).
+
+```php
+$aUser = $oLdap->getUserInfo("john@example.com", []);
+$aUser = $oLdap->getUserInfo("john@example.com", ["memberof", "uid"]);        
+
+// simplify result array:
+print_r($oLdap->normalizeSearchentry($aUser));
+```
+
+### Verify user and password for login
+
+```php
+// set values from $_FORM or $_POST data of your login form here
+// The variable $bAuthenticated is true if authentication of the user was successful.
+$bAuthenticated=oLdap->verifyPassword($sUser, $sPassword);
+```
+
+## Search
+
+When using special chars in search then you can sanitize the search string.
+
+```php
+$sCn = 'John Smith (john)';
+$sSearchFilter = '(cn='.$oLdap->sanitizeFilter($sCn).')';
+$aResults = $oLdap->searchDn("<DN here>", $sSearchFilter, ["*"]);
+$oLdap->close();
+```
+
+## Debugging
+
+If you want to find connection problems then use debugOn().
+This enables the echoing of ldap actions for connect, bind and more.
+
+
+
+```php
+
+// this will set LDAP_OPT_DEBUG_LEVEL
+$aConfig['debugLevel']=7;
+
+$oLdap = new imlldap($aConfig);
+
+// enable showing debug output
+$oLdap->debugOn();
+
+// then do something ... the first action will conect and bind
+if ($oLdap->objectAttributeAndValueExist($sDn, $sAttribute, $sMemberDN)) {
+    ...
+}
+```

docs/_index.md

@@ -9,10 +9,10 @@ A PHP class that I use
 * for authentication of user logins
 * CRUD actions on ldap nodes
 
-👤 Author: Axel Hahn; Institute for Medical Education; University of Bern
-📄 Source: https://git-repo.iml.unibe.ch/iml-open-source/ldap-php-class
+👤 Author: Axel Hahn; Institute for Medical Education; University of Bern \
+📄 Source: <https://git-repo.iml.unibe.ch/iml-open-source/ldap-php-class> \
 📜 License: GNU GPL 3.0
-📗 Docs: https://os-docs.iml.unibe.ch/ldap-php-class/
+📗 Docs: <https://os-docs.iml.unibe.ch/ldap-php-class/>
 
 ## Requirements