# Bookmarks

## Overview

The API includes built-in support for bookmarking activities. Here's a quick example of how to use the bookmark API.

### Adding Bookmarks

```php label="PHP"
// Adding a bookmark to a new folder
$response = $feedsClient->addBookmark(
    'activity_123',
    new GeneratedModels\AddBookmarkRequest(
        userID: 'user_123',
        newFolder: new GeneratedModels\AddFolderRequest(name: 'New folder name')
    )
);

// Adding to an existing folder
$response = $feedsClient->addBookmark(
    'activity_123',
    new GeneratedModels\AddBookmarkRequest(
        userID: 'user_123',
        folderID: 'folder_456'
    )
);

// Update a bookmark (without a folder initially) - add custom data and move it to a new folder
$response = $feedsClient->updateBookmark(
    'activity_123',
    new GeneratedModels\UpdateBookmarkRequest(
        userID: 'user_123',
        custom: (object)['color' => 'blue'],
        newFolder: new GeneratedModels\AddFolderRequest(
            name: 'New folder name',
            custom: (object)['icon' => '📁']
        )
    )
);

// Update a bookmark - move it from one existing folder to another existing folder
$response = $feedsClient->updateBookmark(
    'activity_123',
    new GeneratedModels\UpdateBookmarkRequest(
        userID: 'user_123',
        folderID: 'folder_456',
        newFolderID: 'folder_789'
    )
);
```

### Removing Bookmarks

```php label="PHP"
// Removing a bookmark
$response = $feedsClient->deleteBookmark(
    'activity_123',
    'folder_456',
    'user_123'
);

// When you read a feed we include the bookmark
$feedResponse = $feedsClient->getOrCreateFeed('user', 'user_123', new GeneratedModels\GetOrCreateFeedRequest(
  userID: 'user_123'
));
$activities = $feedResponse->getData()->activities;
echo json_encode($activities[0]->ownBookmarks);
echo $activities[0]->bookmarkCount;
```

### Querying Bookmarks

```php label="PHP"
// Query bookmarks
$firstPage = $feedsClient->queryBookmarks(
    new GeneratedModels\QueryBookmarksRequest(
        limit: 2,
        filter: (object)['user_id' => 'user_123']
    )
);

// Get next page
$secondPage = $feedsClient->queryBookmarks(
    new GeneratedModels\QueryBookmarksRequest(
        limit: 2,
        next: $firstPage->getData()->next,
        filter: (object)['user_id' => 'user_123']
    )
);

// Query by activity ID
$response = $feedsClient->queryBookmarks(
    new GeneratedModels\QueryBookmarksRequest(
        filter: (object)[
            'user_id' => 'user_123',
            'activity_id' => 'activity_123'
        ]
    )
);

// Query by folder ID
$response = $feedsClient->queryBookmarks(
    new GeneratedModels\QueryBookmarksRequest(
        filter: (object)[
            'user_id' => 'user_123',
            'folder_id' => 'folder_456'
        ]
    )
);
```

#### Bookmarks Queryable Built-In Fields

| name          | type                                              | description                                  | supported operations                | example                                               |
| ------------- | ------------------------------------------------- | -------------------------------------------- | ----------------------------------- | ----------------------------------------------------- |
| `user_id`     | string or list of strings                         | The ID of the user who owns the bookmark     | `$in`, `$eq`                        | `{ user_id: { $eq: 'user_123' } }`                    |
| `activity_id` | string or list of strings                         | The ID of the activity that was bookmarked   | `$in`, `$eq`                        | `{ activity_id: { $eq: 'activity_123' } }`            |
| `folder_id`   | string or list of strings                         | The ID of the folder containing the bookmark | `$eq`, `$in`, `$exists`             | `{ folder_id: { $exists: true } }`                    |
| `created_at`  | string, must be formatted as an RFC3339 timestamp | The time the bookmark was created            | `$eq`, `$gt`, `$gte`, `$lt`, `$lte` | `{ created_at: { $gte: '2023-12-04T09:30:20.45Z' } }` |
| `updated_at`  | string, must be formatted as an RFC3339 timestamp | The time the bookmark was last updated       | `$eq`, `$gt`, `$gte`, `$lt`, `$lte` | `{ updated_at: { $gte: '2023-12-04T09:30:20.45Z' } }` |

### Querying Bookmark Folders

```php label="PHP"
// Query bookmark folders
$firstPage = $feedsClient->queryBookmarkFolders(
    new GeneratedModels\QueryBookmarkFoldersRequest(
        limit: 2,
        filter: (object)['user_id' => 'user_123']
    )
);

// Get next page
$secondPage = $feedsClient->queryBookmarkFolders(
    new GeneratedModels\QueryBookmarkFoldersRequest(
        limit: 2,
        next: $firstPage->getData()->next,
        filter: (object)['user_id' => 'user_123']
    )
);

// Query by folder name (partial matching)
$response = $feedsClient->queryBookmarkFolders(
    new GeneratedModels\QueryBookmarkFoldersRequest(
        filter: (object)[
            'user_id' => 'user_123',
            'folder_name' => [
                '$contains' => 'project'
            ]
        ],
        limit: 2
    )
);
```

#### Bookmark Folders Queryable Built-In Fields

| name          | type                                              | description                            | supported operations                | example                                               |
| ------------- | ------------------------------------------------- | -------------------------------------- | ----------------------------------- | ----------------------------------------------------- |
| `user_id`     | string or list of strings                         | The ID of the user who owns the folder | `$in`, `$eq`                        | `{ user_id: { $eq: 'user_123' } }`                    |
| `folder_name` | string or list of strings                         | The name of the bookmark folder        | `$eq`, `$in`, `$contains`           | `{ folder_name: { $contains: 'work' } }`              |
| `created_at`  | string, must be formatted as an RFC3339 timestamp | The time the folder was created        | `$eq`, `$gt`, `$gte`, `$lt`, `$lte` | `{ created_at: { $gte: '2023-12-04T09:30:20.45Z' } }` |
| `updated_at`  | string, must be formatted as an RFC3339 timestamp | The time the folder was last updated   | `$eq`, `$gt`, `$gte`, `$lt`, `$lte` | `{ updated_at: { $gte: '2023-12-04T09:30:20.45Z' } }` |

### Managing Bookmark Folders

#### Update bookmark folder

The endpoint performs a partial update: only the fields you include in the request are changed, and each of those fields is completely overwritten.

Updating a bookmark folder sends `feeds.bookmark_folder.updated` event to the clients of the user who owns the folder. There are no default client-side SDK handlers for this event, but you can add a custom handler if your UI needs to be updated.

#### Delete bookmark folder

Use the delete bookmark folder endpoint to remove a folder by ID. All bookmarks in that folder are removed.

Deleting a bookmark folder sends `feeds.bookmark_folder.deleted` event to the clients of the user who owns the folder. There are no default client-side SDK handlers for this event, but you can add a custom handler if your UI needs to be updated.

```php label="PHP"
// Add a bookmark with a new folder
$addResponse = $feedsClient->addBookmark(
    $activityId,
    new GeneratedModels\AddBookmarkRequest(
        userID: 'user_123',
        newFolder: new GeneratedModels\AddFolderRequest(
            name: 'Breakfast recipes',
            custom: (object)['icon' => '🍳']
        )
    )
);
$folderId = $addResponse->getData()->bookmark->folder->id;

// Update the folder
$updateResponse = $feedsClient->updateBookmarkFolder(
    $folderId,
    new GeneratedModels\UpdateBookmarkFolderRequest(
        name: 'Sweet Breakfast Recipes',
        custom: (object)['icon' => '🥞']
    )
);

// Delete the folder (and all bookmarks in it)
$feedsClient->deleteBookmarkFolder($updateResponse->getData()->bookmarkFolder->id);
```

---

For the most recent version of this documentation, visit [https://getstream.io/activity-feeds/docs/php/bookmarks/](https://getstream.io/activity-feeds/docs/php/bookmarks/).