CartThrob Permissions Manager Version 5.1.0

Overview

CartThrob Permissions Manager is the administrative layer for permissions in CartThrob. It gives you two main tools:

• define reusable permission items (for example, premium_articles, video_library, course_level_2)
• assign or remove those permissions for members

This module works with core CartThrob permission tags and is bundled with the Subscriptions package in this release.

Requirements

• CartThrob Permissions Manager 5.1.0
• CartThrob core (Permission and PermissionItem models)
• PHP >= 7.1 (from cartthrob_permissions_manager/composer.json)
• ExpressionEngine version supported by your CartThrob install

Installation

Bundled path in this package:

/system/user/addons/cartthrob_permissions_manager/

Install via ExpressionEngine Control Panel:

1. Go to Add-ons.
2. Install CartThrob Permissions Manager.
3. Run add-on updates if prompted.

The updater installs:

• add-on components
• cartthrob_permissions_manager fieldtype
• tables: cartthrob_permissions, cartthrob_permission_items, cartthrob_permissions_manager_settings

Upgrading

1. Deploy updated files in /system/user/addons/cartthrob_permissions_manager/.
2. Go to Add-ons and run add-on updates.
3. Re-open Permissions Manager and verify:

- permission items list loads - assigned permissions list loads - create/edit forms save without validation errors

Start Here (10-Minute Setup)

Goal: create one permission item, sell or assign it, and protect one piece of content.

Prerequisites Checklist

• CartThrob is installed and active.
• Permissions Manager is installed.
• You have a test member account.
• You know which content should be protected.

First Success Path

1. Create a permission item in Permissions (for example, Premium Access).
2. Assign that permission to a test member using Assigned Permissions.
3. Wrap protected template content with has_permission.
4. Confirm the member can see content when assigned and cannot when removed.

Common Tasks With Examples

1. Create a Reusable Access SKU

Goal: define access once and reuse it in products, subscriptions, and manual assignment.

1. Go to Permissions.
2. Click New.
3. Set Title: Premium Video Library.
4. Add a short Description and Access overview.
5. Keep Status as open and save.

Outcome: this permission item can be attached to cart actions, subscriptions, or manual grants.

2. Manually Grant Access to a Customer

Goal: give immediate access without checkout.

1. Go to Assigned Permissions.
2. Click New.
3. Enter member_id.
4. Choose a permission from the dropdown.
5. Optionally set order_id, item_id, and sub_id.
6. Save.

Outcome: member receives access immediately, and the assignment appears in list views and template tags.

3. Sell Access Through CartThrob Checkout

Goal: add permission IDs when adding an item to cart.

{exp:cartthrob:add_to_cart_form entry_id="{entry_id}" permissions="12|15" return="store/cart"}
    <button type="submit">Buy Access</button>
{/exp:cartthrob:add_to_cart_form}

Outcome: successful order creates permission assignment records for the member.

4. Protect Content by Permission

Goal: allow only members with specific permissions.

{exp:cartthrob:has_permission permissions="12|15" member_id="CURRENT_USER"}
    <h2>Premium Content</h2>
    <p>Only authorized members can see this block.</p>

    {if no_results}
        <p>You do not have access.</p>
    {/if}
{/exp:cartthrob:has_permission}

Outcome: content is rendered only when one of the requested permissions is assigned.

Quick Links For Existing Users

• Need to manually grant/revoke member access: see Assigned Permissions.
• Need to manage access catalog: see Permission Items.
• Need template checks: see has_permission and permissions tags.
• Need Subscriptions integration flow: see Using With Subscriptions.

Control Panel Reference

Assigned Permissions (addons/settings/cartthrob_permissions_manager)

Sidebar behavior:

• includes Assigned Permissions and Permissions sections
• shows a Subscriptions utility link when cartthrob_subscriptions is installed

Table Columns

1. ID:

- assignment record ID - click opens Edit Permission

2. Member ID:

- shows screen_name (member_id) when member exists - click opens the member profile settings page - shows Guest when no member relation is available

3. Order ID:

- shows related order entry title and entry ID when available - click opens channel entry edit for that order - shows N/A when not linked

4. Item ID:

- stored item identifier for the assignment record

5. Permission:

- shows raw permission ID if no relation found - when related Permission Item exists, shows title (id) - click opens Edit Permission Item

6. Manage toolbar:

- edit opens Edit Permission - remove opens delete confirmation

Form: Assign Permission (.../assign-permission)

Fields:

1. member_id (text)

- target member receiving access

2. order_id (text)

- optional order reference

3. item_id (text)

- optional item reference

4. permission (select)

- chooses one configured permission item - dropdown is populated from existing Permission Items

5. sub_id (text)

- optional subscription linkage identifier

Behavior on submit:

• validates member_id as required integer and existing member
• validates permission as required integer and existing permission item
• enforces uniqueness for the same member_id + permission pair
• on success, saves and redirects to Assigned Permissions list

Form: Edit Permission (.../edit-permission/{id})

• same fields and validation as Assign Permission
• updates the existing assignment record

Delete: Assigned Permission (.../delete-permission/{id})

Fields:

1. confirm (yes/no)

- must be yes to delete

Behavior:

• if confirmed, deletes assignment record and returns to list

Permission Items (.../permission-items)

Table Columns

1. ID:

- permission item ID - click opens Edit Permission Item

2. Title:

- human-readable name for the permission

3. Status:

- open or closed

4. Access overview:

- summary of what a customer gets - displays N/A when empty

5. Manage toolbar:

- edit opens item edit form - remove opens delete confirmation

Form: Create/Edit Permission Item

Fields:

1. title (text, required)

- display label used in CP and dropdowns

2. description (textarea)

- short internal or customer-facing description

3. access_overview (text)

- concise explanation of access scope

4. status (select: open, closed, required)

- availability state for usage in tags/forms

Behavior:

• validates required fields
• on success, saves and redirects to Permission Items list

Delete: Permission Item (.../delete-permission-item/{id})

Fields:

1. confirm (yes/no)

- must be yes to delete

Behavior:

• if confirmed, deletes permission item and returns to list

Fieldtype Reference

Fieldtype: cartthrob_permissions_manager

Use this fieldtype on product channels to attach one or more permission IDs to entries.

Publish/Edit UI Behavior

• renders as multi-select of existing permission items
• selected values are stored as encoded multi-value data

Template Output

Single variable

Outputs pipe-delimited permission IDs.

{permissions}

Example output: 1|3|11

Supported parameter:

• limit: truncates output to N IDs

Variable pair

Loops through selected permission IDs and exposes permission item data.

{permissions limit="10"}
    {count}. {id} - {title} ({status})
{/permissions}

Pair variables from permission item lookup:

• count
• id
• title
• description
• access_overview
• status

Supported parameters:

• limit
• backspace

Template Tags

permissions

Returns permission assignment rows from cartthrob_permissions.

Parameters

1. id

- permission assignment record ID(s) - pipe-delimited supported

2. order_id

- filter by linked order entry ID(s) - pipe-delimited supported - note: mutually exclusive with id in current query branch

3. item_id

- filter by item ID(s) - pipe-delimited supported

4. permission

- filter by permission item ID(s) - pipe-delimited supported

5. member_id

- defaults to current member when omitted - supports CURRENT_USER, {member_id}, {logged_in_member_id} - non-admin users are restricted to their own member ID

6. limit

- max rows to return - default: 100

7. order_by

- sort column - default: id

8. sort

- asc or desc - default: desc - applied when order_by is present

9. sub_id

- intended for subscription-linked filtering - currently unusable in 5.1.0 due hard debug exit in the tag implementation

Variables

• {id} assignment row ID
• {member_id} member receiving permission
• {order_id} order entry ID
• {item_id} item identifier
• {permission} permission item ID
• {sub_id} subscription linkage ID (when present)

Conditionals

• {if no_results} rendered when no matching assignments exist

Example

{exp:cartthrob:permissions member_id="CURRENT_USER" permission="12|15" limit="25" order_by="id" sort="desc"}
    <li>Permission {permission} (record {id})</li>

    {if no_results}
        <li>No permissions found.</li>
    {/if}
{/exp:cartthrob:permissions}

has_permission

Checks whether a member has one of the given permission IDs.

Parameters

1. permissions (required)

- permission item ID(s), pipe-delimited

2. member_id

- optional member target - supports CURRENT_USER, {member_id}, {logged_in_member_id} - defaults to current member

Conditionals

• {if no_results} for alternate output when access check fails

Example

{exp:cartthrob:has_permission permissions="12|15" member_id="CURRENT_USER"}
    <p>Access granted.</p>

    {if no_results}
        <p>Access denied.</p>
    {/if}
{/exp:cartthrob:has_permission}

permission_items

Returns permission item details from cartthrob_permission_items.

Parameters

1. id (required for output in current 5.1.0 implementation)

- permission item ID to retrieve

2. status

- defaults to open when id is provided - typical values: open, closed

Variables

• {id} permission item ID
• {status} open/closed
• {title} title
• {description} description
• {access_overview} access summary

Conditionals

• {if no_results} when item does not match filters

Example

{exp:cartthrob:permission_items id="12" status="open"}
    <h3>{title}</h3>
    <p>{description}</p>
    <p>{access_overview}</p>

    {if no_results}
        <p>Permission not available.</p>
    {/if}
{/exp:cartthrob:permission_items}

Using With Subscriptions

Permissions Manager is the access layer; Subscriptions supplies recurring billing and plan lifecycle. Use them together for recurring access products.

Recommended Flow

1. Create permission items in Permissions Manager.
2. In Subscriptions plan setup, select one or more permissions in the plan permissions checklist.
3. Sell the subscription plan.
4. On subscription create/update, Subscriptions writes assignment rows in cartthrob_permissions with sub_id linkage.
5. Gate protected content with has_permission (or with Subscriptions-specific checks where needed).

What This Gives You

• recurring plans can automatically maintain member access grants
• plan permission changes can be synchronized to subscriptions on plan edit
• support teams can still manually inspect/adjust individual permissions from Permissions Manager

Implementation Notes

• Subscriptions plan edit triggers permission sync through syncPlanPermissions(...).
• Subscriptions writes subscription-linked assignment rows using sub_id.
• Subscriptions CP requires Permissions Manager to be installed.
• Subscriptions-specific access helper tag reference: /add-ons/subscriptions/tags/has_subscription_permission

Known Limitations (v5.1.0)

1. permissions tag sub_id parameter is currently broken (hard debug output + exit).
2. permission_items tag currently returns data only when id is provided.
3. Duplicate assignment of the same permission to the same member is blocked by validation.

Changelog Notes

• Current code version: 5.1.0 (from addon.setup.php).
• Dedicated Permissions Manager changelog file is not present in this package.
• Legacy public docs list 2.5 notes, but this document is aligned to current code behavior.