Documentation

Group extends AbstractBaseApi
in package

Canvas LMS Groups API

Provides functionality to manage groups in Canvas LMS. Groups can be used for collaborative work, discussions, and assignments.

Usage Examples:

// Create a group (defaults to account context)
$group = Group::create([
    'name' => 'Study Group Alpha',
    'description' => 'Weekly study sessions'
]);

// Get first page of groups (memory efficient)
$groups = Group::get();

// Get ALL groups (⚠️ Be cautious with large institutions)
$allGroups = Group::all();

// Get paginated groups (recommended for listings)
$paginated = Group::paginate(['per_page' => 50]);
foreach ($paginated->getData() as $group) {
    echo $group->name . ' (' . $group->membersCount . ' members)';
}

// Get groups for a specific course
$course = Course::find(123);
$courseGroups = $course->groups(); // Returns first page only

// To get ALL groups for a course:
$groups = Group::fetchByContext('courses', 123, true); // true = all pages
Tags
see
https://canvas.instructure.com/doc/api/groups.html

Table of Contents

Properties

$accountId  : int|null
The account ID the group belongs to
$avatarUrl  : string|null
URL to the group's avatar
$contextName  : string|null
The course or account name that the group belongs to
$contextType  : string|null
The context type (Course, Account)
$courseId  : int|null
The course ID the group belongs to (if applicable)
$description  : string|null
The group description
$followedByUser  : bool|null
Whether the current user is following this group
$groupCategoryId  : int|null
The group category ID
$htmlUrl  : string|null
HTML URL to the group
$id  : int|null
The unique identifier for the group
$isFavorite  : bool|null
Whether the group is a favorite
$isPublic  : bool|null
Whether the group is public (applies only to community groups)
$joinLevel  : string|null
Current group join level
$maxMembership  : int|null
Maximum membership allowed in the group
$membersCount  : int|null
Number of members in the group
$name  : string|null
The display name of the group
$nonCollaborative  : bool|null
Indicates whether this group category is non-collaborative
$permissions  : array<string, bool>|null
Permissions for the current user
$role  : string|null
The role of the current user in the group
$sisGroupId  : string|null
The SIS ID of the group
$sisImportId  : int|null
The SIS import ID
$storageQuotaMb  : int|null
The storage quota for the group in bytes
$users  : array<string|int, mixed>|null
Optional list of users that are members in the group Returned only if include[]=users
$workflowState  : string|null
The workflow state of the group
$apiClient  : HttpClientInterface
$methodAliases  : array<string|int, mixed>
Define method aliases

Methods

__callStatic()  : mixed
Magic method to handle function aliases
__construct()  : mixed
BaseApi constructor.
activityStream()  : array{0?: array{id: int, title: string, message: string, type: string, read_state: bool, created_at: string, updated_at: string}}
Get group activity stream
activityStreamSummary()  : array<string|int, array{type: string, unread_count: int, count: int}>
Get group activity stream summary
addUser()  : bool
Add user to group
all()  : array<string|int, static>
Get all pages of results
contentMigration()  : ContentMigration
Get a specific content migration for this group
contentMigrations()  : array<string|int, ContentMigration>
Get content migrations for this group
create()  : self
Create a new group
createContentMigration()  : ContentMigration
Create a content migration for this group
createMembership()  : GroupMembership
Create a membership in this group
delete()  : self
Delete the group
fetchByContext()  : array<string|int, Group>
List groups for a specific context
fetchByContextPaginated()  : PaginatedResponse
Get paginated groups for a specific context
fetchUserGroups()  : array<string|int, Group>
Get groups for a specific user
fetchUserGroupsPaginated()  : PaginatedResponse
Get paginated groups for a specific user
find()  : self
Get a single group by ID
get()  : array<string|int, static>
Get first page of results
getAccountId()  : int|null
getContextName()  : string|null
getContextType()  : string|null
getCourseId()  : int|null
getDescription()  : string|null
getGroupCategoryId()  : int|null
getHtmlUrl()  : string|null
getId()  : int|null
getIsPublic()  : bool|null
getJoinLevel()  : string|null
getMembersCount()  : int|null
getName()  : string|null
getNonCollaborative()  : bool|null
getPermissions()  : array<string, bool>|null
getRole()  : string|null
getUsers()  : array<string|int, mixed>|null
getWorkflowState()  : string|null
importCommonCartridge()  : ContentMigration
Import content from a Common Cartridge file
importZipFile()  : ContentMigration
Import content from a ZIP file
invite()  : self
Invite users to this group
mediaAttachments()  : array<string|int, MediaObject>
Get media attachments for this group
mediaObjects()  : array<string|int, MediaObject>
Get media objects for this group
members()  : array<string|int, User>
Get group members
memberships()  : array<string|int, GroupMembership>
Get memberships for this group
paginate()  : PaginationResult
Get paginated results with metadata
permissions()  : array<string, bool>
Get permissions for the current user
removeUser()  : self
Remove user from group
save()  : self
Save the group (create or update)
setAccountId()  : void
setApiClient()  : void
Set the API client
setContextName()  : void
setContextType()  : void
setCourseId()  : void
setDescription()  : void
setGroupCategoryId()  : void
setHtmlUrl()  : void
setId()  : void
setIsPublic()  : void
setJoinLevel()  : void
setMembersCount()  : void
setName()  : void
setNonCollaborative()  : void
setPermissions()  : void
setRole()  : void
setUsers()  : void
setWorkflowState()  : void
update()  : self
Update group
castValue()  : DateTime|mixed
Cast a value to the correct type
checkApiClient()  : void
Check if the API client is set, if not, instantiate a new one
convertPaginatedResponseToModels()  : array<string|int, static>
Helper method to convert paginated response data to model instances
createConfiguredHttpClient()  : HttpClient
Create an HttpClient with configured middleware
createPaginationResult()  : PaginationResult
Helper method to create PaginationResult from paginated response
getEndpoint()  : string
Get the API endpoint for this resource
getPaginatedResponse()  : PaginatedResponse
Helper method to get paginated response from API endpoint
populate()  : void
Populate the object with new data
toDtoArray()  : array<string, mixed>
Convert group to DTO array

Properties

$accountId

The account ID the group belongs to

public int|null $accountId = null

$avatarUrl

URL to the group's avatar

public string|null $avatarUrl = null

$contextName

The course or account name that the group belongs to

public string|null $contextName = null

$contextType

The context type (Course, Account)

public string|null $contextType = null

$courseId

The course ID the group belongs to (if applicable)

public int|null $courseId = null

$description

The group description

public string|null $description = null

$followedByUser

Whether the current user is following this group

public bool|null $followedByUser = null

$groupCategoryId

The group category ID

public int|null $groupCategoryId = null

$htmlUrl

HTML URL to the group

public string|null $htmlUrl = null

$id

The unique identifier for the group

public int|null $id = null

$isFavorite

Whether the group is a favorite

public bool|null $isFavorite = null

$isPublic

Whether the group is public (applies only to community groups)

public bool|null $isPublic = null

$joinLevel

Current group join level

public string|null $joinLevel = null

$maxMembership

Maximum membership allowed in the group

public int|null $maxMembership = null

$membersCount

Number of members in the group

public int|null $membersCount = null

$name

The display name of the group

public string|null $name = null

$nonCollaborative

Indicates whether this group category is non-collaborative

public bool|null $nonCollaborative = null

$permissions

Permissions for the current user

public array<string, bool>|null $permissions = null

$role

The role of the current user in the group

public string|null $role = null

$sisGroupId

The SIS ID of the group

public string|null $sisGroupId = null

$sisImportId

The SIS import ID

public int|null $sisImportId = null

$storageQuotaMb

The storage quota for the group in bytes

public int|null $storageQuotaMb = null

$users

Optional list of users that are members in the group Returned only if include[]=users

public array<string|int, mixed>|null $users = null

$workflowState

The workflow state of the group

public string|null $workflowState = null

$methodAliases

Define method aliases

protected static array<string|int, mixed> $methodAliases = ['get' => ['fetch', 'list', 'fetchAll'], 'all' => ['fetchAllPages', 'getAll'], 'paginate' => ['getPaginated', 'withPagination', 'fetchPage'], 'find' => ['one', 'getOne']]

Methods

__callStatic()

Magic method to handle function aliases

public static __callStatic(string $name, array<string|int, mixed> $arguments) : mixed
Parameters
$name : string
$arguments : array<string|int, mixed>
Tags
throws
InvalidArgumentException

__construct()

BaseApi constructor.

public __construct(array<string|int, mixed> $data) : mixed
Parameters
$data : array<string|int, mixed>

activityStream()

Get group activity stream

public activityStream([array<string, mixed> $params = [] ]) : array{0?: array{id: int, title: string, message: string, type: string, read_state: bool, created_at: string, updated_at: string}}

Returns an array of activity stream items which may include:

  • Discussion topics (type: 'DiscussionTopic')
  • Announcements (type: 'Announcement')
  • Conversations (type: 'Conversation')
  • Messages (type: 'Message')
  • Submissions (type: 'Submission')
  • Conference invitations (type: 'WebConference')
  • Collaborations (type: 'Collaboration')
  • AssessmentRequests (type: 'AssessmentRequest')

Each item contains: id, title, message, type, read_state, created_at, updated_at, and context-specific fields based on the activity type.

Parameters
$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
array{0?: array{id: int, title: string, message: string, type: string, read_state: bool, created_at: string, updated_at: string}} —

Array of activity stream items

activityStreamSummary()

Get group activity stream summary

public activityStreamSummary() : array<string|int, array{type: string, unread_count: int, count: int}>

Returns a summary of the group's activity stream with counts by type.

Tags
throws
CanvasApiException
Return values
array<string|int, array{type: string, unread_count: int, count: int}> —

Array of activity type summaries

addUser()

Add user to group

public addUser(int $userId) : bool

Use createMembership() for more control

Parameters
$userId : int

User ID to add

Tags
throws
CanvasApiException
Return values
bool

all()

Get all pages of results

public static all([array<string, mixed> $params = [] ]) : array<string|int, static>
Parameters
$params : array<string, mixed> = []

Query parameters

Return values
array<string|int, static>

contentMigrations()

Get content migrations for this group

public contentMigrations([array<string, mixed> $params = [] ]) : array<string|int, ContentMigration>
Parameters
$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
array<string|int, ContentMigration>

fetchByContext()

List groups for a specific context

public static fetchByContext(string $contextType, int $contextId[, array<string, mixed> $params = [] ]) : array<string|int, Group>
Parameters
$contextType : string

'accounts' or 'courses'

$contextId : int

Account or Course ID

$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
array<string|int, Group>

fetchByContextPaginated()

Get paginated groups for a specific context

public static fetchByContextPaginated(string $contextType, int $contextId[, array<string, mixed> $params = [] ]) : PaginatedResponse
Parameters
$contextType : string

'accounts' or 'courses'

$contextId : int

Account or Course ID

$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
PaginatedResponse

fetchUserGroups()

Get groups for a specific user

public static fetchUserGroups(int $userId[, array<string, mixed> $params = [] ]) : array<string|int, Group>
Parameters
$userId : int

User ID

$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
array<string|int, Group>

fetchUserGroupsPaginated()

Get paginated groups for a specific user

public static fetchUserGroupsPaginated(int $userId[, array<string, mixed> $params = [] ]) : PaginatedResponse
Parameters
$userId : int

User ID

$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
PaginatedResponse

find()

Get a single group by ID

public static find(int $id[, array<string|int, mixed> $params = [] ]) : self
Parameters
$id : int

Group ID

$params : array<string|int, mixed> = []

Optional query parameters

Tags
throws
CanvasApiException
Return values
self

get()

Get first page of results

public static get([array<string, mixed> $params = [] ]) : array<string|int, static>
Parameters
$params : array<string, mixed> = []

Query parameters

Return values
array<string|int, static>

getAccountId()

public getAccountId() : int|null
Return values
int|null

getContextName()

public getContextName() : string|null
Return values
string|null

getContextType()

public getContextType() : string|null
Return values
string|null

getCourseId()

public getCourseId() : int|null
Return values
int|null

getDescription()

public getDescription() : string|null
Return values
string|null

getGroupCategoryId()

public getGroupCategoryId() : int|null
Return values
int|null

getHtmlUrl()

public getHtmlUrl() : string|null
Return values
string|null

getId()

public getId() : int|null
Return values
int|null

getIsPublic()

public getIsPublic() : bool|null
Return values
bool|null

getJoinLevel()

public getJoinLevel() : string|null
Return values
string|null

getMembersCount()

public getMembersCount() : int|null
Return values
int|null

getName()

public getName() : string|null
Return values
string|null

getNonCollaborative()

public getNonCollaborative() : bool|null
Return values
bool|null

getPermissions()

public getPermissions() : array<string, bool>|null
Return values
array<string, bool>|null

getRole()

public getRole() : string|null
Return values
string|null

getUsers()

public getUsers() : array<string|int, mixed>|null
Return values
array<string|int, mixed>|null

getWorkflowState()

public getWorkflowState() : string|null
Return values
string|null

importCommonCartridge()

Import content from a Common Cartridge file

public importCommonCartridge(string $filePath[, array<string, mixed> $options = [] ]) : ContentMigration
Parameters
$filePath : string

Path to the .imscc file

$options : array<string, mixed> = []

Additional options

Tags
throws
CanvasApiException
Return values
ContentMigration

importZipFile()

Import content from a ZIP file

public importZipFile(string $filePath[, array<string, mixed> $options = [] ]) : ContentMigration
Parameters
$filePath : string

Path to the .zip file

$options : array<string, mixed> = []

Additional options

Tags
throws
CanvasApiException
Return values
ContentMigration

invite()

Invite users to this group

public invite(array<string|int, string> $emails) : self
Parameters
$emails : array<string|int, string>

Email addresses to invite

Tags
throws
CanvasApiException
Return values
self

mediaAttachments()

Get media attachments for this group

public mediaAttachments([array<string, mixed> $params = [] ]) : array<string|int, MediaObject>
Parameters
$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
array<string|int, MediaObject> —

Array of MediaObject instances

mediaObjects()

Get media objects for this group

public mediaObjects([array<string, mixed> $params = [] ]) : array<string|int, MediaObject>
Parameters
$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
array<string|int, MediaObject> —

Array of MediaObject instances

members()

Get group members

public members([array<string, mixed> $params = [] ]) : array<string|int, User>
Parameters
$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
array<string|int, User>

memberships()

Get memberships for this group

public memberships([array<string, mixed> $params = [] ]) : array<string|int, GroupMembership>
Parameters
$params : array<string, mixed> = []

Query parameters

Tags
throws
CanvasApiException
Return values
array<string|int, GroupMembership>

permissions()

Get permissions for the current user

public permissions([array<string|int, string> $permissions = [] ]) : array<string, bool>
Parameters
$permissions : array<string|int, string> = []

Optional array of permission names to check

Tags
throws
CanvasApiException
Return values
array<string, bool>

removeUser()

Remove user from group

public removeUser(int $userId) : self

Note: Canvas API doesn't provide a direct endpoint to remove a user by user ID. This method fetches memberships to find the correct membership ID for deletion. For better performance when removing multiple users, consider fetching all memberships once and managing them locally.

Parameters
$userId : int

User ID to remove

Tags
throws
CanvasApiException
Return values
self

setAccountId()

public setAccountId(int|null $accountId) : void
Parameters
$accountId : int|null

setContextName()

public setContextName(string|null $contextName) : void
Parameters
$contextName : string|null

setContextType()

public setContextType(string|null $contextType) : void
Parameters
$contextType : string|null

setCourseId()

public setCourseId(int|null $courseId) : void
Parameters
$courseId : int|null

setDescription()

public setDescription(string|null $description) : void
Parameters
$description : string|null

setGroupCategoryId()

public setGroupCategoryId(int|null $groupCategoryId) : void
Parameters
$groupCategoryId : int|null

setHtmlUrl()

public setHtmlUrl(string|null $htmlUrl) : void
Parameters
$htmlUrl : string|null

setId()

public setId(int|null $id) : void
Parameters
$id : int|null

setIsPublic()

public setIsPublic(bool|null $isPublic) : void
Parameters
$isPublic : bool|null

setJoinLevel()

public setJoinLevel(string|null $joinLevel) : void
Parameters
$joinLevel : string|null

setMembersCount()

public setMembersCount(int|null $membersCount) : void
Parameters
$membersCount : int|null

setName()

public setName(string|null $name) : void
Parameters
$name : string|null

setNonCollaborative()

public setNonCollaborative(bool|null $nonCollaborative) : void
Parameters
$nonCollaborative : bool|null

setPermissions()

public setPermissions(array<string, bool>|null $permissions) : void
Parameters
$permissions : array<string, bool>|null

setRole()

public setRole(string|null $role) : void
Parameters
$role : string|null

setUsers()

public setUsers(array<string|int, mixed>|null $users) : void
Parameters
$users : array<string|int, mixed>|null

setWorkflowState()

public setWorkflowState(string|null $workflowState) : void
Parameters
$workflowState : string|null

castValue()

Cast a value to the correct type

protected castValue(string $key, mixed $value) : DateTime|mixed
Parameters
$key : string
$value : mixed
Tags
throws
Exception
Return values
DateTime|mixed

checkApiClient()

Check if the API client is set, if not, instantiate a new one

protected static checkApiClient() : void

convertPaginatedResponseToModels()

Helper method to convert paginated response data to model instances

protected static convertPaginatedResponseToModels(PaginatedResponse $paginatedResponse) : array<string|int, static>
Parameters
$paginatedResponse : PaginatedResponse
Return values
array<string|int, static>

getEndpoint()

Get the API endpoint for this resource

protected static getEndpoint() : string
Return values
string

getPaginatedResponse()

Helper method to get paginated response from API endpoint

protected static getPaginatedResponse(string $endpoint[, array<string|int, mixed> $params = [] ]) : PaginatedResponse
Parameters
$endpoint : string

The API endpoint path

$params : array<string|int, mixed> = []

Query parameters for the request

Return values
PaginatedResponse

populate()

Populate the object with new data

protected populate(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>
Tags
throws
Exception

toDtoArray()

Convert group to DTO array

protected toDtoArray() : array<string, mixed>
Return values
array<string, mixed> 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results