Skip to content

Commit dd477c1

Browse files
loxKloxK
committed
Rewrite README for v5.x with full feature documentation
1 parent c86f386 commit dd477c1

1 file changed

Lines changed: 186 additions & 66 deletions

File tree

‎README.md‎

Lines changed: 186 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,209 @@
1-
# ident_switch
2-
ident_switch plugin for Roundcube
1+
# Ultimate Identity Switcher for Roundcube
32

4-
This plugin allows users to switch between different accounts (including remote) in single Roundcube session like this:
3+
[![Version](https://img.shields.io/github/v/release/Gecka-Apps/roundcube-ident_switch?label=version)](https://github.com/Gecka-Apps/roundcube-ident_switch/releases)
4+
[![PHP CodeSniffer](https://github.com/Gecka-Apps/roundcube-ident_switch/actions/workflows/phpcs.yml/badge.svg)](https://github.com/Gecka-Apps/roundcube-ident_switch/actions/workflows/phpcs.yml)
5+
[![PHP Lint](https://github.com/Gecka-Apps/roundcube-ident_switch/actions/workflows/php-lint.yml/badge.svg)](https://github.com/Gecka-Apps/roundcube-ident_switch/actions/workflows/php-lint.yml)
6+
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
7+
[![PHP](https://img.shields.io/badge/PHP-8.2+-777BB4)](https://www.php.net)
8+
[![Roundcube](https://img.shields.io/badge/Roundcube-1.6+-37BEFF)](https://roundcube.net)
59

6-
![Screenshot example](https://i.imgur.com/rRIqtA8.jpg)
10+
Switch between multiple IMAP accounts within a single Roundcube session.
711

8-
*Inspired by identities_imap plugin that is no longer supported.*
12+
## About
913

10-
### Installation ###
14+
**ident_switch** is a Roundcube plugin that turns identities into full account shortcuts. Configure each identity with its own IMAP, SMTP and Sieve server, then switch between accounts with a single click from the toolbar dropdown. Aliases, notifications, and domain preconfig are all built in.
1115

12-
#### With Composer (recommended) ####
16+
*Originally created by Boris Gulay. This fork is a major rewrite by [Gecka](https://gecka.nc) — modernized for PHP 8.2+, restructured codebase, and packed with new features: alias identities, Sieve support, background mail notifications, domain preconfig, connection testing, and per-protocol security.*
1317

14-
```sh
18+
## Features
19+
20+
### Multi-Account Switching
21+
22+
- One-click account switching from a toolbar dropdown
23+
- Each identity can be linked to a separate IMAP/SMTP server with its own credentials
24+
- Automatic special folder mapping (Sent, Drafts, Junk, Trash) per account
25+
- Encrypted password storage in database
26+
27+
### Alias Identities
28+
29+
- Link identities as aliases of any configured account (not just the primary)
30+
- Aliases share the parent account's IMAP inbox, SMTP and Sieve configuration
31+
- Compose "From" dropdown automatically filtered to show only the active account and its aliases
32+
33+
### Sieve (ManageSieve) Support
34+
35+
- Per-account Sieve server configuration with independent host, port and credentials
36+
- Three authentication modes: same as IMAP, none, or custom credentials
37+
- Sieve section only appears when the `managesieve` plugin is active
38+
39+
### New Mail Notifications
40+
41+
- Background mail checking across all secondary accounts
42+
- Unread count badge in the account switcher dropdown
43+
- Per-account notification settings: favicon, sound, desktop notifications
44+
- Optional round-robin mode to reduce IMAP connections with many accounts
45+
- Integrates with Roundcube's `newmail_notifier` plugin
46+
47+
### Domain Preconfig
48+
49+
- Pre-fill server settings based on the identity's email domain
50+
- Wildcard domain support (`*`) for catch-all defaults
51+
- Lock preconfigured fields as read-only to prevent user changes
52+
- Restrict account creation to preconfigured domains only (`preconfig_only` mode)
53+
54+
### Security
55+
56+
- Per-protocol security selection: None, STARTTLS, or SSL/TLS (IMAP, SMTP, Sieve independently)
57+
- Connection testing on save (IMAP, SMTP, Sieve) to catch misconfigurations early
58+
- Passwords encrypted using Roundcube's built-in encryption
59+
- Warning displayed when selecting unencrypted connections
60+
61+
## Requirements
62+
63+
- PHP 8.2+
64+
- Roundcube 1.6+
65+
- MySQL, PostgreSQL, or SQLite
66+
67+
## Installation
68+
69+
### With Composer (recommended)
70+
71+
Navigate to your Roundcube installation directory and run:
72+
73+
```bash
1574
composer require gecka/roundcube-ident_switch
16-
bin/updatedb.sh --package=ident_switch --dir=plugins/ident_switch/SQL
1775
```
1876

19-
The plugin is automatically registered. Enable it by adding `'ident_switch'` to `$config['plugins']` in your Roundcube `config/config.inc.php`.
77+
The [roundcube/plugin-installer](https://github.com/roundcube/plugin-installer) will automatically place the plugin in the correct `plugins/` directory, initialize the database schema, and offer to enable it.
78+
79+
> **Don't have Composer?** See [getcomposer.org](https://getcomposer.org/download/) for installation instructions.
2080
21-
#### Manual ####
81+
> **Running as root on a VPS?** Roundcube files are typically owned by `www-data`. Run Composer as the web server user to avoid permission issues:
82+
> ```bash
83+
> sudo -u www-data composer require gecka/roundcube-ident_switch
84+
> ```
85+
86+
### Manual
87+
88+
1. Place this plugin folder into the plugins directory of Roundcube:
89+
```bash
90+
cd /path/to/roundcube/plugins/
91+
git clone https://github.com/Gecka-Apps/roundcube-ident_switch.git ident_switch
92+
```
93+
94+
2. Add `ident_switch` to `$config['plugins']` in your Roundcube config:
95+
```php
96+
$config['plugins'] = array('ident_switch', /* other plugins */);
97+
```
2298

23-
1. Copy or symlink the plugin to `plugins/ident_switch` in your Roundcube installation.
24-
2. Add `'ident_switch'` to the `$config['plugins']` array in your Roundcube `config/config.inc.php`.
2599
3. Initialize the database schema:
26-
```sh
27-
bin/updatedb.sh --package=ident_switch --dir=plugins/ident_switch/SQL
100+
```bash
101+
bin/updatedb.sh --package=ident_switch --dir=plugins/ident_switch/SQL
102+
```
103+
104+
## Configuration
105+
106+
Copy the sample configuration file and edit it to match your environment:
107+
108+
```bash
109+
cp plugins/ident_switch/config.inc.php.dist plugins/ident_switch/config.inc.php
28110
```
29111

30-
#### Configuration ####
112+
### Domain Preconfig
31113

32-
Optionally copy `plugins/ident_switch/config.inc.php.dist` to `plugins/ident_switch/config.inc.php` and edit it to preconfigure mail settings per domain.
114+
Pre-fill server settings per email domain so users don't have to enter them manually:
33115

34-
### Where to start ###
35-
* In settings interface create new identity.
36-
* For all identities except default you will see new section of settings - "Plugin ident_switch" (see screenshot below). Enter data required to connect to remote server. Don't forget to check Enabled check box.
37-
* After you have created at least one identity with active plugin you will see combobox in the top right corner instead of plain text field with account name. It will allows you to switch to another account.
116+
```php
117+
$config['ident_switch.preconfig'] = [
118+
'domain.tld' => [
119+
'imap_host' => 'ssl://mail.domain.tld:993',
120+
'smtp_host' => 'tls://mail.domain.tld:587',
121+
'sieve_host' => 'tls://mail.domain.tld:4190',
122+
'user' => 'email', // 'email' = full address, 'mbox' = local part
123+
'readonly' => true, // lock fields in UI
124+
],
125+
'*' => [ // wildcard: default for unlisted domains
126+
'imap_host' => 'ssl://mail.example.com:993',
127+
'smtp_host' => 'tls://mail.example.com:587',
128+
'user' => 'email',
129+
],
130+
];
131+
```
38132

39-
### Settings ###
133+
### Options
40134

41-
![Plugin settings](https://i.imgur.com/rFaHUbR.jpg)
135+
| Setting | Default | Description |
136+
|---------|---------|-------------|
137+
| `ident_switch.check_mail` | `true` | Enable background mail checking across secondary accounts |
138+
| `ident_switch.round_robin` | `false` | Check one account per refresh cycle instead of all at once |
139+
| `ident_switch.hide_notifier_warning` | `false` | Hide the warning when `newmail_notifier` plugin is not active |
140+
| `ident_switch.preconfig_only` | `false` | Restrict account creation to preconfigured domains only |
141+
| `ident_switch.debug` | `false` | Log SMTP/Sieve routing and alias resolution to `logs/ident_switch.log` |
42142

43-
* **Enabled** - enables plugin (i.e. account switcing) for this identity.
44-
* **Label** - text that will be displayed in drop down list for this identity. If left blank email will be used.
45-
* **IMAP**
46-
* **Server host name** - host name for imap server. If left blank 'localhost' will be used.
47-
* **Port** - port on server to connect to. If left blank 143 will be used.
48-
* **Secure connection** - enabled secure connection (TLS) *for both IMAP and SMTP*.
49-
* **Username** - login used *for IMAP and SMTP servers*.
50-
* **Password** - password used *for IMAP and SMTP servers*. It's stored encrypted in database.
51-
* **SMTP**
52-
* **Server host name** - host name for imap server. If left blank 'localhost' will be used.
53-
* **Port** - port on server to connect to. If left blank 587 will be used.
143+
## Usage
54144

55-
### Migrating from the original plugin ###
145+
1. Create a new identity in **Settings > Identities**
146+
2. Choose the account mode:
147+
- **Primary account** — default identity, no server config needed
148+
- **Separate account** — configure IMAP, SMTP, and optionally Sieve servers
149+
- **Alias of [account]** — link to an existing account's servers
150+
3. For separate accounts, fill in server details (or let preconfig handle it)
151+
4. The account switcher dropdown appears in the toolbar once at least one separate account is configured
56152

57-
If you are upgrading from the original `boressoft/ident_switch` or another fork:
153+
## Updating
58154

59-
1. Replace the plugin files in `plugins/ident_switch/`.
60-
2. Run the database migration to update the schema:
61-
```sh
62-
bin/updatedb.sh --package=ident_switch --dir=plugins/ident_switch/SQL
63-
```
64-
3. If you use `config.inc.php`, update it to the new format. The `'host'` key has been replaced by separate `'imap_host'` and `'smtp_host'` keys (the old `'host'` key still works as fallback):
65-
```php
66-
'domain.tld' => [
67-
'imap_host' => 'ssl://mail.domain.tld:993',
68-
'smtp_host' => 'tls://mail.domain.tld:587',
69-
'user' => 'email',
70-
'readonly' => true,
71-
],
155+
```bash
156+
composer update gecka/roundcube-ident_switch
72157
```
73-
4. If installed via Composer, update `composer.json` to use `gecka/roundcube-ident_switch` instead of `boressoft/ident_switch`.
74-
75-
### Version compatibility ###
76-
* Versions 1.X (not supported any more) - for Roundcube v1.1
77-
* Versions 2.X (not supported any more) - for Roundcube v1.2
78-
* Versions 3.X (not supported any more) - for Roundcube v1.3
79-
* Versions 4.x - for Roundcube v1.3, 1.4 and 1.5.
80-
* Versions 5.x - for Roundcube v1.6+ (PHP 8.1+)
81-
82-
This is a fork of the [original plugin](https://bitbucket.org/BoresExpress/ident_switch) by Boris Gulay, maintained at [Gecka-apps/ident_switch](https://github.com/Gecka-apps/ident_switch).
83-
84-
### Contributors ###
85-
* **Boris Gulay** - Original developer (2016-2022)
86-
* **Christian Landvogt** - Special folders support (2019)
87-
* **Gergely Papp** - Bug fixes (2021)
88-
* **Mickael** - SMTP compatibility fix (2022)
89-
* **Laurent Dinclaux - Gecka** - Current maintainer (2026)
158+
159+
Database migrations are applied automatically by the Roundcube plugin installer.
160+
161+
## Migrating from the Original Plugin
162+
163+
If you are upgrading from `boressoft/ident_switch`, `toteph42/identity_switch`, or another fork:
164+
165+
### With Composer
166+
167+
1. Replace the old package in `composer.json` with `gecka/roundcube-ident_switch` and run `composer update`
168+
2. Database migrations are applied automatically
169+
170+
### Manual
171+
172+
1. Replace the plugin files in `plugins/ident_switch/`
173+
2. Run the database migration:
174+
```bash
175+
bin/updatedb.sh --package=ident_switch --dir=plugins/ident_switch/SQL
176+
```
177+
178+
### Configuration
179+
180+
If you use `config.inc.php`, update it to the new format — the `'host'` key has been replaced by separate `'imap_host'` and `'smtp_host'` keys (old `'host'` key still works as fallback).
181+
182+
## Localization
183+
184+
Available in 7 languages: English, French, German, Italian, Dutch, Russian, Slovenian.
185+
186+
## Version Compatibility
187+
188+
| Version | Roundcube | PHP |
189+
|---------|-----------|-----|
190+
| 5.x | 1.6+ | 8.2+ |
191+
| 4.x | 1.3 — 1.5 | 7.x — 8.1 |
192+
| 1.x — 3.x | 1.1 — 1.3 | *discontinued* |
193+
194+
## License
195+
196+
This plugin is released under the [GNU Affero General Public License Version 3](https://www.gnu.org/licenses/agpl-3.0.html).
197+
198+
Original code by Boris Gulay licensed under GPL-3.0+. New contributions licensed under AGPL-3.0+.
199+
200+
## Authors
201+
202+
- **Boris Gulay** — Original developer (2016–2022)
203+
- **Christian Landvogt** — Special folders support
204+
- **Gergely Papp** — Bug fixes
205+
- **Laurent Dinclaux - Gecka** — Current maintainer ([Gecka](https://gecka.nc))
206+
207+
---
208+
209+
Built with 🥥 and ☕ by [Gecka](https://gecka.nc) — Kanaky-New Caledonia 🇳🇨

0 commit comments

Comments
 (0)