alienlebarge / handle
A Kirby plugin that automatically transforms social handles into links to their profiles
Installs: 24
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Type:kirby-plugin
Requires
- php: >=7.4
- getkirby/composer-installer: ^1.1
Requires (Dev)
- phpunit/phpunit: ^9.5
This package is auto-updated.
Last update: 2025-06-24 21:12:41 UTC
README
A Kirby plugin that automatically transforms social handles (like @user@instance
) into clickable links to their profiles. Supports Unicode characters, custom services, and comprehensive configuration options.
Installation
Download
Download and place this plugin in /site/plugins/handle
.
Composer
composer require alienlebarge/handle
Git
git submodule add https://github.com/alienlebarge/handle.git site/plugins/handle
Usage
Field Method
<?= $page->text()->kirbytext()->handleLinks() ?>
Automatic
The plugin automatically processes all texts passed through kirbytext.
KirbyTag
(handle: @user@instance)
or
(handle: user: username instance: bsky.app)
Configuration
Configure the plugin in your config.php
file:
return [ // Global plugin settings 'alienlebarge.handle.enabled' => true, 'alienlebarge.handle.maxTextLength' => 100000, 'alienlebarge.handle.logErrors' => true, 'alienlebarge.handle.enableFediverse' => true, // Service configurations 'alienlebarge.handle.services' => [ 'bsky.app' => [ 'enabled' => true, 'urlPrefix' => 'https://bsky.app/profile/', 'urlSuffix' => '', 'class' => 'bsky-link', 'displayUsername' => true, 'name' => 'Bluesky' ], // Add custom services... ] ];
See CONFIG.md for detailed configuration options and examples.
Default Supported Services
- Fediverse (Mastodon, etc.)
- Bluesky (bsky.app)
- Flickr
- GitHub
- Micro.blog
- YouTube
- Vimeo
Migration from v0.0.3
If upgrading from v0.0.3, update your configuration:
Before:
'handle.services' => [ 'github.com' => [ 'urlPrefix' => 'https://github.com/', 'class' => 'github-link' ] ]
After:
'alienlebarge.handle.services' => [ 'github.com' => [ 'enabled' => true, // New required field 'urlPrefix' => 'https://github.com/', 'class' => 'github-link', 'displayUsername' => true, // New optional field 'name' => 'GitHub' // New optional field ] ]
License
MIT
Features
- Automatic Processing: Transforms handles via
kirbytext:before
hook - Unicode Support: Works with international usernames and domains
- Security: XSS protection with input validation and sanitization
- Performance: Optimized with early returns and configurable text size limits
- Extensible: Easy to add custom services and configure behavior
- Code Protection: Preserves handles in code blocks and backticks
Requirements
- PHP >= 7.4
- Kirby CMS >= 3.0
Advanced Usage
In your templates
The plugin works in several ways:
-
Automatically (via the
kirbytext:before
hook):<?= $page->text()->kirbytext() ?>
-
Manually (via the field method):
<?= $page->text()->handleLinks() ?>
-
Via KirbyTag:
(handle: @heydon@social.lol)
or
(handle: user: heydon instance: social.lol)
Adding Custom Services
'alienlebarge.handle.services' => [ 'mastodon.social' => [ 'enabled' => true, 'urlPrefix' => 'https://mastodon.social/@', 'urlSuffix' => '', 'class' => 'mastodon-link', 'displayUsername' => true, 'name' => 'Mastodon Social' ], 'custom-platform.com' => [ 'enabled' => true, 'urlPrefix' => 'https://custom-platform.com/users/', 'urlSuffix' => '/profile', 'class' => 'custom-platform-link', 'displayUsername' => false, // Show @username@instance 'name' => 'Custom Platform' ] ]
Service Configuration Options:
enabled
(bool): Enable/disable this serviceurlPrefix
(string, required): Base URL for user profilesurlSuffix
(string): Optional suffix added to URLsclass
(string, required): CSS class for styling linksdisplayUsername
(bool): Show only@username
(true) or@username@instance
(false)name
(string): Human-readable service name for documentation
Validation Rules:
- URL Format: Must be valid HTTP/HTTPS URLs
- CSS Classes: Must follow CSS naming conventions (
[a-zA-Z][a-zA-Z0-9\-_]*
) - Required Fields:
urlPrefix
andclass
are mandatory