# man > User::Identity::Collection::Users

---
type: CommandReference
command: User::Identity::Collection::Users
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `User::Identity::Collection::Users->new('people')` — create a new users collection
- `$collection->addCollection('User::Identity', name => 'john')` — add a new user
- `$collection->find('john')` — find a user by name
- `$collection->addRole('admin')` — add a role to the collection
- `$collection->sorted()` — sort users by name

## Name

a collection of users

## Synopsis

perl
use User::Identity::Collection::Users;

my $users = User::Identity::Collection::Users->new('people');
$users->addCollection('User::Identity', name => 'john');
my $user = $users->find('john');
## Options

Constructor options for `new( [$name], %options )`:

- `-description` — STRING, description of the collection
- `-item_type` — CLASS, default `User::Identity`
- `-name` — STRING, default 'people'
- `-parent` — OBJECT, parent collection
- `-roles` — ROLE|ARRAY, roles to assign

## Methods

All methods are inherited from [User::Identity::Collection](https://metacpan.org/pod/User::Identity::Collection) and [User::Identity::Item](https://metacpan.org/pod/User::Identity::Item) unless noted.

### Constructors

- `new( [$name], %options )` — create a new collection

### Attributes

- `description()` — get description
- `itemType()` — get item type
- `name( [$newname] )` — get/set name
- `roles()` — get roles

### Collections

- `add($collection, $role)` — add a collection
- `addCollection( $object | [$type], %options )` — add a collection
- `collection($name)` — get a collection by name
- `parent( [$parent] )` — get/set parent
- `removeCollection($object|$name)` — remove a collection
- `type()` — get type
- `user()` — get user

### Maintaining roles

- `addRole($role | [$name],%options | ARRAY)` — add a role
- `removeRole($role|$name)` — remove a role
- `renameRole( $role|$oldname, $newname )` — rename a role
- `sorted()` — get sorted list of roles

### Searching

- `find($name|CODE|undef)` — find an item by name or code

## Diagnostics

### Errors

- `$object is not a collection.` — First argument is not a User::Identity::Collection object.
- `Cannot create a $type to add this to my collection.` — Failed to create a native collection object.
- `Cannot load collection module for $type ($class).` — Module not found or compilation error.
- `Cannot rename $name into $newname: already exists` — Target name already in use.
- `Cannot rename $name into $newname: doesn't exist` — Source name not found.
- `Creation of a collection via $class failed.` — Object instantiation failed.
- `Don't know what type of collection you want to add.` — Missing type when adding a collection.
- `Wrong type of role for $collection: requires a $expect but got a $type` — Role type mismatch.

### Warnings

- `No collection $name` — Collection does not exist and cannot be created.

## See Also

- [User::Identity::Collection](https://metacpan.org/pod/User::Identity::Collection)
- [User::Identity::Item](https://metacpan.org/pod/User::Identity::Item)
- [User::Identity](https://metacpan.org/pod/User::Identity)
- Part of `User-Identity` distribution version 1.01 (2022-02-11). [Website](http://perl.overmeer.net/CPAN/)