MediaCollectorLibary/README.md

Media Collector

A modern PHP application to collect and manage media from various sources like Steam, Jellyfin, Stash, and XBVR.

Features

• Unified Dashboard: View all your media in one place with comprehensive statistics
• Multiple Sources: Connect to Steam, Jellyfin, Stash, and XBVR
• Media Types: Manage games, movies, TV shows, and music with detailed tracking
• Database-Driven: Complete database schema with migrations and models
• Rich Analytics: Track playtime, watch counts, favorites, and sync status
• User Authentication: Secure login system with session management
• Admin Panel: Comprehensive admin interface for sync management
• Real-time Sync: Live progress tracking and status updates
• Responsive Design: Works on desktop and mobile devices
• Modern Stack: Built with PHP 8.1+, Slim Framework, Vue.js, and Tailwind CSS

Authentication & Admin Features

User Management

• Secure Authentication: Session-based login system with CSRF protection
• Role-based Access: Admin and user roles with appropriate permissions
• Session Management: Automatic session handling and cleanup

Admin Panel (/admin)

• Source Management: Configure and manage media sources
• Sync Control: Start full or incremental syncs for each source
• Live Status: Real-time progress tracking and error reporting
• Sync History: View past sync activities and results
• Error Monitoring: Comprehensive error logging and debugging

Database Schema

The application includes a comprehensive database schema supporting:

• Games: Steam integration, playtime tracking, completion percentages
• Movies: Watch status, ratings, TMDb integration
• TV Shows & Episodes: Season/episode tracking, watch progress
• Music: Artists, albums, tracks with play counts and favorites
• Sources: Integration management for external services
• Sync Logs: Synchronization tracking and error reporting
• Users: Authentication and role management

Prerequisites

• PHP 8.1 or higher
• Composer (for PHP dependencies)
• Node.js 16+ and npm/yarn (for frontend assets)
• SQLite (or MySQL/PostgreSQL)

Docker Installation (Recommended)

For the easiest setup, use Docker Compose:

Prerequisites

• Docker
• Docker Compose

Quick Start

1. Clone and setup:

   git clone <your-repo-url>
   cd media-collector
   cp .env.example .env
   # Edit .env with your API keys
   

2. Start the application:

   # For production
   docker-compose up -d
   
   # For development (with hot-reload)
   docker-compose --profile dev up
   

3. Access the application:

   • Main app: http://localhost:8000
   • Admin panel: http://localhost:8000/admin

Docker Commands

# View logs
docker-compose logs -f

# Stop containers
docker-compose down

# Rebuild containers
docker-compose up --build

# Access PHP container
docker-compose exec app bash

# Reset database
docker-compose down -v
docker-compose up -d

Docker Architecture

• App Container: PHP 8.2-FPM with Composer dependencies
• Nginx Container: Web server for static files and reverse proxy
• Database: SQLite file stored in persistent volume
• Networks: Isolated network for container communication

Manual Installation (Alternative)

1. Clone the repository:

   git clone [repository-url]
   cd media-collector
   

2. Install PHP dependencies:

   composer install
   

3. Install frontend dependencies:

   npm install
   

4. Copy and configure the environment file:

   cp .env.example .env
   

   Edit .env and configure your settings:

   APP_NAME="Media Collector"
   APP_ENV=local
   APP_DEBUG=true
   APP_URL=http://localhost:8000
   
   # Database Configuration
   DB_CONNECTION=sqlite
   DB_DATABASE=database/database.sqlite
   
   # Admin User Configuration (required for initial setup)
   ADMIN_USERNAME=admin
   ADMIN_EMAIL=admin@example.com
   ADMIN_PASSWORD=admin123
   
   # Gaming Platform APIs
   STEAM_API_KEY=your_steam_api_key_here
   EXOPHASE_API_KEY=your_exophase_api_key_here
   EXOPHASE_API_URL=https://api.exophase.com
   
   # Services API Keys
   JELLYFIN_API_KEY=your_jellyfin_api_key_here
   STASH_API_KEY=your_stash_api_key_here
   STASH_URL=http://localhost:9999
   XBVR_URL=http://localhost:9998
   

5. Set up the database (runs migrations and creates admin user):

   php setup.php
   

6. Build frontend assets:

   npm run dev
   # or for production:
   # npm run build
   

7. Start the development server:

   php -S localhost:8000 -t public
   

8. Login to Admin Panel:

   • Open http://localhost:8000/login
   • Use the admin credentials created during setup
   • Access the admin panel at http://localhost:8000/admin

Development

• Frontend development (with hot-reload):

  npm run dev
  

• Building for production:

  npm run build
  

• Running tests:

  composer test
  

Project Structure

media-collector/
├── app/                    # Application code
│   ├── Controllers/        # Request handlers
│   │   ├── AuthController.php     # Authentication routes
│   │   ├── AdminController.php    # Admin panel routes
│   │   ├── Controller.php         # Base controller class
│   │   └── DashboardController.php
│   ├── Database/           # Database connection and configuration
│   │   └── Database.php
│   ├── Http/               # HTTP middleware
│   │   └── Middleware/     # Authentication and admin middleware
│   ├── Models/             # Database models and ORM
│   │   ├── Model.php       # Base model class
│   │   ├── Game.php        # Game model with Steam integration
│   │   ├── Movie.php       # Movie model with TMDb integration
│   │   ├── TvShow.php      # TV show model
│   │   ├── TvEpisode.php   # TV episode model
│   │   ├── MusicArtist.php # Music artist model
│   │   ├── MusicAlbum.php  # Music album model
│   │   ├── MusicTrack.php  # Music track model
│   │   ├── Source.php      # Source integration model
│   │   ├── SyncLog.php     # Synchronization log model
│   │   └── User.php        # User authentication model
│   ├── Services/           # Business logic services
│   │   ├── AuthService.php        # Authentication service
│   │   ├── BaseSyncService.php   # Base sync service class
│   │   ├── SteamSyncService.php  # Steam API integration
│   │   ├── JellyfinSyncService.php # Jellyfin API integration
│   │   ├── StashSyncService.php   # Stash API integration
│   │   └── XbvrSyncService.php    # XBVR API integration
├── config/                 # Configuration files
│   └── database.php        # Database configuration
├── database/               # Database migrations and seeds
│   ├── migrations/         # Database migration files (11 total)
│   └── seeds/              # Database seeders
├── public/                 # Web root
│   └── index.php           # Application entry point
├── resources/
│   ├── js/                 # JavaScript files
│   │   └── app.js          # Main Vue.js application
│   ├── scss/               # Stylesheets
│   │   └── app.scss        # Main stylesheet with Tailwind CSS
│   └── views/              # Twig templates
│       ├── layouts/
│       │   └── app.twig    # Base application layout
│       ├── auth/
│       │   └── login.twig  # Login page
│       ├── dashboard/
│       │   └── index.twig  # Dashboard view
│       └── admin/
│           └── index.twig  # Admin dashboard
├── routes/                 # Application routes
│   └── web.php             # Web routes definition
├── storage/                # Logs, cache, etc.
│   └── framework/          # Framework-specific storage
├── .env                    # Environment variables
├── composer.json           # PHP dependencies
├── package.json            # Node.js dependencies
├── setup.php               # Database setup script
└── README.md

API Integration

The application supports integration with:

• Steam: Game library, playtime, achievements
• Jellyfin: Movies and TV shows with metadata
• Stash: Adult content management
• Exophase Integration: Cross-platform gaming achievements and playtime tracking

Configure your API keys in the .env file to enable these integrations.

Database Models

Each media type includes rich model functionality:

• Statistics: Total counts, averages, favorites
• Relationships: Proper foreign key relationships
• Methods: CRUD operations, special queries, formatting
• Type Casting: Automatic data type conversion
• Error Handling: Comprehensive error reporting

Security Features

• CSRF Protection: All forms include CSRF tokens
• Session Security: Secure session handling with timeouts
• Input Validation: Comprehensive input sanitization
• Role-based Access: Admin-only routes and functionality
• Password Hashing: Secure password storage

Admin Panel Usage

1. Login: Use admin credentials at /login
2. Access Admin: Navigate to /admin for the admin dashboard
3. Source Management: Configure your media sources
4. Sync Operations: Start full or incremental syncs
5. Monitor Progress: View real-time sync status and results
6. View History: Check past sync activities and errors

License

This project is open-sourced software licensed under the MIT license.