The following pages provide an overview about all functions of the API (Application Programming Interface) of the hyper Content & Digital Asset Management Server.
Please note, that you might usually only require few functions for the development of Plugins, template functions like navigation, sitemap and so on. Please read the Template Designers Guide and Programers Guide for a better insight.
The API is primarily used for the implementation of standalone applications that leverage the capabilities of the hyper Content & Digital Asset Management Server. The API is not to be confused with the OpenAPI, which is based on a SOA (Service Oriented Architecture), and is not part of the Free Edition.
For Questions & Answers please visit the Google Group.
hyperCMS API Function Reference
- Main API Functions
- Get API Functions
- Set API Functions
- Connect API Functions
- Security API Functions
- Media API Functions
- Metadata API Functions
- Link API Functions
- Plugin API Functions
- User Interface API Functions
- Template Engine API Functions
- XML API Functions
- Report API Functions
- Project API Functions
- Task API Functions
- Workflow API Functions
- Cloud Storage API Functions
- Import/Export API Functions
▲ Security API Functions
resolvepermission
Description
Returns the permission value (true or false) of a permission position of a permission segment
Syntax
resolvepermission ($permission_array, $segment, $position)
Input parameters
- $permission_array ... permission array [array]
- $segment ... permission segment name [string]
- $position ... permission value position [integer]
Output
rootpermission
Description
Deserializes the permission string and and returns the root permission array
Syntax
rootpermission ($site_name, $site_admin, $permission_str)
Input parameters
- $site_name ... publication name [string]
- $site_admin ... publication admin [boolean]
- $permission_str ... permission string from group [string]
global input parameters
- $rootpermission
$mgmt_config
Output
- global permission array/false
globalpermission
Description
Deserializes the permission string and returns the global permission array
Syntax
globalpermission ($site_name, $permission_str)
Input parameters
- $site_name ... publication name [string]
- $permission_str ... permission string from group [string]
Output
- global permission array/false
localpermission
Description
Deserializes the permission string and returns the local permission array
Syntax
localpermission ($site_name, $permission_str)
Input parameters
- $site_name ... publication name [string]
- $permission_str ... permission string from group [string]
Output
- local permission array/false
accessgeneral
Description
Checks general access to certain system folders, publications and returns true if access is granted
Syntax
accessgeneral ($site, $location, $cat)
Input parameters
- $site ... publication name [string]
- $location ... location (path to folder) [string]
- $cat ... object category [page, comp]
global input parameters
- $mgmt_config
$hiddenfolder
$siteaccess
Output
accesspermission
Description
Evaluates page and asset/component access permissions and returns the group(s). Since version 8.0.0 this function does not evaluate the access based on access links anymore since explorer_objectlist verifies the access linking.
Syntax
accesspermission ($site, $location, $cat)
Input parameters
- $site ... location (path to folder) [string]
- $location ... object category [page, comp]
- $cat
global input parameters
- $user
$pageaccess
$compaccess
$hiddenfolder
$hcms_linking
$mgmt_config
Output
- group with access permissions as array / false on error
setlocalpermission
Description
Sets local permissions of a user group for a specific publication
Syntax
setlocalpermission ($site, $group_array, $cat)
Input parameters
- $site ... publication name [string]
- $group_array ... group name [array]
- $cat ... object category [page, comp]
global input parameters
Output
- local permission array / false on error
checkpublicationpermission
Description
Checks the access to a publication based on the publication access and inheritance settings
Syntax
checkpublicationpermission ($site, $strict=true)
Input parameters
- $site ... publication name [string]
- $strict ... strictly limited to publication access without inheritance [boolean] (optional)
global input parameters
Output
- "direct" for direct access via group permission / "inherited" for access through inheritance / false
checkadminpermission
Description
Checks the super admin permission
Syntax
checkadminpermission ()
Input parameters
global input parameters
Output
checkrootpermission
Description
Checks the root permissions
Syntax
checkrootpermission ($name)
Input parameters
- $name ... permission name [string]
global input parameters
Output
checkglobalpermission
Description
Checks global permission for a publication
Syntax
checkglobalpermission ($site, $name)
Input parameters
- $site ... publication name [string]
- $name ... permission name [string]
global input parameters
Output
checklocalpermission
Description
Checks local permissions of a user group for a specific publication
Syntax
checklocalpermission ($site, $group, $name)
Input parameters
- $site ... publication name [string]
- $group ... user group name [string]
- $name ... permission name [string]
global input parameters
Output
checkpluginpermission
Description
Checks the plugin access permissions of a user for a specific plugin
Syntax
checkpluginpermission ($site, $pluginname)
Input parameters
- $site ... publication name [string]
- $pluginname ... plugin name [string]
global input parameters
- $mgmt_config
$mgmt_plugin
$pluginaccess
Output
checklanguage
Syntax
checklanguage ($language_array, $language_value)
Input parameters
- $language_array ... language array with all valid values [array]
- $language_value ... language value of attribute in template tag [string}
Output
- true if language array holds the given language value / false if not found
checkgroupaccess
Description
Verifies if a user has access to the tags content based on the group membership.
Syntax
checkgroupaccess ($groupaccess, $usergroup_array)
Input parameters
- $groupaccess ... group access from template group-tag attribute [string]
- $usergroup_array ... user group membership names [array]
Output
- true if the current user group has access / false if not
userlogin
Description
Login of a user by his credentials (user and password, or user hash code).
The function reads and provides all permissions of the user and authenticated against other user directories, e.g. LDAP/AD if defined in the main configuration, see $mgmt_config['authconnect'].
The function provides a result array but does not register the user in the session.
Syntax
userlogin ($user="", $passwd="", $hash="", $objref="", $objcode="", $ignore_password=false, $locking=true, $portal="")
Input parameters
- $user ... user name [string] (optional if hash code is used for logon)
- $passwd ... password [string] (optional if hash code is used for logon)
- $hash ... hash code of user [string] (optional)
- $objref ... object reference for hcms linking (object ID) [string] (optional)
- $objcode ... object code for hcms linking (crypted object ID) [string] (optional)
- $ignore_password ... ignore passwordcheck needed for WebDAV or access link [boolean] (optional)
- $locking ... lock IP after 10 failed attempts to login [boolean] (optional)
- $portal ... portal name in the form of publication.portal or publication/portal [string] (optional)
global input parameters
- ralize the permission string and define root
global and local permissions if (isset ($permission_str[$site_name][$group_name])) { $result['rootpermission'] = rootpermission ($site_name
$mgmt_config[$site_name]['site_admin']
$permission_str)
Output
setportalpermissions
Description
Sets the permissions for a portal user by reducing the standard permissions.
Syntax
setportalpermissions ($login_result)
Input parameters
- $login_result ... result from function userlogin [array]
global input parameters
Output
registerinstance
Description
Registers the instance in the users session.
Syntax
registerinstance ($instance, $load_config=true)
Input parameters
- $instance ... instance name [string]
- $load_config ... load main config of instance [boolean] (optional)
global input parameters
Output
registerservice
Description
Registers the service of a standard user and returns the service hash.
Syntax
registerservice ($servicename, $user)
Input parameters
- $servicename ... service name [string]
- $user ... user name [string]
global input parameters
Output
- service hash as string / false on error
registerserviceuser
Description
Registers a system service user "sys:service-name:16-digit-servicehash" in the session.
Syntax
registerserviceuser ($servicename, $servicehash)
Input parameters
- $servicename ... service name [string]
- $servicehash ... 16 digits service hash [string]
global input parameters
Output
- system service user name / false
registeruser
Description
Registers all user related paramaters in the session. Access links can be provided with the login result or alternatively as the seperate accesslink parameter.
Syntax
registeruser ($instance="", $login_result=array(), $accesslink=false, $hcms_objformats=false, $is_mobile=0, $is_iphone=0, $html5support=1)
Input parameters
- $instance ... instance name [string] (optional)
- $login_result ... result array of function userlogin [array]
- $accesslink ... access link [array] (optional)
- $hcms_objformats ... download formats of access link provided by function rdbms_getaccessinfo [array] (optional)
- $is_mobile ... mobile browser result of client [0, 1] (optional)
- $is_iphone ... is iOS browser result of client [0, 1] (optional)
- $html5support ... HTML5 file support result of client [0, 1] (optional)
global input parameters
- $mgmt_config
$hcms_lang
$lang
Output
- result array / false on error
registerassetbrowser
Syntax
registerassetbrowser ($userhash, $objecthash="")
Input parameters
- $userhash ... user hash [string]
- $objecthash ... object hash [string] (optional)
global input parameters
Output
createchecksum
Description
Creates the checksum of the user permissions.
Syntax
createchecksum ($permissions="")
Input parameters
- $permissions ... array or empty [array]
Output
writesession
Description
Writes hyperCMS specific session data of a user.
Syntax
writesession ($user, $passwd, $checksum, $siteaccess=array())
Input parameters
- $user ... user name [string]
- $passwd ... password [string]
- $checksum ... checksum [string]
- $siteaccess ... publicaion access [array]
global input parameters
Output
writesessiondata
Description
Serializes and writes all session data of a user.
Syntax
writesessiondata ()
Input parameters
global input parameters
Output
createsession
Description
Creates a session for the user. This function accesses session variables directly.
Syntax
createsession ($name="hyperCMS", $session_id="")
Input parameters
- $name ... session name [string] (optional)
- $session_id ... session ID [string] (optional)
global input parameters
Output
killsession
Description
Destroys the session data of a user.
Syntax
killsession ($user="", $destroy_php=true, $remove=false)
Input parameters
- $user ... user name for hyperCMS session [string] (optional)
- $destroy_php ... destroy php session [boolean] (optional)
- $remove ... remove session file of the user [boolean] (optional)
global input parameters
Output
suspendsession
Description
Suspends the session by writing the session data and closing it.
Syntax
suspendsession ($name="", $user="")
Input parameters
- $name ... process name [string] (optional)
- $user ... user name [string] (optional)
global input parameters
Output
- session ID / false on error
revokesession
Description
Revokes the session.
Syntax
revokesession ($name="", $user="", $session_id="")
Input parameters
- $name ... process name [string] (optional)
- $user ... user name [string] (optional)
- $session_id ... session ID [string] (optional)
global input parameters
Output
- session ID / false on error
is_suspendedsession
Description
Verifies if a process file of a suspended session exists.
Syntax
is_suspendedsession ($name="", $user="")
Input parameters
- $name ... process name [string] (optional)
- $user ... user name [string] (optional)
global input parameters
Output
checkdiskkey
Description
Checks the disc key of the installation.
Syntax
checkdiskkey ()
Input parameters
global input parameters
Output
checkpassword
Description
This function checks the strength of a password and return the error messages or true.
Syntax
checkpassword ($password, $user="")
Input parameters
- $password ... password [string]
- $user ... user name [string] (optional for password history)
global input parameters
Output
- true if passed / error message as string
loguserip
Syntax
loguserip ($client_ip, $user="sys")
Input parameters
- $client_ip ... client IP address [string]
- $user ... user logon name [string] (optional)
global input parameters
Output
checkuserip
Syntax
checkuserip ($client_ip, $user="", $timeout=0)
Input parameters
- $client_ip ... client IP address [string]
- $user ... user logon name [string] (optional)
- $timeout ... timeout in minutes [integer] (optional)
global input parameters
Output
- true if IP is not locked / false if IP is locked or on error
checkuserrequests
Description
Provides security for Cross-Site Request Forgery.
Syntax
checkuserrequests ($user="sys")
Input parameters
- $user ... user name [string] (optional)
global input parameters
Output
- true / false if a certain amount of reguests per minute is exceeded
recreateusersession
Description
Recreates the users session data in case it is missing (due to issues with Android Chrome and the Mobile Edition).
Recreates the session data only if the session ID is still available.
Syntax
recreateusersession ()
Input parameters
global input parameters
Output
- true / false requires config.inc.php
checkusersession
Description
Checks if the session data of a user is valid. This function does access session variables directly.
If a system service is used the service identifier in the form of "sys:service-name:service-hash" can be provided.
Syntax
checkusersession ($user="sys", $CSRF_detection=true)
Input parameters
- $user ... user name or service identifier [string] (optional)
- $CSRF_detection ... include CSRF detection [boolean]
global input parameters
Output
- true / html-output followed by termination requires config.inc.php
allowuserip
Description
Verifies if the client IP is in the range of valid IPs and logs IP addresses with no access.
Syntax
allowuserip ($site)
Input parameters
- $site ... publication name [string]
global input parameters
Output
- true / false requires config.inc.php
valid_objectname
Description
Checks if an object name includes forbidden characters in order to prevent directory browsing.
Syntax
valid_objectname ($variable)
Input parameters
- $variable ... variable [string or array]
Output
valid_locationname
Description
Checks if an location is valid and does not include forbidden characters in order to prevent directory browsing.
Syntax
valid_locationname ($variable)
Input parameters
- $variable ... variable [string or array]
global input parameters
Output
valid_publicationname
Description
Checks if a publication name includes forbidden characters in order to prevent directory browsing.
Optionally verifies if the publication name is included in the siteaccess variable.
Syntax
valid_publicationname ($variable)
Input parameters
- $variable ... variable [string or array]
global input parameters
Output
html_encode
Description
This function encodes certain characters (&, <, >, ", ') into their HTML character entity equivalents to protect against XSS.
Converts a string into the html equivalents (also used for XSS protection).
Supports multibyte character sets like UTF-8 as well based on the ASCII value of the character.
Syntax
html_encode ($expression, $encoding="", $js_protection=false)
Input parameters
- $expression ... variable [string or array]
- $encoding ... conversion of all special characters based on given character set or to ASCII [string] (optional)
- $js_protection ... remove characters to avoid JS injection [boolean] (optional)
Output
- html encoded value as array or string / false on error
html_decode
Description
This function decodes all characters which have been converted by html_encode.
Syntax
html_decode ($expression, $encoding="")
Input parameters
- $expression ... epxression [string or array]
- $encoding ... conversion of all special characters based on character set [string] (optional)
Output
- html decoded value as array or string / false on error
scriptcode_encode
Description
This function escapes all script tags.
This function must be used to clean all user input in the CMS by removing all server side scripts tags.
Syntax
scriptcode_encode ($content)
Input parameters
- $content ... content [string]
global input parameters
Output
- escaped content as string / false on error
scriptcode_extract
Description
This function extracts the script code of a given content.
Syntax
scriptcode_extract ($content, $identifier_start="<?", $identifier_end="?>")
Input parameters
- $content ... content [string]
- $identifier_start ... identifier of script begin [string]
- $identifier_end ... identifier of script end [string]
Output
- script code as array / false on error or if noting was found
scriptcode_clean_functions
Description
This function removes all dangerous PHP functions.
Syntax
scriptcode_clean_functions ($content, $type=4, $application="PHP")
Input parameters
- $content ... content [string]
- $type ... cleaning level type: no cleaning = 0; basic set of disabled functions = 1; 1 + file access functions = 2; 2 + include functions = 3; 3 + hyperCMS API file functions = 4; No server side script allowed = 5 [0, 1, 2, 3, 4, 5] (optional)
- $application ... application [PHP, ASP, JSP] (optional)
global input parameters
Output
- result array / false on error
sql_clean_functions
Description
This function checks SQL statements for write operations.
Syntax
sql_clean_functions ($content)
Input parameters
- $content ... SQL statement [string]
global input parameters
Output
- result array / false on error
url_encode
Description
This function encodes all characters.
Syntax
url_encode ($variable)
Input parameters
- $variable ... variable [string or array]
global input parameters
Output
- urlencoded value as array or string / false on error
url_decode
Description
This function decodes all characters which have been converted by url_encode or urlencode (PHP).
Syntax
url_decode ($variable)
Input parameters
- $variable ... variable [string or array]
global input parameters
Output
- urldecoded value as array or string / false on error
shellcmd_encode
Description
This function encodes/escapes characters to secure the shell comand.
Syntax
shellcmd_encode ($variable, $type="")
Input parameters
- $variable ... variable [string or array]
- $type ... type [%, strict] (optional)
Output
- encoded value as array or string / false on error
hcms_crypt
Description
Unidrectional encryption using sha1 and urlencode. Used to create tokens for simple view links in the system.
The tokens can be verified by calculating the hash of the media file name and comparing the hash values.
Don't use this function to secure any string or for password hashing.
Syntax
hcms_crypt ($string, $start=0, $length=0)
Input parameters
- $string ... string to encode [string]
- $start ... start position [integer]
- $length ... length for string extraction [integer]
global input parameters
Output
- encoded string / false on error
hcms_encrypt
Description
Encryption of a string. Only strong encryption is binary-safe.
Syntax
hcms_encrypt ($string, $key="", $crypt_level="", $encoding="url")
Input parameters
- $string ... string to encode [string]
- $key ... key of length 16 or 24 or 32 [string] (optional)
- $crypt_level ... crypt strength level [weak, standard, strong] (optional)
- $encoding ... encoding [base64, url, none] (optional)
global input parameters
Output
- encoded string / false on error
hcms_decrypt
Description
Decryption of a string. Only strong encryption is binary-safe.
Syntax
hcms_decrypt ($string, $key="", $crypt_level="", $encoding="url")
Input parameters
- $string ... hash-string to decode [string]
- $key ... key of length 16 or 24 or 32 [string] (optional)
- $crypt_level ... crypt strength level [weak, standard, strong] (optional)
- $encoding ... encoding [base64, url, none] (optional)
global input parameters
Output
- decoded string / false on error
createtimetoken
Syntax
createtimetoken ($lifetime=0, $secret=4)
Input parameters
- $lifetime ... token lifetime in seconds [integer] (optional)
- $secret ... secret value [integer] (optional)
global input parameters
Output
checktimetoken
Syntax
checktimetoken ($token, $secret=4)
Input parameters
- $token ... token [string]
- $secret ... secret value [integer] (optional)
global input parameters
Output
createtoken
Syntax
createtoken ($user="sys", $lifetime=0, $secret=4)
Input parameters
- $user ... user name [string] (optional)
- $lifetime ... token lifetime in seconds [integer] (optional)
- $secret ... secret value [integer] (optional)
global input parameters
Output
checktoken
Syntax
checktoken ($token, $user="sys", $secret=4)
Input parameters
- $token ... token [string]
- $user ... user name [string] (optional)
- $secret ... secret value [integer] (optional)
global input parameters
Output
createuniquetoken
Syntax
createuniquetoken ($length=16)
Input parameters
- $length ... token length [integer] (optional)
global input parameters
Output
createpassword
Syntax
createpassword ($length=10)
Input parameters
- $length ... password length [integer] (optional)
global input parameters
Output
- password as string / false
rand_secure
Syntax
rand_secure ($min=1000, $max=999999999999)
Input parameters
- $min ... min and max value [integer] (optional)
- $max
Output
- secure random number / false