Ceratic/MediaCollectorLibary
1
0
Fork 0
mirror of https://github.com/ceratic/MediaCollectorLibary.git synced 2026-05-13 23:56:46 +02:00
Code Issues Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Lars Behrends
2025-10-17 13:29:28 +02:00
commit 929ee43001
85 changed files with 10361 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

301
README.md Normal file
View File

@@ -0,0 +1,301 @@
# 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](https://docker.com/get-started)
- [Docker Compose](https://docs.docker.com/compose/install/)
### Quick Start
1. **Clone and setup**:
```bash
git clone <your-repo-url>
cd media-collector
cp .env.example .env
# Edit .env with your API keys
```
2. **Start the application**:
```bash
# 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
```bash
# 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:
```bash
git clone [repository-url]
cd media-collector
```
2. Install PHP dependencies:
```bash
composer install
```
3. Install frontend dependencies:
```bash
npm install
```
4. Copy and configure the environment file:
```bash
cp .env.example .env
```
Edit `.env` and configure your settings:
```bash
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):
```bash
php setup.php
```
6. Build frontend assets:
```bash
npm run dev
# or for production:
# npm run build
```
7. Start the development server:
```bash
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):
```bash
npm run dev
```
- Building for production:
```bash
npm run build
```
- Running tests:
```bash
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](https://opensource.org/licenses/MIT).