User Function Guide functions.custom.php in Cotonti

Cotonti Custom Functions Guide

This guide provides a detailed description of four functions designed to identify the owner or author of content. Each function is accompanied by code examples and usage instructions.

1. Activating the Functions File

Before using the functions, you need to ensure that the file /system/functions.custom.php is enabled in the site configuration.

Open the file /datas/config.php. 

Find the line:

$cfg['customfuncs'] = false;

And change it to:

$cfg['customfuncs'] = true;

Now Cotonti will automatically load your custom functions from /system/functions.custom.php.

2. Placing the Function Code

All the code should be placed in a single file: /system/functions.custom.php.

Overview of cot_customfuncs_* Functions for Working with Page Owner and Content Author

This article provides a detailed overview of ten custom functions prefixed with cot_customfuncs_, designed to determine the page owner, check administrative rights, and verify authorship in Cotonti templates. Each function includes a description, example calls in templates, and expected results.

All functions use standard Cotonti mechanisms: cot_import(), Cot::$db->query(), cot_auth_build(), and global variables. Template call examples are given in Cotonti-supported syntax: {PHP|function_name()} or <!-- IF {PHP|...} -->.

1. cot_customfuncs_getUserDataOwner()

Purpose

Returns an array of data for the page owner user. The owner is determined by URL parameters id (numeric user ID) or u (username). If neither is provided, the current logged-in user's ID is used.

Important: This function should not be called directly in templates because it returns an array that is not convenient to output without additional processing. Instead, use wrappers like cot_customfuncs_getOwnerId(), cot_customfuncs_getOwnerName(), etc.

Logic

1. Gets id from GET parameter id as an integer.
2. Gets u from GET parameter u as a string.
3. If u is provided but id is not, queries the users table to get user_id by user_name.
4. If neither id nor u is provided, but the user is logged in (Cot::$usr['id'] > 0), uses their ID.
5. If the resulting id > 0, returns a row from the users table (SELECT * FROM users WHERE user_id = ?) as an associative array.
6. If the user is not found, returns null.

PHP Call Example

$owner = cot_customfuncs_getUserDataOwner();
if (!empty($owner)) {
    echo $owner['user_id'];    // 123
    echo $owner['user_name'];  // Alice
    echo $owner['user_email']; // [email protected]
}

Template Usage Example (via wrappers)

<!-- IF {PHP|cot_customfuncs_getOwnerId()} > 0 -->
    The profile belongs to a registered user.
<!-- ENDIF -->

Return Value

• Array – user data if found. Contains all fields from the cot_users table, including user_id, user_name, user_email, user_maingrp, etc.
• null – if the user is not found or parameters are missing and the current user is not logged in.

Example Return

When opening a page with URL ?id=42, and a user with user_id=42 exists:

[
    'user_id' => 42,
    'user_name' => 'john_doe',
    'user_email' => '[email protected]',
    'user_maingrp' => 4,
    ...
]

2. cot_customfuncs_isOwnerSuperAdmin()

Purpose

Checks whether the page owner is a super administrator (group COT_GROUP_SUPERADMINS, usually ID 5). This function does not check the current user, but specifically the owner determined via cot_customfuncs_getUserDataOwner().

Logic

1. Calls cot_customfuncs_getUserDataOwner().
2. If data is obtained and the key user_maingrp exists, compares its value with the constant COT_GROUP_SUPERADMINS (value 5) after casting to integer.
3. Returns true or false.

Template Usage Example

<!-- IF {PHP|cot_customfuncs_isOwnerSuperAdmin()} -->
    <div class="alert alert-danger">The page owner is a super admin.</div>
<!-- ELSE -->
    <div class="alert alert-info">The page owner is not a super admin.</div>
<!-- ENDIF -->

Return Value

• true – if the owner is found and their main group equals COT_GROUP_SUPERADMINS.
• false – in all other cases.

Example Result

When owner.user_maingrp = 5:

The page owner is a super admin.

When owner.user_maingrp = 4:

The page owner is not a super admin.

3. cot_customfuncs_isOwnerAdmin()

Purpose

Checks whether the page owner has administrator rights in the admin area. Unlike isOwnerSuperAdmin(), it considers not only the main group COT_GROUP_SUPERADMINS but also secondary groups that may grant administrative privileges (e.g., the "Administrators" group with appropriate rights in the cot_auth table).

Logic

1. Gets owner data via cot_customfuncs_getUserDataOwner().
2. If no user_id, returns false.
3. Extracts user_id and user_maingrp.
4. Calls cot_auth_build($ownerId, $maingrp) – this builds a rights matrix for the specified user based on their main and secondary groups.
5. Checks for the presence of $rights['admin']['a'] (admin rights in the admin area).
6. Gets the bitmask of rights and checks if bit A (value 128) is set.
7. Returns true if the bit is set, otherwise false.

Template Usage Example

<!-- IF {PHP|cot_customfuncs_isOwnerAdmin()} -->
    <span class="badge bg-success">Owner is an administrator</span>
<!-- ELSE -->
    <span class="badge bg-secondary">Owner is a regular user</span>
<!-- ENDIF -->

Return Value

• true – if the owner has administrator rights (super admin or belongs to a group with the admin flag).
• false – if the owner is not an administrator or not found.

Example Result

If the owner is in a secondary group "Administrators" (with A rights in the admin area), the function returns true, and the template displays:

Owner is an administrator

If the owner is a regular user:

Owner is a regular user

4. cot_customfuncs_getOwnerGroupId()

Purpose

Returns the numeric ID of the main group (user_maingrp) of the page owner. Allows checking the owner's group membership without directly accessing the data array.

Logic

1. Calls cot_customfuncs_getUserDataOwner().
2. If the array contains user_maingrp, returns it as int.
3. If the owner is not found or the key is empty, returns 0.

Template Usage Example

<!-- IF {PHP|cot_customfuncs_getOwnerGroupId()} == 5 -->
    Owner is a super admin
<!-- ELSE -->
    <!-- IF {PHP|cot_customfuncs_getOwnerGroupId()} == 6 -->
        Owner is a moderator
    <!-- ELSE -->
        Owner belongs to another group
    <!-- ENDIF -->
<!-- ENDIF -->

Return Value

• Integer – ID of the owner's main group (e.g., 4, 5, 6).
• 0 – if the owner is not found.

Example Result

If the owner has user_maingrp = 5:

Owner is a super admin

5. cot_customfuncs_isOwner()

Purpose

Checks whether the currently logged-in user is the owner of the page. Compares the current user's ID with the owner ID obtained via cot_customfuncs_getUserDataOwner().

Logic

1. Gets owner data.
2. If data is found, the current user is logged in (Cot::$usr['id'] > 0) and their ID matches the owner's user_id, returns true.
3. Otherwise false.

Template Usage Example

<!-- IF {PHP|cot_customfuncs_isOwner()} -->
    <a href="{PHP|cot_url('users', 'm=profile')}">Edit profile</a>
<!-- ENDIF -->

Return Value

• true – if the current user is the owner of the page being viewed.
• false – if not the owner or not logged in.

Example Result

If the current user has user_id = 42 and the page owner also has user_id = 42, the "Edit profile" link will be shown.

6. cot_customfuncs_isTopicAuthor()

Purpose

Checks whether the current user is the author of a forum topic. The topic ID is taken from the URL parameter q. The function compares ft_firstposterid (ID of the first post's author) with the current user's ID.

Logic

1. Gets topicId from GET parameter q as an integer.
2. If the user is not logged in or topicId is empty, returns false.
3. Queries the cot_forum_topics table to get ft_firstposterid.
4. If posterId > 0 and matches the current user's ID, returns true, otherwise false.

Template Usage Example

<!-- IF {PHP|cot_customfuncs_isTopicAuthor()} -->
    <button>Delete topic</button>
<!-- ENDIF -->

Return Value

• true – if the current user is the topic author.
• false – if not the author, not logged in, or the q parameter is missing.

Example Result

With URL ?q=15, where topic ft_id=15 was created by user ID 42, and the current user has ID 42, the "Delete topic" button will appear.

7. cot_customfuncs_isPageAuthor()

Purpose

Checks whether the current user is the author of a page (article). The page ID is taken from the URL parameter id. Compares page_ownerid with the current user's ID.

Logic

1. Gets pageId from GET parameter id as an integer.
2. If the user is not logged in or pageId is empty, returns false.
3. Queries the cot_pages table to get page_ownerid.
4. If ownerId > 0 and matches the current user's ID, returns true, otherwise false.

Template Usage Example

<!-- IF {PHP|cot_customfuncs_isPageAuthor()} -->
    <div>You are the author of this article.</div>
<!-- ELSE -->
    <div>You are not the author.</div>
<!-- ENDIF -->

Return Value

• true – if the current user is the article author.
• false – if not the author or the id parameter is missing.

Example Result

With URL ?id=99, where page page_id=99 belongs to user ID 42, and the current user has ID 42, the output will be "You are the author of this article."

8. cot_customfuncs_getOwnerId()

Purpose

Returns the numeric ID of the page owner. This is a wrapper around cot_customfuncs_getUserDataOwner() extracting only user_id.

Logic

1. Calls cot_customfuncs_getUserDataOwner().
2. If the array contains user_id, returns it as int, otherwise 0.

Template Usage Example

Owner ID: {PHP|cot_customfuncs_getOwnerId()}

Return Value

• Integer – owner ID (e.g., 42).
• 0 – if the owner is not found.

Example Result

If the owner is found:

Owner ID: 42

9. cot_customfuncs_getOwnerName()

Purpose

Returns the owner's username escaped for safe HTML output. This is a wrapper around cot_customfuncs_getUserDataOwner() extracting user_name and applying htmlspecialchars().

Logic

1. Calls cot_customfuncs_getUserDataOwner().
2. If the array contains user_name, returns it after htmlspecialchars().
3. If the owner is not found or the name is empty, returns an empty string.

Template Usage Example

Owner name: {PHP|cot_customfuncs_getOwnerName()}

Return Value

• String – owner's name (e.g., "Alice"), already escaped.
• Empty string – if the name is not found.

Example Result

When a name exists:

Owner name: Alice

10. cot_customfuncs_getPageOwnerId()

Purpose

Returns the numeric ID of the page owner (article), based on the current URL. Unlike cot_customfuncs_getOwnerId(), this function queries the cot_pages table directly instead of the users table.

Logic

1. Gets pageId from GET parameter id as an integer.
2. Executes query: SELECT page_ownerid FROM cot_pages WHERE page_id = ?.
3. If a value is returned, returns it as int, otherwise 0.

Template Usage Example

Article author ID: {PHP|cot_customfuncs_getPageOwnerId()}

Return Value

• Integer – article owner ID.
• 0 – if the article is not found or ownerid is empty.

Example Result

With URL ?id=99, where page_ownerid=42:

Article author ID: 42

Function Summary Table

Conclusion

The set of cot_customfuncs_* functions provides a convenient interface for working with the page owner and verifying authorship in Cotonti templates. Use them according to your specific task:

• To check the current user's ownership of content, use cot_customfuncs_isOwner(), cot_customfuncs_isPageAuthor(), or cot_customfuncs_isTopicAuthor().
• To obtain information about the page owner, use cot_customfuncs_getOwnerId(), cot_customfuncs_getOwnerName(), or cot_customfuncs_getOwnerGroupId().
• To check the owner's administrative privileges, use cot_customfuncs_isOwnerAdmin() (considers secondary groups) or cot_customfuncs_isOwnerSuperAdmin() (super admin only).

All functions are built on standard Cotonti mechanisms and are safe to use in templates.

```