immich_integration
No security coverage
Immich Integration
A comprehensive service-oriented integration with Immich, the self-hosted photo and video management solution.
Overview
The Immich Integration module provides a robust Service-Oriented Architecture (SOA) foundation for integrating Immich with Drupal. Rather than providing opinionated features out-of-the-box, this module focuses on offering a comprehensive service layer that developers can use to build custom Immich integrations tailored to their specific needs.
What is Immich?
Immich is a high-performance, self-hosted photo and video management solution that provides features like:
- Automatic photo backup from mobile devices
- Machine learning-powered face recognition
- Advanced search capabilities
- Timeline views and memories
- Album management
- Shared links and collaborative features
Service-Oriented Architecture
This module is built on Service-Oriented Architecture principles, providing a clean, injectable ImmichClient service that encapsulates all communication with the Immich API. Developers can inject this service into their custom modules, blocks, controllers, or plugins to build any Immich-related functionality they need.
Why Service-Oriented?
- Maximum Flexibility: Build exactly the features you need
- Clean Code: Reusable service methods following Drupal best practices
- Easy Extension: No need to modify the base module
- Minimal Dependencies: Lightweight foundation with no UI opinions
- Developer-Friendly: Comprehensive API coverage with extensive documentation
Features
Comprehensive API Coverage (50+ Methods)
The immich_integration.client service provides access to all major Immich API categories:
Server Operations
- Connection testing and health checks
- Server version and configuration
- Feature detection and statistics
Album Management
- List, create, update, and delete albums
- Add and remove assets from albums
- Full CRUD operations
Asset Management
- List and filter assets
- Get asset metadata
- Update asset properties (favorites, descriptions, etc.)
- Delete assets
- Generate thumbnail and original file URLs
Search & Discovery
- Search assets by metadata (location, camera, date, etc.)
- Browse places and cities
- Get curated explore content
Timeline Features
- Get time-based asset buckets (monthly/yearly)
- Retrieve assets for specific time periods
- Build chronological galleries
People (Face Recognition)
- List recognized people
- Get person details
- Update person names
Tags
- List and create tags
- Tag assets
- Organize content by tags
Shared Links
- Create public/private shared links
- Manage link permissions
- Delete shared links
User & Library Management
- Get current user information
- Access user preferences
- Manage libraries and statistics
Memories
- Access "on this day" features
- Build nostalgia-driven experiences
Configuration Interface
- Simple settings form at
/admin/config/media/immich - Secure API key storage using Drupal's configuration system
- AJAX-powered connection testing
- Server URL configuration with validation
Demo Pages (Reference Implementation)
- Album listing page
- Photo gallery with grid layout
- Navigation tabs for easy access
- These serve as examples for developers building custom features
Complete Documentation
- Comprehensive README with usage examples
- Inline code documentation for all methods
- Example custom block implementation
- Example custom controller implementation
- Error handling patterns
- Extension ideas and best practices
Use Cases
This module serves as a foundation for building:
- Photo Galleries: Display Immich photos on your Drupal site
- Media Integration: Import Immich assets into Drupal's Media library
- Content Enhancement: Add Immich images to content types via field formatters
- Timeline Displays: Create chronological photo galleries
- Search Interfaces: Build custom search forms for Immich content
- User Dashboards: Show personalized photo collections
- Face Recognition: Integrate people detection into your site
- Location-Based Features: Display photos by geographic location
- Shared Galleries: Create public or private photo sharing features
- Mobile App Backend: Use Drupal as a bridge between mobile apps and Immich
Example Usage
Simple: Display Recent Photos
// Inject the service
$immich = \Drupal::service('immich_integration.client');
// Get recent assets
$assets = $immich->getAssets();
$recent = array_slice($assets, 0, 10);
foreach ($recent as $asset) {
echo '<img src="' . $immich->getAssetThumbnailUrl($asset['id']) . '" />';
}
Advanced: Search and Filter
$immich = \Drupal::service('immich_integration.client');
// Search for photos from Paris taken with Canon camera
$results = $immich->searchAssets([
'city' => 'Paris',
'make' => 'Canon',
'takenAfter' => '2024-01-01',
]);
Custom Block Plugin
use Drupal\immich_integration\Service\ImmichClient;
class RecentPhotosBlock extends BlockBase implements ContainerFactoryPluginInterface {
protected $immichClient;
public function __construct(..., ImmichClient $immich_client) {
parent::__construct(...);
$this->immichClient = $immich_client;
}
public static function create(ContainerInterface $container, ...) {
return new static(
...,
$container->get('immich_integration.client')
);
}
public function build() {
$assets = $this->immichClient->getAssets(['isFavorite' => true]);
// Build your render array
}
}
Requirements
- Drupal 9.4, 10, or 11
- PHP 7.4 or higher
- Access to an Immich server (self-hosted or cloud)
- Immich API key with appropriate permissions
Installation
- Install the module using Composer (recommended) or manually
- Enable the module:
drush en immich_integration - Configure your Immich server connection at
/admin/config/media/immich - Generate an API key in your Immich account settings
- Test the connection using the AJAX test button
- Start building your custom integration!
Configuration
- Navigate to Configuration → Media → Immich Integration
- Enter your Immich server URL (e.g.,
http://localhost:2283orhttps://immich.example.com) - Enter your Immich API key (generate one in Immich under Account Settings → API Keys)
- Click "Test Connection" to verify connectivity
- Save configuration
Security
- API keys are stored securely in Drupal's configuration system
- All API communication uses header-based authentication
- Access to configuration pages is restricted by permissions
- Comprehensive error logging for debugging
- Input validation on all service methods
Performance Considerations
- The module makes real-time API calls to your Immich server
- All service methods return
NULLon failure for easy error handling - Errors are logged to the
immich_integrationwatchdog channel - Consider implementing caching in your custom code for frequently accessed data
- Thumbnail URLs require authentication and may need proxying for public display
Extension Ideas
Developers can extend this module to build:
- Media Library Integration: Import Immich assets as Drupal Media entities
- Views Integration: Create Views plugins for Immich data
- Field Formatters: Display Immich images in content types
- Caching Layer: Add Drupal cache integration to reduce API calls
- Image Proxy: Proxy Immich images through Drupal for better browser compatibility
- Batch Operations: Implement batch API for bulk imports
- Webhooks: Listen for Immich events and sync data
- Advanced Search UI: Build custom search forms with exposed filters
- Lightbox Integration: Add photo viewing experiences
- Mobile Upload: Create upload interfaces for mobile users
Support
This module provides the service layer only. For custom development or feature requests, extend the module in your own custom code using the provided service methods.
Project Information
- Project Page: https://www.drupal.org/project/immich_integration
- Issue Queue: https://www.drupal.org/project/issues/immich_integration
- Immich Documentation: https://immich.app/
- Immich API Documentation: https://api.immich.app/
Related Projects
- Immich: https://immich.app/ - The self-hosted photo and video management solution
- Media: Core Drupal media management
- Image: Core Drupal image handling
Note: This module is a service-oriented foundation, not a complete feature set. It provides the tools; you build the features. Perfect for developers who want full control over their Immich integration without being constrained by opinionated implementations.