Chatify

https://github.com/munafio/chatify
Admin
Chatify is a Laravel package that provides a complete real-time one-to-one messaging system with...
Tokens:120,871
Snippets:798
Trust Score:7.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### AttachmentService usage example

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-core.md

Usage example: resolve the service via the container, check if a file exists on disk using downloadPath (null means missing), and copy an album's files when forwarding a message.

```php
use Chatify\Services\AttachmentService;

$svc = app(AttachmentService::class);

if ($svc->downloadPath($filename) === null) {
    // 404 path — file missing on disk
}

// Reuse an album's files when forwarding
$copy = $svc->copyMessageAttachment($original->attachment);
```

--------------------------------

### Install dependencies

Source: https://github.com/munafio/chatify/blob/main/CONTRIBUTING.md

Installs PHP dependencies with Composer and frontend dependencies with npm ci. Requires PHP 8.2+, Composer, and Node.js 20.

```bash
composer install
cd frontend && npm ci
```

--------------------------------

### Using ConversationService and model constants

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/models.md

Usage example showing how to retrieve or create the saved conversation for a user, check if it is saved, access role and type constants, and get the unread count (which is 0 for saved conversations).

```php
use Chatify\Models\Conversation;
use Chatify\Models\ConversationParticipant;
use Chatify\Models\Message;
use Chatify\Services\ConversationService;

$group = app(ConversationService::class)->findSavedForUser($user)
    ?? app(ConversationService::class)->findOrCreateSavedForUser($user);

$saved = $group->isSaved();                              // true
$role   = ConversationParticipant::ROLE_MEMBER;          // 'member'
$type   = Conversation::TYPE_SAVED;                      // 'saved'

$unread = app(MessageService::class)->unreadCount($group, (int) $user->getKey()); // 0 for saved
```

--------------------------------

### GET /settings

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Retrieves the authenticated user's settings.

```APIDOC
## GET /settings

### Description
Retrieves the authenticated user's settings.

### Method
GET

### Endpoint
`/settings`

### Response
#### Success Response (200)
- **data** (object) - User settings.
```

--------------------------------

### GET /link-preview

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Fetches a link preview for a given URL.

```APIDOC
## GET /link-preview

### Description
Fetches a link preview for a given URL. Validates the URL and rejects non-http(s) schemes, localhost, and private IPs.

### Method
GET

### Endpoint
`/link-preview`

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to preview. Must be a valid URL with http or https scheme, max length 2048.

### Response
#### Success Response (200)
- **data** (object) - The link preview data.

#### Error Response (422)
- **message** (string) - `only_http_https_urls`
```

--------------------------------

### SendMessageData usage example

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/data-and-support.md

Shows how to instantiate SendMessageData and pass it to MessageService::send().

```php
use Chatify\Data\SendMessageData;
use Chatify\Services\MessageService;

$message = app(MessageService::class)->send($conversation, $user, new SendMessageData(
    body: 'Hello',
    attachmentMeta: null,
    replyToMessageId: null,
));
```

--------------------------------

### GET {web prefix}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Renders the main Chatify application page.

```APIDOC
## GET {web prefix} (default /chatify)

### Description
Renders the main Chatify application page with the `chatifyBoot` JSON and asset URLs.

### Method
GET

### Endpoint
{web prefix} (default /chatify)

### Response
#### Success Response (200)
Renders `Chatify::pages.app` with `chatifyBoot` JSON and asset URLs.
```

--------------------------------

### Usage example for LinkPreviewService fetch

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-group.md

Shows how to use the LinkPreviewService via the application container to fetch a preview for a URL. The returned array contains url, title, description, and image, with title, description, and image being nullable strings.

```php
use Chatify\Services\LinkPreviewService;

$preview = app(LinkPreviewService::class)->fetch('https://example.com/article');
// ['url' => ..., 'title' => string|null, 'description' => string|null, 'image' => string|null]
```

--------------------------------

### Chatify console commands usage

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/console.md

Shows the four main Chatify console commands: install (with optional --with-ui), publish (with --force), and build. Use these to set up or update Chatify in a Laravel project.

```bash
# Typical first-time install (headless API)
php artisan chatify:install

# Install with the bundled messenger UI
php artisan chatify:install --with-ui

# Publish everything, overwriting hosted files
php artisan chatify:publish --force

# Rebuild the Vue frontend and publish compiled assets
php artisan chatify:build
```

--------------------------------

### GET / (web)

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Returns the main messenger view for the authenticated user.

```APIDOC
## GET / (web)

### Description
Returns the main messenger view for the authenticated user.

### Method
GET

### Endpoint
/ (web prefix `chatify`)

### Response
#### Success Response (200)
- **html** (string) - The messenger page.

#### Response Example
[HTML content]
```

--------------------------------

### GET /users/{user}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Retrieves a user's profile.

```APIDOC
## GET /users/{user}

### Description
Retrieves a user's profile. Returns 404 if not found.

### Method
GET

### Endpoint
/users/{user}

### Parameters
#### Path Parameters
- **user** (string) - Required - The user ID.

### Response
#### Success Response (200)
- **data** (object) - UserResource.

#### Error Responses
- **404** - User not found.

#### Response Example
{
  "data": {}
}
```

--------------------------------

### GET /users/{user}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Retrieves a user resource by ID.

```APIDOC
## GET /users/{user}

### Description
Retrieves a user resource by ID.

### Method
GET

### Endpoint
`/users/{user}`

### Parameters
#### Path Parameters
- **user** (integer) - Required - The user ID.

### Response
#### Success Response (200)
- **data** (object) - User resource.
```

--------------------------------

### GET /users/{user}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Shows a specific user.

```APIDOC
## GET /users/{user}

### Description
Shows a specific user.

### Method
GET

### Endpoint
`/users/{user}` (under API prefix)

### Parameters
#### Path Parameters
- **user** (integer) - Required - The user ID.

### Response
#### Success Response (200)
Returns the user data.
```

--------------------------------

### sendMessage basic usage via facade

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/chatify-messenger.md

Example of sending a message using the ChatifyMessenger facade after creating a direct conversation.

```php
use Chatify\Facades\ChatifyMessenger;

$conversation = ChatifyMessenger::findOrCreateDirect($userA, $userB);
$message = ChatifyMessenger::sendMessage($conversation, $userA, 'Hello!');
```

--------------------------------

### GET /blocks

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Lists blocked users.

```APIDOC
## GET /blocks

### Description
Lists blocked users.

### Method
GET

### Endpoint
`/blocks` (under API prefix)

### Parameters
None.

### Response
#### Success Response (200)
Returns a list of blocked users.
```

--------------------------------

### UpdateUserSettings usage with error handling

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/actions-settings-favorites.md

Usage example for UpdateUserSettings with error handling. It updates dark mode and theme preferences, then attempts to set a chat background, catching InvalidArgumentException for cases like wallpaper_upload_disabled, image_type_not_allowed, or image_too_large.

```php
use Chatify\Actions\Settings\UpdateUserSettings;

$action = app(UpdateUserSettings::class);

$settings = $action->handle($user, [
    'dark_mode' => true,
    'theme_preferences' => ['themeId' => 'night', 'accentColor' => '#3F51B5'],
]);

try {
    $action->handle($user, [], null, $uploadedBackground);
} catch (\InvalidArgumentException $e) {
    // wallpaper_upload_disabled | image_type_not_allowed | image_too_large
    report($e->getMessage());
}
```

--------------------------------

### findOrCreateDirect basic usage via facade

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/chatify-messenger.md

Example of using the ChatifyMessenger facade to find or create a direct conversation between two users.

```php
use Chatify\Facades\ChatifyMessenger;

$conversation = ChatifyMessenger::findOrCreateDirect($currentUser, $otherUser);
echo $conversation->id; // uuid
```

--------------------------------

### Chatify configuration overrides (config/chatify.php and env)

Source: https://github.com/munafio/chatify/blob/main/_autodocs/configuration.md

Example overrides for the Chatify configuration. The published config file (config/chatify.php) and environment variables are both read via config('chatify.*'), so either can be used. The env block shows the corresponding environment variable names for middleware, group max participants, max file size, and Giphy API key.

```php
// config/chatify.php (published)
return [
    'api' => ['prefix' => 'messaging/v1'],
    'groups' => ['max_participants' => 100],
    'web' => ['enabled' => false],
];
```

```env
// env
CHATIFY_API_MIDDLEWARE=web,auth
CHATIFY_GROUP_MAX_PARTICIPANTS=100
CHATIFY_MAX_FILE_SIZE=75
CHATIFY_GIPHY_API_KEY=giphy123
```

--------------------------------

### GET /contacts/search

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Searches contacts.

```APIDOC
## GET /contacts/search

### Description
Searches contacts.

### Method
GET

### Endpoint
`/contacts/search` (under API prefix)

### Parameters
None documented.

### Response
#### Success Response (200)
Returns search results.
```

--------------------------------

### GET /favorites

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Lists all users favorited by the authenticated user.

```APIDOC
## GET /favorites

### Description
Lists all users favorited by the authenticated user. Returns a collection of user resources.

### Method
GET

### Endpoint
`/favorites`

### Response
#### Success Response (200)
- **data** (array) - List of favorited user resources.
```

--------------------------------

### sendMessage error handling with attachment

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/chatify-messenger.md

Example of sending a message with an attachment and catching ValidationException for various errors.

```php
use Chatify\Facades\ChatifyMessenger;
use Illuminate\Validation\ValidationException;

try {
    $message = ChatifyMessenger::sendMessage($conversation, $sender, null, $uploadedFile);
} catch (ValidationException $e) {
    // Not a participant / blocked recipient / empty body
    // $e->errors() exposes the field-keyed messages
    report($e->errors());
}
```

--------------------------------

### GET /blocked-users

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Lists all users blocked by the authenticated user.

```APIDOC
## GET /blocked-users

### Description
Lists all users blocked by the authenticated user. Returns a collection of user resources and metadata about blocked user IDs.

### Method
GET

### Endpoint
`/blocked-users`

### Response
#### Success Response (200)
- **data** (array) - List of blocked user resources.
- **meta** (object) - Contains `messaging_blocked_user_ids` (array of user IDs).
```

--------------------------------

### ChatifyServiceProvider class skeleton

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/service-provider.md

The ChatifyServiceProvider class skeleton with all its public and protected methods. It is the Composer/IU service provider that installs Chatify into a host application, declared in composer.json under extra.laravel.providers.

```php
class ChatifyServiceProvider extends ServiceProvider
{
    public function register(): void { /* ... */ }
    public function boot(): void { /* ... */ }
    protected function registerPolicies(): void { /* ... */ }
    protected function registerRateLimiters(): void { /* ... */ }
    protected function registerRouteBindings(): void { /* ... */ }
    protected function loadRoutes(): void { /* ... */ }
    protected function loadBroadcastChannels(): void { /* ... */ }
    protected function setPublishes(): void { /* ... */ }
}
```

--------------------------------

### GET /translations

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Retrieves translation strings for the UI, system messages, dates, themes, wallpaper, and roles.

```APIDOC
## GET /translations

### Description
Retrieves translation strings for the UI, system messages, dates, themes, wallpaper, and roles.

### Method
GET

### Endpoint
/translations

### Response
#### Success Response (200)
- **locale** (string) - The current locale.
- **fallbackLocale** (string) - The fallback locale.
- **dir** (string) - Text direction (e.g., ltr/rtl).
- **translations** (object) - Contains keys: `ui`, `system_messages`, `dates`, `themes`, `wallpaper`, `roles`.
- **fallbackTranslations** (object|null) - Fallback translations.

#### Response Example
{
  "locale": "en",
  "fallbackLocale": "en",
  "dir": "ltr",
  "translations": {
    "ui": {},
    "system_messages": {},
    "dates": {},
    "themes": {},
    "wallpaper": {},
    "roles": {}
  },
  "fallbackTranslations": null
}
```

--------------------------------

### Using InteractsWithChatify in a User model

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/traits-contracts.md

Example of using the InteractsWithChatify trait in a User model. Shows how to add the trait, use its methods in your own methods, and call sendMessageTo, conversationWith, and participatesInConversation from application code. Note that sendMessageTo and conversationWith raise the same ValidationException cases as SendMessage and FindOrCreateDirectConversation.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Chatify\Traits\InteractsWithChatify;

class User extends Model
{
    use InteractsWithChatify;

    // ... own scopes/relations

    public function notifyOfReply()
    {
        // $this->chatifySettingsOrCreate(); $this->sentChatifyMessages();
    }
}

// In application code
$user->sendMessageTo($collaborator, 'See the design doc');
$conversation = $user->conversationWith($collaborator);
$isMember = $user->participatesInConversation($conversationId);
```

--------------------------------

### GET /translations

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Returns translation data for the current locale.

```APIDOC
## GET /translations

### Description
Returns translation data for the current locale, including locale, fallback locale, direction, and translation arrays.

### Method
GET

### Endpoint
`/translations`

### Response
#### Success Response (200)
- **locale** (string) - Current locale.
- **fallbackLocale** (string) - Fallback locale.
- **dir** (string) - Text direction (e.g., `ltr` or `rtl`).
- **translations** (object) - Translation key-value pairs.
- **fallbackTranslations** (object) - Fallback translation key-value pairs.
```

--------------------------------

### GET /conversations/{conversation}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Shows a specific conversation. Requires the `view` policy.

```APIDOC
## GET /conversations/{conversation}

### Description
Shows a specific conversation. Requires the `view` policy.

### Method
GET

### Endpoint
`/conversations/{conversation}` (under API prefix)

### Parameters
#### Path Parameters
- **conversation** (integer) - Required - The conversation ID.

### Response
#### Success Response (200)
Returns the conversation data.
```

--------------------------------

### GET conversations

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Lists conversations for the authenticated user with optional pagination.

```APIDOC
## GET conversations

### Description
Retrieves a paginated list of conversations for the authenticated user.

### Method
GET

### Endpoint
`/conversations`

### Parameters
#### Query Parameters
- **per_page** (integer) - Optional - Number of conversations per page (default: 30).

### Response
#### Success Response (200)
- **data** (array) - List of conversation resources.

#### Response Example
```json
{
  "data": []
}
```
```

--------------------------------

### findOrCreateDirect usage via container

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/chatify-messenger.md

Example of resolving ChatifyMessenger from the container and calling findOrCreateDirect.

```php
$messenger = app(ChatifyMessenger::class);
$conversation = $messenger->findOrCreateDirect($requester, $target);
```

--------------------------------

### GET /attachments/{filename}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Streams a stored attachment file as a download.

```APIDOC
## GET /attachments/{filename}

### Description
Streams a stored attachment file as a download. Resolves the basename of the filename and returns a 404 if the file is missing or not referenced by any message.

### Method
GET

### Endpoint
/attachments/{filename}

### Parameters
#### Path Parameters
- **filename** (string) - Required - The filename of the attachment.

### Response
#### Success Response (200)
Streams the stored file as a download.

#### Error Response (404)
Returned when the file is missing on disk or not referenced by any message (`file_not_found`).
```

--------------------------------

### GET /contacts/search

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Searches for users to contact, excluding blocked and self.

```APIDOC
## GET /contacts/search

### Description
Searches for users to contact. Excludes blocked users and the current user.

### Method
GET

### Endpoint
/contacts/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Must be between 1 and 100 characters.
- **per_page** (int) - Optional - Default: 30.

### Response
#### Success Response (200)
- **data** (array) - Collection of UserResource.

#### Response Example
{
  "data": []
}
```

--------------------------------

### ToggleFavorite usage

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/actions-settings-favorites.md

Usage example for ToggleFavorite. It resolves the action from the container and calls handle with the user and target, then checks the boolean result to determine if the favorite was created or removed.

```php
use Chatify\Actions\Favorites\ToggleFavorite;

$favorited = app(ToggleFavorite::class)->handle($user, $contact);
// $favorited === true  → now favorited
// $favorited === false → unfavorited
```

--------------------------------

### UserTyping

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/events.md

Event dispatched when a user starts or stops typing in a conversation. It carries the conversation ID, user ID, and typing status.

```APIDOC
## UserTyping

### Description
Dispatched when a user starts or stops typing in a conversation. It carries the conversation ID, user ID, and typing status.

### Constructor / Dispatch Parameters
- **conversationId** (string) - Required - The ID of the conversation.
- **userId** (int) - Required - The ID of the user typing.
- **isTyping** (bool) - Required - Whether the user is typing.

### Usage Example
```php
UserTyping::dispatch($conversationId, $userId, $isTyping);
```
```

--------------------------------

### GET /{conversationId} (web)

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Returns the messenger view for a specific conversation.

```APIDOC
## GET /{conversationId} (web)

### Description
Returns the messenger view for a specific conversation.

### Method
GET

### Endpoint
/{conversationId} (uuid)

### Parameters
#### Path Parameters
- **conversationId** (uuid) - Required - The conversation ID.

### Response
#### Success Response (200)
- **html** (string) - The messenger page.

#### Response Example
[HTML content]
```

--------------------------------

### GET /attachments/{filename}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Downloads an attachment. Requires `view` policy on the message owning the file.

```APIDOC
## GET /attachments/{filename}

### Description
Downloads an attachment. Requires `view` policy on the message owning the file.

### Method
GET

### Endpoint
/attachments/{filename}

### Parameters
#### Path Parameters
- **filename** (string) - Required - The attachment filename.

### Response
#### Success Response (200)
- **file** (binary) - The attachment file.

#### Response Example
[Binary file content]
```

--------------------------------

### GET {web prefix}/{conversationId}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Renders the Chatify application page with a specific conversation ID.

```APIDOC
## GET {web prefix}/{conversationId}

### Description
Renders the Chatify application page with a specific conversation ID set in the `chatifyBoot` JSON.

### Method
GET

### Endpoint
{web prefix}/{conversationId}

### Parameters
#### Path Parameters
- **conversationId** (uuid) - Required - The conversation ID. Must be a valid UUID, otherwise a 404 is returned.

### Response
#### Success Response (200)
Renders the same view as the index page with `chatifyBoot.conversationId` set.

#### Error Response (404)
Returned for non-uuid values.
```

--------------------------------

### Run tests and build

Source: https://github.com/munafio/chatify/blob/main/CONTRIBUTING.md

Runs the PHP test suite with PHPUnit, the frontend tests with Vitest, and the frontend typecheck plus production build. These commands are used to verify changes locally.

```bash
# PHP (PHPUnit)
composer test

# Frontend (Vitest)
cd frontend && npm test

# Frontend typecheck + production build
cd frontend && npm run build
```

--------------------------------

### Rebuild and commit dist/

Source: https://github.com/munafio/chatify/blob/main/CONTRIBUTING.md

Rebuilds the frontend and stages the dist/ directory. Required when changing files under frontend/src/; CI fails if committed dist/ does not match a fresh build.

```bash
cd frontend && npm run build
git add dist/
```

--------------------------------

### Tag a beta release

Source: https://github.com/munafio/chatify/blob/main/CONTRIBUTING.md

Creates an annotated tag for a beta release. Replace the version with the actual release version.

```bash
git tag -a v2.0.0-beta.3 -m "Chatify v2.0.0-beta.3"
```

--------------------------------

### LinkPreviewService class with fetch method and constants

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-group.md

Defines the LinkPreviewService class with a fetch method that returns an array with url, title, description, and image. Titles and descriptions are sourced from Open Graph, then Twitter, then HTML title/meta description. HTML beyond 512 KB is truncated, relative image URLs are resolved against the origin, non-2xx responses yield an all-null preview, and a 5s timeout with a 'Chatify Link Preview' user-agent is used.

```php
final class LinkPreviewService
{
    private const TIMEOUT_SECONDS = 5;
    private const MAX_BYTES = 524288;

    public function fetch(string $url): array
}
```

--------------------------------

### Send message with reply and album, then forward

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/actions-messages.md

Shows a full send with reply and album using SendMessage::handle, catching ValidationException for errors on 'conversation', 'recipient', 'body', or 'reply_to_message_id'. Also demonstrates forwarding a previous message with ForwardMessage::handle.

```php
use Chatify\Actions\Messages\SendMessage;
use Illuminate\Validation\ValidationException;

$send = app(SendMessage::class);

try {
    $message = $send->handle(
        $conversation,
        $currentUser,
        'See the attached',
        null,                    // single attachment
        [$fileA, $fileB],        // album (2+ files stored as album
        $replyToId,              // reply
        null,
    );
} catch (ValidationException $e) {
    // $e->errors(): 'conversation' | 'recipient' | 'body' | 'reply_to_message_id'
}

// Forward a previous message
$forwarded = app(ForwardMessage::class)->handle($targetGroup, $originalMessage, $currentUser);
```

--------------------------------

### storage

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-core.md

Returns the configured storage disk for chatify.

```APIDOC
## storage

### Description
Returns the storage disk instance configured for chatify.

### Method
storage

### Returns
- **Storage** - The storage disk (`Storage::disk(chatify.storage_disk_name)`).

### Example
```php
$disk = $svc->storage();
```
```

--------------------------------

### Usage of ChatifyModels::userClass()

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/data-and-support.md

Shows how to use ChatifyModels to fetch a user by ID using the configured user model class.

```php
use Chatify\Support\ChatifyModels;

$user = ChatifyModels::userClass()::query()->findOrFail($id);
```

--------------------------------

### UserSettingsService class with forUser and update methods

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-people.md

Defines the UserSettingsService class with a constructor injecting AttachmentService and two public methods: forUser and update. forUser firstOrCreates the settings row with defaults (avatar = avatar.png, dark_mode = false, messenger_color = defaultColor() = first configured color or #2180f3, active_status = true). update applies merge semantics and may throw \InvalidArgumentException via ThemePreferencesValidator::validate.

```php
final class UserSettingsService
{
    public function __construct(private readonly AttachmentService $attachmentService) { }

    public function forUser(Model $user): UserSetting
    public function update(Model $user, array $attributes, ?UploadedFile $avatar = null, ?UploadedFile $chatBackground = null): UserSetting
}
```

--------------------------------

### PresenceService class skeleton with heartbeat, markOffline, and visibility methods

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-people.md

Class skeleton for Chatify's presence service. The heartbeat method stores a timestamp in the cache key `chatify:presence:<id>` with a 45-second TTL and broadcasts `UserPresenceChanged` on offline-to-online transitions, unless the user's settings hide online status, in which case it calls `markOffline(broadcast: true)` and returns false. `markOffline` forgets the cache entry and broadcasts offline only if the user was online and shows status. `canViewPresence` returns true only when both users show online status, and `visibleIsOnline` returns null when `canViewPresence` is false, otherwise it returns `isOnline(target)`.

```php
final class PresenceService
{
    private const CACHE_PREFIX = 'chatify:presence:';
    private const TTL_SECONDS = 45;

    public function __construct(private readonly UserSettingsService $userSettingsService) { }

    public function heartbeat(Model $user): bool
    public function markOffline(Model $user, bool $broadcast = true): void
    public function isOnline(int $userId): bool
    public function showsOnlineStatus(Model $user): bool
    public function canViewPresence(Model $viewer, Model $target): bool
    public function visibleIsOnline(Model $viewer, Model $target): ?bool
    public function audienceUserIds(int $userId): array   // @return list<int>
}
```

--------------------------------

### Custom endpoint returning a raw resource

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/http-resources.md

Shows how to use a resource in a custom endpoint. It fetches the latest message and returns the resolved resource or null if no message exists.

```php
use Chatify\Http\Resources\MessageResource;

public function latestMessage()
{
    $message = Message::query()->latest()->first();

    return $message !== null ? (new MessageResource($message))->resolve() : null;
}
```

--------------------------------

### GET conversations/{conversation}/messages

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Retrieves a paginated list of messages for a conversation.

```APIDOC
## GET conversations/{conversation}/messages

### Description
Retrieves a paginated list of messages for a conversation.

### Method
GET

### Endpoint
`/conversations/{conversation}/messages`

### Parameters
#### Path Parameters
- **conversation** (integer) - Required - The conversation ID.

#### Query Parameters
- **per_page** (integer) - Optional - Number of messages per page (default: 30).
- **after** (string) - Optional - Cursor for pagination.

### Response
#### Success Response (200)
- **data** (array) - List of message resources.

#### Response Example
```json
{
  "data": []
}
```
```

--------------------------------

### UserSetting model with custom primary key and fillable attributes

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/models.md

Defines the UserSetting model for user preferences. Uses 'user_id' as primary key with non-incrementing IDs. The fillable fields include avatar, dark_mode, messenger_color, theme_preferences, chat_background, and active_status. The default active_status is true. The tableConfigKey method returns 'user_settings'.

```php
class UserSetting extends ChatifyModel
{
    protected $table = 'ch_user_settings';
    protected $primaryKey = 'user_id';
    public $incrementing = false;
    protected $fillable = ['user_id', 'avatar', 'dark_mode', 'messenger_color', 'theme_preferences', 'chat_background', 'active_status'];
    protected $attributes = ['active_status' => true];
    protected function tableConfigKey(): ?string { return 'user_settings'; }

    public function user(): BelongsTo
}
```

--------------------------------

### GET conversations/{conversation}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Retrieves a single conversation with its participants, creator, and latest message.

```APIDOC
## GET conversations/{conversation}

### Description
Retrieves a single conversation with its participants, creator, and latest message.

### Method
GET

### Endpoint
`/conversations/{conversation}`

### Parameters
#### Path Parameters
- **conversation** (integer) - Required - The conversation ID.

### Response
#### Success Response (200)
- **data** (object) - The conversation resource.

#### Response Example
```json
{
  "data": {}
}
```
```

--------------------------------

### UpdateUserSettings::handle

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/actions-settings-favorites.md

Action class for updating user settings including profile and chat preferences.

```APIDOC
## UpdateUserSettings::handle

### Description
Updates user settings including dark mode, active status, messenger color, theme preferences, avatar, and chat background. Returns the updated or created `UserSetting` model.

### Method
handle

### Signature
`public function handle(Model $user, array $attributes, ?UploadedFile $avatar = null, ?UploadedFile $chatBackground = null): UserSetting`

### Parameters
- **user** (`Model`) - Required - The user whose settings are updated
- **attributes** (`array`) - Required - Recognized keys: `dark_mode` (bool), `active_status` (bool), `messenger_color`, `theme_preferences` (array), `reset_avatar` (truthy)
- **avatar** (`?UploadedFile`) - Optional, default `null` - New avatar image (must be png/jpg/jpeg/gif; `InvalidArgumentException` otherwise)
- **chatBackground** (`?UploadedFile`) - Optional, default `null` - New chat background image; throws `\InvalidArgumentException` (`wallpaper_upload_disabled`) when `chatify.chat_background.enabled` is false

### Return Value
`Chatify\Models\UserSetting` - Fresh settings row (created on demand, `firstOrCreate`).

### Behavior
- Stores avatar/background uploads and deletes previous custom files.
- `dark_mode` and `active_status` are cast to `bool`; disabling `active_status` calls `PresenceService::markOffline($user)`.
- `theme_preferences` passes through `ThemePreferencesValidator::validate()` (throws `\InvalidArgumentException` on invalid input) and is merged recursively into existing preferences; an `accentColor` propagates to `messenger_color`, a `themeId` of `night`/`tinted` sets `dark_mode = true`.
- `reset_avatar` truthy → avatar reset to `chatify.user_avatar.default` (`avatar.png`) after deleting a custom file.

### Usage Example
```php
use Chatify\Actions\Settings\UpdateUserSettings;

$action = app(UpdateUserSettings::class);

$settings = $action->handle($user, [
    'dark_mode' => true,
    'theme_preferences' => ['themeId' => 'night', 'accentColor' => '#3F51B5'],
]);

try {
    $action->handle($user, [], null, $uploadedBackground);
} catch (\InvalidArgumentException $e) {
    // wallpaper_upload_disabled | image_type_not_allowed | image_too_large
    report($e->getMessage());
}
```
```

--------------------------------

### downloadPath

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-core.md

Provides a download path for a file, returning null if the file is not present.

```APIDOC
## downloadPath

### Description
Returns the existence-checked download path for a file, or `null` if the file is missing on disk.

### Method
downloadPath

### Parameters
- **filename** (string) - Required - The stored filename.

### Returns
- **?string** - Download path or `null` if file does not exist.

### Example
```php
if ($svc->downloadPath($filename) === null) {
    // 404 path — file missing on disk
}
```
```

--------------------------------

### GET /conversations/{conversation}/participants

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Lists participants of a group conversation. Returns a paginated list of participants.

```APIDOC
## GET /conversations/{conversation}/participants

### Description
Lists participants of a group conversation. Returns a paginated list of participants.

### Method
GET

### Endpoint
`/conversations/{conversation}/participants`

### Parameters
#### Path Parameters
- **conversation** (integer) - Required - The conversation ID.

#### Query Parameters
- **per_page** (integer) - Optional - Number of items per page (default 20).
- **search** (string) - Optional - Search term to filter participants.

### Response
#### Success Response (200)
- **data** (array) - List of participant resources.
- **meta** (object) - Pagination metadata.

#### Error Response (404)
- **message** (string) - Not a group conversation.
```

--------------------------------

### GET conversations/{conversation}/messages/search

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Searches messages within a conversation. Requires a minimum query length of 2.

```APIDOC
## GET conversations/{conversation}/messages/search

### Description
Searches messages within a conversation. Requires a minimum query length of 2.

### Method
GET

### Endpoint
`/conversations/{conversation}/messages/search`

### Parameters
#### Path Parameters
- **conversation** (integer) - Required - The conversation ID.

#### Query Parameters
- **q** (string) - Required - Search query (minimum length 2).
- **per_page** (integer) - Optional - Number of results per page (default: 20).
- **page** (integer) - Optional - Page number (default: 1).

### Response
#### Success Response (200)
- **data** (array) - List of matching message resources.

#### Response Example
```json
{
  "data": []
}
```
```

--------------------------------

### url

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-core.md

Generates a storage URL for a file.

```APIDOC
## url

### Description
Builds a storage URL for a given filename.

### Method
url

### Parameters
- **filename** (string) - Required - The stored filename.

### Returns
- **string** - The storage URL.

### Example
```php
$url = $svc->url($filename);
```
```

--------------------------------

### SetLocaleFromRequest middleware class and handle method

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Middleware class SetLocaleFromRequest with its handle method signature. Prepended to the API middleware chain when chatify.locale.middleware is true. Resolution order chatify.locale.detect_via (default ['header', 'query', 'user', 'app']): header uses X-Chatify-Locale (fallback_header) first, else first language tag of Accept-Language; query uses ?locale= (query_parameter); user uses user.locale attribute (user_attribute); app uses app()->getLocale(). Non-null results are normalized (ar_EG → ar); the app locale is switched before the request continues.

```php
final class SetLocaleFromRequest
{
    public function handle(Request $request, Closure $next): Response
}
```

--------------------------------

### LinkPreviewService

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-group.md

Service for fetching link preview metadata from URLs.

```APIDOC
## fetch

### Description
Fetches link preview metadata (title, description, image) for a given URL. Uses Open Graph, Twitter Card, and HTML meta tags as fallbacks. Returns an array with `url`, `title`, `description`, and `image` fields.

### Method
fetch

### Signature
`public function fetch(string $url): array`

### Parameters
- **url** (string) - Required - The URL to fetch preview data for.

### Return Value
Returns an array with keys: `url`, `title`, `description`, `image`. Values may be `null` if not found.

### Behavior
- Extracts metadata from Open Graph (`og:title`, `og:description`, `og:image`), then Twitter (`twitter:title`, `twitter:description`, `twitter:image`), then `<title>` and meta `description`.
- Truncates HTML beyond 512 KB.
- Resolves relative image URLs against the origin.
- Returns all-`null` preview for non-2xx responses.
- Uses a 5-second timeout and a `Chatify Link Preview` user-agent.

### Usage Example
```php
use Chatify\Services\LinkPreviewService;

$preview = app(LinkPreviewService::class)->fetch('https://example.com/article');
// ['url' => ..., 'title' => string|null, 'description' => string|null, 'image' => string|null]
```
```

--------------------------------

### GET /attachments/{filename}/download

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Downloads an attachment file by its filename. Returns a streamed file response or a 404 error if the file is missing.

```APIDOC
## GET /attachments/{filename}/download

### Description
Downloads an attachment file by its filename. The filename is sanitized using `basename`. Returns a streamed file response or a 404 error if the file is missing on disk or not referenced by any message.

### Method
GET

### Endpoint
`/attachments/{filename}/download`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The attachment filename.

### Response
#### Success Response (200)
- Streamed file content.

#### Error Response (404)
- **message** (string) - `file_not_found`
```

--------------------------------

### Push beta release tag

Source: https://github.com/munafio/chatify/blob/main/CONTRIBUTING.md

Pushes the beta release tag to the remote repository. Used after tagging to trigger Packagist pickup.

```bash
git push origin v2.0.0-beta.3
```

--------------------------------

### storeChatBackground

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-core.md

Stores an image as a chat background and returns the stored filename.

```APIDOC
## storeChatBackground

### Description
Stores an image file as a chat background in the `chat-backgrounds` folder and returns the stored filename.

### Method
storeChatBackground

### Parameters
- **file** (UploadedFile) - Required - The image file to store.

### Returns
- **array** - `{ stored_name }`.

### Throws
- `\InvalidArgumentException` - `image_type_not_allowed` or `image_too_large`.

### Example
```php
$result = $svc->storeChatBackground($file);
```
```

--------------------------------

### GET /conversations/{conversation}/attachments

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Retrieves attachments for a conversation. Supports pagination and filtering by type (media, docs, links) or returns recent shared photos.

```APIDOC
## GET /conversations/{conversation}/attachments

### Description
Retrieves attachments for a conversation. When `type` or `page` query parameters are present, returns paginated media, docs, or links. Otherwise, returns recent shared photos.

### Method
GET

### Endpoint
`/conversations/{conversation}/attachments`

### Parameters
#### Path Parameters
- **conversation** (integer) - Required - The conversation ID.

#### Query Parameters
- **type** (string) - Optional - Filter by attachment type: `media`, `docs`, or `links`.
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page.

### Response
#### Success Response (200)
- **data** (array) - List of attachment resources.
- **meta** (object) - Pagination metadata: `total`, `current_page`, `last_page`, `per_page`, `total_all`.

#### Response Example
{
  "data": [],
  "meta": {
    "total": 0,
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total_all": 0
  }
}
```

--------------------------------

### chatBackgroundUrl

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-core.md

Generates the storage URL for a chat background file.

```APIDOC
## chatBackgroundUrl

### Description
Returns the storage URL for a chat background filename, or `null` if not available.

### Method
chatBackgroundUrl

### Parameters
- **filename** (?string) - Required - The stored background filename.

### Returns
- **?string** - Storage URL or `null`.

### Example
```php
$url = $svc->chatBackgroundUrl($filename);
```
```

--------------------------------

### POST conversations/direct

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Creates a direct conversation with another user. Returns 201 on success.

```APIDOC
## POST conversations/direct

### Description
Creates a direct conversation between the authenticated user and another user. Returns 201 on success.

### Method
POST

### Endpoint
`/conversations/direct`

### Parameters
#### Request Body
- **user_id** (integer) - Required - The ID of the other user.

### Response
#### Success Response (201)
- **data** (object) - The created conversation resource.

#### Response Example
```json
{
  "data": {}
}
```
```

--------------------------------

### Overriding RecipientResolver with a custom policy

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/traits-contracts.md

Example of overriding the RecipientResolver binding with a custom policy class. The custom class must implement canMessage() with your rules; SendMessage will consult it for every direct-chat send.

```php
// config/app.php or a provider
app()->bind(RecipientResolver::class, CorporateMessagingPolicy::class);

// CorporateMessagingPolicy implements canMessage() with your rules;
// SendMessage will consult it for every direct-chat send.
```

--------------------------------

### SendMessage action class with handle() method

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/actions-messages.md

Final action class for sending a message. The handle() method accepts the conversation, sender, body, optional single or multiple attachments, reply/forward IDs, and prebuilt attachment metadata. It returns a Message loaded with sender, replyTo.sender, and forwardedFrom.sender. The constructor injects MessageService, ConversationService, AttachmentService, RecipientResolver, and InboxBroadcastService.

```php
final class SendMessage
{
    public function __construct(
        private readonly MessageService $messageService,
        private readonly ConversationService $conversationService,
        private readonly AttachmentService $attachmentService,
        private readonly RecipientResolver $recipientResolver,
        private readonly InboxBroadcastService $inboxBroadcastService,
    ) {}

    public function handle(
        Conversation $conversation,
        Model $sender,
        ?string $body,
        ?UploadedFile $attachment = null,
        array $attachments = [],
        ?string $replyToMessageId = null,
        ?string $forwardedFromMessageId = null,
        ?array $prebuiltAttachmentMeta = null,
    ): Message
}
```

--------------------------------

### InteractsWithChatify trait: method signatures

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/traits-contracts.md

Trait to add to your User model to get instance methods and relations. Provides methods for settings, participants, conversations, messages, and direct messaging. Per InstallCommand output: "Add `Chatify\Traits\InteractsWithChatify` to your User model."

```php
trait InteractsWithChatify
{
    public function chatifySettings(): HasOne
    public function conversationParticipants(): HasMany
    public function chatifyConversations(): BelongsToMany
    public function sentChatifyMessages(): HasMany
    public function chatifySettingsOrCreate(): UserSetting
    public function conversationWith(self $other): Conversation
    public function sendMessageTo(self $recipient, ?string $body = null, ?UploadedFile $attachment = null): Message
    public function participatesInConversation(string $conversationId): bool
}
```

--------------------------------

### ConversationPinService class with setPinned and reorderPinned methods

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/services-group.md

Defines the public API of the ConversationPinService. setPinned writes is_pinned = true and pin_order = nextPinOrder(user) when pinning, or clears both when unpinning, and returns the fresh participant. reorderPinned sets pin_order = index for each id, requiring the submitted id set to exactly match the user's currently pinned conversation ids. Throws ValidationException with codes 'saved_messages_cannot_be_pinned', 'not_participant', 'pin_order_must_include_all', and 'only_pinned_can_be_reordered'.

```php
final class ConversationPinService
{
    public function setPinned(Conversation $conversation, Model $user, bool $pinned): ConversationParticipant
    public function reorderPinned(Model $user, array $conversationIds): void
}
```

--------------------------------

### POST /settings/chat-background

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/controllers.md

Updates the authenticated user's chat background.

```APIDOC
## POST /settings/chat-background

### Description
Updates the authenticated user's chat background.

### Method
POST

### Endpoint
`/settings/chat-background`

### Parameters
#### Request Body
- **chat_background** (file) - Required - Chat background image file.

### Response
#### Success Response (200)
- **data** (object) - Updated user settings.
```

--------------------------------

### POST /broadcasting/auth

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Handles the broadcast server authentication handshake.

```APIDOC
## POST /broadcasting/auth

### Description
Handles the broadcast server authentication handshake. Consult your broadcast adapter's response contract for the expected response format.

### Method
POST

### Endpoint
/broadcasting/auth

### Response
#### Success Response
Returns the broadcast authentication response as defined by the broadcast adapter.
```

--------------------------------

### UpdateUserSettings class signature

Source: https://github.com/munafio/chatify/blob/main/_autodocs/api-reference/actions-settings-favorites.md

Class signature for the UpdateUserSettings action. It injects UserSettingsService and exposes a handle method that updates user settings with optional avatar and chat background uploads, returning a UserSetting model.

```php
final class UpdateUserSettings
{
    public function __construct(private readonly UserSettingsService $userSettingsService) {}

    public function handle(
        Model $user,
        array $attributes,
        ?UploadedFile $avatar = null,
        ?UploadedFile $chatBackground = null,
    ): UserSetting
}
```

--------------------------------

### POST /favorites/{user}

Source: https://github.com/munafio/chatify/blob/main/_autodocs/endpoints.md

Adds a user to favorites.

```APIDOC
## POST /favorites/{user}

### Description
Adds a user to the current user's favorites. Cannot favorite self.

### Method
POST

### Endpoint
/favorites/{user}

### Parameters
#### Path Parameters
- **user** (string) - Required - The user ID.

### Response
#### Success Response (200)
- **data** (object) - Contains `favorited` (boolean).

#### Error Responses
- **422** - cannot_favorite_self.

#### Response Example
{
  "data": {
    "favorited": true
  }
}
```
Tokens:
Raw