games:import-stats

Imports statistics JSON data for a specific game version.

Overview

This command imports pre-generated statistics from JSON files into the database for a specific game version. It's typically used to import analysis results from external processing or to restore statistics data.

Key Features: JSON validation, data integrity checks, flexible targeting options.

Usage

php artisan games:import-stats [options]

Options

--game-id=ID: ID of the specific game to process.
--game-name=NAME: Name of the game to process (only used if game-id is not provided).
--version-id=ID: Game version ID in the database.
--stats-file=PATH: Path to the stats JSON file to import.

JSON Format

The stats JSON file should contain structured data with the following format:

{
  "characters": [
    {
      "name": "Character Name",
      "blocks": 150,
      "words": 2500,
      "language": "en"
    }
  ],
  "metadata": {
    "total_blocks": 500,
    "total_words": 8000,
    "languages": ["en", "ja"]
  }
}

Examples

php artisan games:import-stats --game-id=123 --stats-file=/path/to/stats.json

Imports stats for the latest version of game ID 123.

php artisan games:import-stats --game-name="My Game" --stats-file=stats.json

Imports stats for the latest version of the named game.

php artisan games:import-stats --version-id=456 --stats-file=./data/stats.json

Imports stats for a specific version ID.

php artisan games:import-stats --game-id=123 --stats-file=storage/stats/game123.json

Uses a relative path to the stats file.

When to Use

Recommended Usage Scenarios

Importing analysis results from external tools
Restoring statistics after data corruption
Bulk importing pre-calculated statistics
Migrating statistics from other systems
Testing with known good statistics data

Validation

The command performs comprehensive validation:

File Validation

File Existence: Verifies the stats file exists and is readable
JSON Syntax: Validates proper JSON formatting
Schema Validation: Ensures required fields are present

Data Validation

Character Data: Validates character names and statistics
Numeric Values: Ensures blocks and words are non-negative integers
Language Codes: Validates language identifiers
Consistency: Checks totals match individual character sums

Import Process

Step	Action	Validation
1. File Loading	Read and parse JSON file	File exists, valid JSON
2. Target Resolution	Identify game/version	Game/version exists
3. Data Validation	Validate statistics data	Schema compliance
4. Database Update	Import statistics	Data integrity

Error Handling

The command handles various error conditions:

File Not Found: Clear error message with file path
Invalid JSON: Detailed parsing error information
Missing Game/Version: Helpful suggestions for resolution
Data Validation Errors: Specific field-level error details
Database Errors: Transaction rollback on failure

Data Integrity

Import operations maintain data integrity through:

Transaction Wrapping: All-or-nothing import process
Backup Validation: Optionally preserve existing data
Consistency Checks: Verify totals and relationships
Duplicate Prevention: Handle existing statistics appropriately

games:reimport-version - Reimport from stored archives
fix:characters - Comprehensive character fixes
games:refresh - Refresh game information

Last modified: 01 June 2025