Skip to content
Snippets Groups Projects
Commit b518de19 authored by Hahn Axel (hahn)'s avatar Hahn Axel (hahn)
Browse files

Merge branch '5915-update-docs' into 'master' 

php8 only: use variable types; update phpdocs

See merge request !2
parents 065b5cd5 9f0ee42a
No related branches found
No related tags found
1 merge request!2php8 only: use variable types; update phpdocs
Expand all Show whitespace changes
Inline Side-by-side
README.md
+ 4
− 5
View file @ b518de19
......@@ -5,8 +5,7 @@ A PHP class that I use
* for authentication of user logins
* CRUD actions on ldap nodes
Institute for Medical Education; University of Bern
License: GNU GPL 3
see [docs](docs/)
\ No newline at end of file
👤 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/20_Usage.md
+ 60
− 8
View file @ b518de19
......@@ -11,12 +11,11 @@ require_once '[APPROOT]/classes/ldap.class.php';
As an example I create a hash named $aConfig and save it as "inc_config.php".
```php
$aConfig=[
return [
...
'ldap' => [
'server' => 'ldaps://ldap.example.com',
'port' => 636,
'DnLdapUser' => 'cn=Lookup,ou=Service,dc=some,dc=example.com',
'PwLdapUser' => 'PasswordOfLookupUser',
......@@ -32,16 +31,69 @@ $aConfig=[
];
```
## Example: verify login data
## initialize connection
```php
require_once('inc_config.php');
$aConfig = require_once('inc_config.php');
require_once '[APPROOT]/classes/ldap.class.php';
oLdap=new imlldap($aConfig['ldap']);
$oLdap=new imlldap($aConfig['ldap']);
```
## Methods
### 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
### 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
### User functions
* userAdd(array $aItem, string $sDn = "")
* getUserInfo(string $sUser, array $aAttributesToGet = ["*"]): bool|array
* userDelete(string $sUserDn)
* userUpdate(array $aItem)
* setPassword(string $sUser, string $sPW): bool
* verifyPassword(string $sUser, string $sPW): bool
### Debugging
Turn debugging on or off
// 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);
* 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));
```
### 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/30_Methods.md
+ 64
− 71
View file @ b518de19
......@@ -5,19 +5,28 @@
---
## `class imlldap`
IML LDAP CONNECTOR *<pre> 2022-02-22 ah added objGet(), sanitizeFilter() <br> 2022-08-18 ah mask password (showing 4 chars only) <br> 2022-08-22 ah mhash is deprecated <br> 2022-08-26 ah fix verifyPassword <br> </pre>
IML LDAP CONNECTOR
2022-02-22 ah added objGet(), sanitizeFilter() 2022-08-18 ah mask password (showing 4 chars only) 2022-08-22 ah mhash is deprecated 2022-08-26 ah fix verifyPassword 2024-07-11 ah php8 only: use variable types
---
## `private $_aLdap = array( 'server' => false, 'port' => false, 'DnLdapUser' => false, // ldap rdn oder dn 'PwLdapUser' => false, 'DnUserNode' => false, // ou=People... 'DnAppNode' => false, // cn=AppGroup... 'protoVersion' => 3, 'debugLevel' => 0, )`
## `private array $_aLdap = [ 'server' => false, 'port' => false, 'DnLdapUser' => false, // ldap rdn oder dn 'PwLdapUser' => false, 'DnUserNode' => false, // ou=People... 'DnAppNode' => false, // cn=AppGroup... 'protoVersion' => 3, 'debugLevel' => 0, ]`
---
## `private $_ldapConn = false`
## `private object|bool $_ldapConn = false`
---
## `private $_ldapBind = false`
## `private object|bool $_ldapBind = false`
ldap bind object - bind was done?
---
## `public function __construct($aConfig = array())`
## `var bool $bDebug = false`
Flag if debug mode is on
---
## `public function __construct(array $aConfig = [])`
constructor
**Parameters:**
......@@ -27,17 +36,17 @@ Var | Type | Desciption
$aConfig | array | optional set ldap connection
---
## `public function debugOn()`
## `public function debugOn(): void`
turn debug messages on; if this detail level is not enough, set a value with key debugLevel in ldap config array
---
## `public function debugOff()`
## `public function debugOff(): void`
turn debug messages off
---
## `private function _w($sText)`
## `private function _w(string $sText): bool`
write debug message if denugOn() was fired.
......@@ -52,7 +61,7 @@ $sText | string | message text
boolean
---
## `private function _wLdaperror($sText = '')`
## `private function _wLdaperror(string $sText = ''): bool`
write last ldap error as debug
......@@ -67,7 +76,7 @@ $sText | string | message text
boolean
---
## `public function setConfig($aConfig = array())`
## `public function setConfig(array $aConfig = []): void`
set a ldap config
......@@ -87,17 +96,17 @@ Var | Type | Desciption
$aConfig | array | new config items
---
## `public function close()`
## `public function close(): void`
close an existing ldap connection
---
## `public function connect()`
## `public function connect(): void`
connect to ldap
---
## `public function bind($sUser = '', $sPw = '')`
## `public function bind(string $sUser = '', string $sPw = ''): bool`
ldap bind connects with a ldap user. If the ldap connection was not opened yet the connection will be established. If a binding exists it will be unbind
......@@ -109,12 +118,12 @@ $sUser | string | optional: username (overrides _aLdap['DnLdapUser'])
$sPw | string | optional: password (overrides _aLdap['PwLdapUser'])
---
## `public function unbind()`
## `public function unbind(): void`
ldap unbind ... if a bind exists
---
## `public function DnExists($sDn)`
## `public function DnExists(string $sDn): bool`
check if a DN already exists; return is true/ false
**Parameters:**
......@@ -128,37 +137,22 @@ $sDn | string | DN to check
boolean
---
## `public function normalizeSearchentry($aRecord)`
## `public function normalizeSearchentry(array $aRecord): bool|array`
get simpler array from ldap_get_entries after ldap_search
get simpler array from ldap_get_entries after ldap_search If the given array doesn't contain the key "dn" it returns "false"
**Parameters:**
Var | Type | Desciption
-- |-- |--
$aRecord | array | singel result item
$aRecord | array | single result item
**Return:**
array
---
## `public function normalizeSearchresult($aLdapSearchresult)`
get simpler array from ldap_get_entries after ldap_search
**Parameters:**
Var | Type | Desciption
-- |-- |--
$aRecord | array | singel result item
**Return:**
array
---
## `static public function sanitizeFilter($s)`
## `static public function sanitizeFilter(string $s): string`
sanitize value to put into a search filter WARNING: the implementation is incomplete! I replaces the first N ascii chars only
......@@ -176,9 +170,9 @@ $s | string | value to sanitize
string
---
## `public function searchDn($sDn, $sSearchFilter='(objectclass=*)', $aAttributesToGet = array("*"), $bRecursive=true)`
## `public function searchDn(string $sDn, string $sSearchFilter = '(objectclass=*)', array $aAttributesToGet = ["*"], bool $bRecursive = true): bool|array`
search in ldap directory and get result as array
search in ldap directory and get result as array. It returns "false" on error: - no ldap connection - search failed
**Parameters:**
......@@ -191,10 +185,10 @@ $bRecursive | boolean | recusrive (uses ldap_search) or not (ldap_list)
**Return:**
array
boolean|array
---
## `public function searchUser($sSearchFilter='', $aAttributesToGet = array("*"), $bRecursive=true)`
## `public function searchUser(string $sSearchFilter = '', array $aAttributesToGet = ["*"], bool $bRecursive = true): bool|array`
search for entries in in ldap user node and get result as array
......@@ -208,10 +202,10 @@ $bRecursive | bool | flag: recursive search? default: true (=yes, recursive)
**Return:**
array
boolean|array
---
## `public function getUserInfo($sUser, $aAttributesToGet = array("*"))`
## `public function getUserInfo(string $sUser, array $aAttributesToGet = ["*"]): bool|array`
search user by a given username or email address. It returns false if the user does not exist or is not member of the group 'DnAppNode' (if it was set).
......@@ -219,15 +213,15 @@ search user by a given username or email address. It returns false if the user d
Var | Type | Desciption
-- |-- |--
$sUser | type | user id (uid) or email (mail) to search
$aAttributesToGet | type | i.e. array("ou", "sn", "vorname", "mail", "uid", "memberOf")
$sUser | string | user id (uid) or email (mail) to search
$aAttributesToGet | array | i.e. ["ou", "sn", "vorname", "mail", "uid", "memberOf"]
**Return:**
boolean|array
---
## `public function getUserDn($sUser)`
## `public function getUserDn(string $sUser): bool|string`
search for a DN entry with the lookup user by a given username or email address. It returns false if the user does not exist or is not member of the group 'DnAppNode' (if it was set).
......@@ -235,14 +229,14 @@ search for a DN entry with the lookup user by a given username or email address.
Var | Type | Desciption
-- |-- |--
$sUser | type | %s
$sUser | string | %s
**Return:**
string
---
## `public function setPassword($sUser, $sPW)`
## `public function setPassword(string $sUser, string $sPW): bool`
set a password for a given user; this requires a ldap bind with master/ admin account
......@@ -258,7 +252,7 @@ $sPW | string | password
boolean
---
## `private function _getNTLMHash($Input)`
## `private function _getNTLMHash(string $Input): string`
get NTLM hash from a string taken from https://secure.php.net/manual/en/ref.hash.php
......@@ -273,7 +267,7 @@ $Input | string | %s
string
---
## `public function setPasswordSamba($sUser, $sPW)`
## `public function setPasswordSamba(string $sUser, string $sPW): bool`
set a password for a given user for Samba this requires a ldap bind with master/ admin account see https://msdn.microsoft.com/en-us/library/cc223248.aspx see http://php.net/ldap-modify-batch - last examle see https://secure.php.net/manual/en/ref.hash.php
......@@ -289,23 +283,23 @@ $sPW | string | password
boolean
---
## `public function objAdd($sDn, $aItem)`
## `public function objAdd(string $sDn, array $aItem): bool`
update an ldap object this requires a ldap bind with master/ admin account
update an ldap object this requires a ldap bind with master/ admin account It returns true if the action was successful
**Parameters:**
Var | Type | Desciption
-- |-- |--
$sDn | string | dn to update
$aItem | string | array of new ldap properties
$aItem | array | array of new ldap properties
**Return:**
boolean
---
## `public function objAddAttr($sDn, $aItem)`
## `public function objAddAttr(string $sDn, array $aItem): bool`
update an ldap attribute this requires a ldap bind with master/ admin account
......@@ -314,16 +308,16 @@ update an ldap attribute this requires a ldap bind with master/ admin account
Var | Type | Desciption
-- |-- |--
$sDn | string | dn to update
$aItem | string | array of new ldap properties
$aItem | array | array of new ldap properties
**Return:**
boolean
---
## `public function objGet($sDn, $sSearchFilter='(objectclass=*)', $aAttributesToGet = array("*"))`
## `public function objGet(string $sDn, string $sSearchFilter = '(objectclass=*)', array $aAttributesToGet = ["*"]): bool|array`
read attributes from ldap node with given DN (using ldap_read)
read attributes from ldap node with given DN (using ldap_read) It returns "false" if the action was not successful - no ldap connection - DN or filter didn't match
**Parameters:**
......@@ -335,12 +329,12 @@ $aAttributesToGet | array | flat array of attributes to fetch
**Return:**
array
boolean|array
---
## `public function objUpdate($sDn, $aItem)`
## `public function objUpdate(string $sDn, array $aItem): bool`
update an ldap object with given key-value array if the attribute (key) does not exist it will be created. this requires a ldap bind with master/ admin account
update an ldap object with given key-value array if the attribute (key) does not exist it will be created. this requires a ldap bind with master/ admin account It returns "false" if the action failed
**Parameters:**
......@@ -354,9 +348,9 @@ $aItem | array | updated entry
boolean
---
## `public function objDelete($sDn)`
## `public function objDelete(string $sDn): bool`
delete an ldap object this requires a ldap bind with master/ admin account
delete an ldap object this requires a ldap bind with master/ admin account It returns "false" if the action failed
**Parameters:**
......@@ -369,25 +363,24 @@ $sDn | string | full DN to remove
boolean
---
## `public function objDeleteAttr($sDn, $aItem)`
delete attributes of an ldap object this requires a ldap bind with master/ admin account
## `public function objDeleteAttr(string $sDn, array $aItem): bool`
TODO: Test me
delete attributes of an ldap object this requires a ldap bind with master/ admin account It returns "false" if the action failed
remove attribute "userPassword" of user $sUserDn: <code>$oLdap->objDeleteAttr($sUserDn, ['userPassword'=>[]]</code>
**Parameters:**
Var | Type | Desciption
-- |-- |--
$sDn | string | DN
$aItem | string | item to remove
$aItem | array | item to remove
**Return:**
boolean
---
## `public function objectAttributeExists($sDn, $sAttribute)`
## `public function objectAttributeExists(string $sDn, string $sAttribute): bool`
check if an attribute exists in a DN
......@@ -404,7 +397,7 @@ $sAttrValue | string | value to check
boolean
---
## `public function objectAttributeAndValueExist($sDn, $sAttribute, $sAttrValue)`
## `public function objectAttributeAndValueExist(string $sDn, string $sAttribute, string $sAttrValue): bool`
check if an attribute and value exist in a DN
......@@ -421,7 +414,7 @@ $sAttrValue | string | value to check
boolean
---
## `public function objectAttributeAndValueMustExist($sDn, $sAttribute, $sAttrValue)`
## `public function objectAttributeAndValueMustExist(string $sDn, string $sAttribute, string $sAttrValue): bool`
check an attribute and value; it will be created if it does not exist this requires a ldap bind with master/ admin account
......@@ -438,7 +431,7 @@ $sAttrValue | string | value to check
boolean
---
## `public function userAdd($aItem, $sDn = false)`
## `public function userAdd(array $aItem, string $sDn = ""): bool`
create a new user item this requires a ldap bind with master/ admin account
......@@ -454,7 +447,7 @@ $sDn | string | optional DN where to create the user
boolean
---
## `public function userDelete($sUserDn)`
## `public function userDelete(string $sUserDn): bool`
delete a user this requires a ldap bind with master/ admin account
......@@ -470,7 +463,7 @@ $sPW | string | new password to set
boolean
---
## `public function userUpdate($aItem)`
## `public function userUpdate(array $aItem): bool`
update an ldap object this requires a ldap bind with master/ admin account
......@@ -485,7 +478,7 @@ $aItem | array | new user data to update
boolean
---
## `public function verifyPassword($sUser, $sPW)`
## `public function verifyPassword(string $sUser, string $sPW): bool`
verify user and password
**Parameters:**
......
docs/_index.md
+ 6
− 5
View file @ b518de19
......@@ -5,12 +5,13 @@ A PHP class that I use
* for authentication of user logins
* CRUD actions on ldap nodes
Institute for Medical Education; University of Bern
License: GNU GPL 3
👤 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/
## Requirements
* PHP 7+
* PHP 8
* Php Ldap module
* OpenLdap server to connect
* OpenLdap server / Active Directory to connect
src/ldap.class.php
+ 173
− 130
View file @ b518de19
This diff is collapsed.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment