> ## Documentation Index
> Fetch the complete documentation index at: https://help.pixwel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flags

# Flags (new and updated tags)

On the projects screen, you may see flags like "new" or "updated" against projects, assets or files:

<img src="https://mintcdn.com/pixwel/EzZene0sLkTaATKH/img/catalog_flags.png?fit=max&auto=format&n=EzZene0sLkTaATKH&q=85&s=5db6c35b786facc2474fc9f1c87443e2" alt="Updated flag" width="206" height="302" data-path="img/catalog_flags.png" />

There is a database table `catalog_flags` (API class [CatalogFlags](https://github.com/Pixwel/platform/blob/2.x/api/models/CatalogFlags.php). Anything older than its `expires` field [is automatically removed](https://github.com/Pixwel/platform/blob/2.x/api/_build/migrations/91277488-auto-expire-catalog-flags.js).

The flags are set from the Events model:

```
 ___________       ___________       _____________
|           |     |           |     |             |
| Something |  \  |   Event   |  \  |  Catalog::  |
|  happens  |  /  | generated |  /  | updateFlags |
|           |     |           |     |  triggered  |
|___________|     |___________|     |_____________|
```

`updateFlags` is supplied an event and a list of users. It then upserts (creates or updates) that flag per-user. The CatalogFlags determines whether an event is a project, asset, or file level flag by extracting that information from the event in the `collect()` function.

The UI inspects `project.$flags` (an array of strings, generally empty if nothing is new/updated) to determine whether to display flags.

To do anything with flags, an event has to:

1. Be triggered by something - i.e. have a rule - you can see a list of rules in [Events::\$\_rules](https://github.com/Pixwel/platform/blob/2.x/api/models/Events.php).
2. Have a collector in the [`CatalogFlags::collect()` function](https://github.com/Pixwel/platform/blob/2.x/api/models/CatalogFlags.php).
3. Have one or more users returned from the [`Events::__users()` function](https://github.com/Pixwel/platform/blob/2.x/api/models/Events.php)
4. Each matching user gets a flag set. If not users match, no flags set.

## Serving flags to the user

There is a [Flags proxy](https://github.com/Pixwel/platform/blob/2.x/api/proxies/Flags.php). If a controller wants to embed flags, it can do something like:

```php theme={null}
class Projects extends Base {
	protected $_proxies = [
		// ...
		'Flags'  => ['project'],
		// ...
	];
```

This tells it what to check for - `project` for project flags, `file` for file flags, etc.

## Troubleshooting

We have historically had many issues with this system.

Places to look:

1. Are flags being set by events?
2. Are the flags set for all the users they are supposed to be?
3. Have users somehow cleared flags?
4. I don't *think* they can do this, but...
5. Is an event being created?
6. At the time of writing, there is no event for project update, for example, in [Events::\$\_rules](https://github.com/Pixwel/platform/blob/2.x/api/models/Events.php)
7. Is there a collector in [`CatalogFlags::collect()` function](https://github.com/Pixwel/platform/blob/2.x/api/models/CatalogFlags.php) for the event?
8. Maybe if there are more than `X` users it fails?
9. When the events are created, is the date being set correctly?
10. See [the mongo docs on `expireAfterSeconds`](https://docs.mongodb.org/manual/tutorial/expire-data/)

# Specific test scripts

## Testing asset updates (Events::ASSET\_UPDATE)

TODO how in the heck does this work?????!!!!

***

[Back to docs index](/) | [Next page in recommended reading order >>](/email)