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:

git clone <repository-url>
cd kyoobackend

2. Start the services:

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

{
  "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

{
  "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

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": "Error message"
}

Paginated List

{
  "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

docker-compose up -d --build

Stop services

docker-compose down

View logs

# All logs
docker-compose logs

# Specific service
docker-compose logs php
docker-compose logs mariadb

Reset database

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

docker-compose logs php

Database connection errors

Check if MariaDB is running:

docker-compose ps

Tables not created

Tables are auto-created on first API call. Check logs:

docker-compose logs php

Swagger/OpenAPI Documentation

A Swagger/OpenAPI specification file is included at swagger.json in the project root. This file can be used with Swagger UI to interactively test the API.

Using Swagger UI

Option 1: Online Swagger Editor

1. Go to https://editor.swagger.io
2. Import the swagger.json file
3. Click "Try it out" to test endpoints

Option 2: Docker with Swagger UI

docker run -p 8080:8080 -e SWAGGER_JSON=/swagger/swagger.json -v $(pwd):/swagger swaggerapi/swagger-ui

Then access at: http://localhost:8080

Option 3: Local Swagger UI

1. Download Swagger UI from https://github.com/swagger-api/swagger-ui
2. Extract and open dist/index.html
3. Modify the URL to point to your swagger.json file

API Endpoints Covered

• Root endpoints (API info, auto-docs)
• Media CRUD operations
• Series episodes CRUD operations
• Music tracks CRUD operations
• Cast CRUD operations
• Adult cast CRUD operations
• Settings operations

License

[Add your license here]