Add API documentation and project README

Add comprehensive API_DOCS.md describing the Kyoo backend API (endpoints, request/response examples, image handling, authentication, error handling, CORS, logging) and a README.md with project overview, tech stack, quick start, API endpoints, data models, configuration and Docker instructions. Provides developers with usage examples, directory layout and troubleshooting steps for local deployment.
Add Jellyfin mappings and optimize cast queries
2026-04-12 03:00:17 +02:00 · 2026-04-12 02:07:59 +02:00
7 changed files with 1481 additions and 32 deletions
--- a/API_DOCS.md
+++ b/API_DOCS.md
--- a/README.md
+++ b/README.md
@@ -0,0 +1,331 @@
+# Kyoo Backend
+
+A RESTful API backend for media management, supporting movies, TV series, music albums, games, and cast information.
+
+## Features
+
+- **Media Management**: CRUD operations for movies, TV series, music albums, and games
+- **Cast Management**: Manage actors, directors, and other staff with filmography tracking
+- **Image Handling**: Automatic processing and storage of posters, banners, and cast photos
+- **Search & Filtering**: Advanced search with pagination support
+- **API Logging**: Built-in request/response logging for debugging
+- **Docker Support**: Easy deployment with Docker Compose
+- **Auto Documentation**: Self-documenting API endpoint
+
+## Tech Stack
+
+- **PHP 8.2** with Apache
+- **MariaDB 10.11** 
+- **Docker & Docker Compose**
+- **phpMyAdmin** for database management
+
+## Quick Start
+
+### Prerequisites
+
+- Docker installed
+- Docker Compose installed
+
+### Installation
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd kyoobackend
+```
+
+2. Start the services:
+```bash
+docker-compose up -d --build
+```
+
+3. Access the API:
+- API Base URL: `http://localhost:6400/api`
+- phpMyAdmin: `http://localhost:6402`
+
+### Database Credentials
+
+- **Host**: `mariadb` (within Docker) or `localhost:6401` (from host)
+- **Database**: `kyoo`
+- **User**: `kyoo_user`
+- **Password**: `kyoo_password`
+- **Root Password**: `root_password`
+
+## Project Structure
+
+```
+kyoobackend/
+├── api/
+│   ├── controllers/     # Request handlers
+│   │   ├── MediaController.php
+│   │   ├── CastController.php
+│   │   ├── ImageController.php
+│   │   └── SettingsController.php
+│   ├── models/          # Data models
+│   │   ├── Media.php
+│   │   ├── Cast.php
+│   │   ├── Game.php
+│   │   ├── Series.php
+│   │   ├── Music.php
+│   │   └── ...
+│   ├── services/        # Business logic
+│   │   ├── ApiLogger.php
+│   │   ├── ImageHandler.php
+│   │   └── DocumentationService.php
+│   ├── config.php       # Configuration
+│   ├── database.php     # Database connection
+│   ├── Router.php       # API routing
+│   └── index.php        # Entry point
+├── docker-compose.yml   # Docker configuration
+├── Dockerfile           # PHP container build
+└── php-custom.ini       # PHP configuration
+```
+
+## API Endpoints
+
+### Root
+- `GET /api` - API information and available endpoints
+
+### Documentation
+- `GET /api/docs` - Auto-generated API documentation
+
+### Media
+- `GET /api/media` - Get all media (with pagination and filtering)
+- `GET /api/media/:id` - Get specific media item
+- `POST /api/media` - Create new media
+- `PUT /api/media/:id` - Update media
+- `DELETE /api/media/:id` - Delete media
+
+### Series Episodes
+- `GET /api/media/:id/episodes` - Get all episodes for a series
+- `GET /api/media/:id/episodes/:episodeId` - Get specific episode
+- `POST /api/media/:id/episodes` - Add episode to series
+- `PUT /api/media/:id/episodes/:episodeId` - Update episode
+- `DELETE /api/media/:id/episodes/:episodeId` - Delete episode
+
+### Music Tracks
+- `GET /api/media/:id/tracks` - Get all tracks for an album
+- `GET /api/media/:id/tracks/:trackId` - Get specific track
+- `POST /api/media/:id/tracks` - Add track to album
+- `PUT /api/media/:id/tracks/:trackId` - Update track
+- `DELETE /api/media/:id/tracks/:trackId` - Delete track
+
+### Cast
+- `GET /api/cast` - Get all cast members (with search)
+- `GET /api/cast/:id` - Get specific cast member with filmography
+- `GET /api/cast/:id/media` - Get all media for a cast member
+- `POST /api/cast` - Create new cast member
+- `PUT /api/cast/:id` - Update cast member
+- `DELETE /api/cast/:id` - Delete cast member
+
+### Adult Cast
+- `GET /api/cast/adult` - Get all adult cast members (with filters)
+- `GET /api/cast/adult/:id` - Get specific adult cast member
+- `POST /api/cast/adult` - Create new adult cast member
+- `PUT /api/cast/adult/:id` - Update adult cast member
+- `DELETE /api/cast/adult/:id` - Delete adult cast member
+
+### Images
+- `GET /api/images/*` - Serve images directly
+
+### Settings
+- `GET /api/settings` - Get application settings
+- `PUT /api/settings` - Update settings
+
+## Query Parameters
+
+### Media List
+- `page` - Page number (default: 1)
+- `limit` - Items per page (default: 20)
+- `category` - Filter by category (e.g., "movie", "tv", "music", "game")
+- `type` - Filter by type (e.g., "Movie", "TV", "Album", "Game")
+- `search` - Search in title and description
+
+### Cast List
+- `page` - Page number (default: 1)
+- `limit` - Items per page (default: 20)
+- `search` - Search by name
+
+### Adult Cast List
+- `page` - Page number (default: 1)
+- `limit` - Items per page (default: 20)
+- `search` - Search by name
+- `ethnicity` - Filter by ethnicity
+- `hair_color` - Filter by hair color
+
+### Series Episodes
+- `season` - Filter by season number
+
+## Data Models
+
+### Media
+```json
+{
+  "id": 1,
+  "title": "Movie Title",
+  "cleanname": "movie-title",
+  "year": 2024,
+  "poster": "/images/movies/poster_xxx.webp",
+  "banner": "/images/movies/banner_xxx.webp",
+  "description": "Description text",
+  "rating": 8.5,
+  "category": "movie",
+  "type": "Movie",
+  "status": "released",
+  "aspectRatio": "16:9",
+  "runtime": 120,
+  "director": "Director Name",
+  "writer": "Writer Name",
+  "source": "netflix",
+  "releaseDate": "2024-01-01",
+  "genres": ["Action", "Drama"],
+  "tags": ["tag1", "tag2"],
+  "studios": ["Studio1"],
+  "staff": [
+    {
+      "id": 1,
+      "name": "Actor Name",
+      "role": "Actor",
+      "characterName": "Character",
+      "characterImage": "/images/characters/char_xxx.webp"
+    }
+  ],
+  "createdAt": "2024-01-01 00:00:00",
+  "updatedAt": "2024-01-01 00:00:00"
+}
+```
+
+### Cast
+```json
+{
+  "id": 1,
+  "name": "Actor Name",
+  "cleanname": "actor-name",
+  "photo": "/images/cast/photo_xxx.webp",
+  "bio": "Biography text",
+  "birthDate": "1990-01-01",
+  "birthPlace": "City, Country",
+  "occupations": ["Actor", "Director"],
+  "filmography": [
+    {
+      "id": 1,
+      "title": "Movie Title",
+      "year": 2024,
+      "poster": "/images/movies/poster_xxx.webp",
+      "category": "movie",
+      "type": "Movie",
+      "role": "Actor",
+      "characterName": "Character"
+    }
+  ],
+  "createdAt": "2024-01-01 00:00:00",
+  "updatedAt": "2024-01-01 00:00:00"
+}
+```
+
+## Response Format
+
+All responses follow this structure:
+
+### Success
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+### Error
+```json
+{
+  "success": false,
+  "error": "Error message"
+}
+```
+
+### Paginated List
+```json
+{
+  "success": true,
+  "data": {
+    "items": [ ... ],
+    "total": 100,
+    "page": 1,
+    "limit": 20,
+    "totalPages": 5
+  }
+}
+```
+
+## Configuration
+
+Environment variables can be set in `docker-compose.yml` or as system environment variables:
+
+- `DB_HOST` - Database host (default: `mariadb`)
+- `DB_NAME` - Database name (default: `kyoo`)
+- `DB_USER` - Database user (default: `kyoo_user`)
+- `DB_PASS` - Database password (default: `kyoo_password`)
+- `API_LOGGING_ENABLED` - Enable API logging (default: `false`)
+
+## Docker Commands
+
+### Start services
+```bash
+docker-compose up -d --build
+```
+
+### Stop services
+```bash
+docker-compose down
+```
+
+### View logs
+```bash
+# All logs
+docker-compose logs
+
+# Specific service
+docker-compose logs php
+docker-compose logs mariadb
+```
+
+### Reset database
+```bash
+docker-compose down -v
+docker-compose up -d --build
+```
+
+## Development
+
+The API files are mounted as volumes, so changes are immediately reflected without rebuilding.
+
+### API Logging
+
+Logs are written to:
+- API requests/responses: `/var/www/html/logs/api.log`
+- PHP errors: `/var/www/html/logs/php_error.log`
+
+Enable logging by setting `API_LOGGING_ENABLED=true`.
+
+## Troubleshooting
+
+### PHP container won't start
+```bash
+docker-compose logs php
+```
+
+### Database connection errors
+Check if MariaDB is running:
+```bash
+docker-compose ps
+```
+
+### Tables not created
+Tables are auto-created on first API call. Check logs:
+```bash
+docker-compose logs php
+```
+
+## License
+
+[Add your license here]
--- a/api/controllers/MediaController.php
+++ b/api/controllers/MediaController.php
@@ -279,16 +279,6 @@ class MediaController {
        
        $result = $this->media->search($filters, $page, $limit);

-        // Game-spezifische Daten für Games laden
-        foreach ($result['items'] as &$item) {
-            if ($item['type'] === 'Game') {
-                $gameInfo = $this->game->getGameInfoForList($item['id']);
-                if ($gameInfo) {
-                    $item = array_merge($item, $gameInfo);
-                }
-            }
-        }
-        
        return ['success' => true, 'data' => $result];
    }
    
--- a/api/database.php
+++ b/api/database.php
@@ -357,6 +357,7 @@ class Database {
                auto_play_trailers BOOLEAN DEFAULT 0,
                language TEXT DEFAULT 'en',
                theme TEXT DEFAULT 'system',
+                jellyfin_library_mappings JSON,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
            )
--- a/api/models/Cast.php
+++ b/api/models/Cast.php
@@ -49,16 +49,37 @@ class Cast extends BaseModel {
        $items = $this->findAll($conditions, 'createdAt DESC', $limit, $offset);
        $total = $this->count($conditions);

+        // Load filmography for all cast members in a single query
+        if (!empty($items)) {
+            $castIds = array_column($items, 'id');
+            $placeholders = str_repeat('?,', count($castIds) - 1) . '?';
            
-        // Add filmography to each cast member
-        foreach ($items as &$item) {
-            $item['filmography'] = $this->getMediaForCast($item['id']);
-            // Extract unique media types
-            $mediaTypes = array_unique(array_column($item['filmography'], 'category'));
-            $item['media_types'] = array_values($mediaTypes);
+            $stmt = $this->pdo->prepare("
+                SELECT mc.cast_id, m.id, m.title, m.year, m.poster, m.category, m.type, mc.role, mc.characterName
+                FROM media m
+                INNER JOIN media_cast mc ON m.id = mc.media_id
+                WHERE mc.cast_id IN ($placeholders)
+                ORDER BY m.year DESC
+            ");
+            $stmt->execute($castIds);
+            $allFilmography = $stmt->fetchAll();
+            
+            // Group filmography by cast_id
+            $filmographyByCast = [];
+            foreach ($allFilmography as $film) {
+                $castId = $film['cast_id'];
+                unset($film['cast_id']);
+                $filmographyByCast[$castId][] = $film;
+            }
+            
+            // Attach filmography to each cast member
+            foreach ($items as &$item) {
+                $item['filmography'] = $filmographyByCast[$item['id']] ?? [];
+                $mediaTypes = array_unique(array_column($item['filmography'], 'category'));
+                $item['media_types'] = array_values($mediaTypes);
+            }
        }

-        
        return [
            'items' => $items,
            'total' => $total,
--- a/api/models/Media.php
+++ b/api/models/Media.php
@@ -65,11 +65,6 @@ class Media extends BaseModel {
            $stmt->execute($params);
            $items = $stmt->fetchAll();

-            // Cast-Mitglieder für jedes Medium laden
-            foreach ($items as &$item) {
-                $item['staff'] = $this->getCastForMedia($item['id']);
-            }
-            
            // Count Query
            $countQuery = "SELECT COUNT(*) FROM {$this->table} WHERE 1=1";
            $countParams = [];
@@ -93,11 +88,6 @@ class Media extends BaseModel {
        } else {
            $items = $this->findAll($conditions, 'createdAt DESC', $limit, $offset);
            $total = $this->count($conditions);
-            
-            // Cast-Mitglieder für jedes Medium laden
-            foreach ($items as &$item) {
-                $item['staff'] = $this->getCastForMedia($item['id']);
-            }
        }
        
        return [
--- a/api/models/Settings.php
+++ b/api/models/Settings.php
@@ -56,6 +56,10 @@ class Settings extends BaseModel {
            $updateData['theme'] = $data['theme'];
        }

+        if (isset($data['jellyfin_library_mappings'])) {
+            $updateData['jellyfin_library_mappings'] = $data['jellyfin_library_mappings'];
+        }
+        
        // Check if settings row exists
        $existing = $this->findById(1);
        
@@ -72,7 +76,7 @@ class Settings extends BaseModel {
                'auto_play_trailers' => 0,
                'language' => 'en',
                'theme' => 'system',
-                'theme' => 'system'
+                'jellyfin_library_mappings' => ''
            ];
            $mergedData = array_merge($defaultData, $updateData);
            $this->create($mergedData);