### Development Environment Setup and Commands

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Provides shell commands to manage the Docker-based development environment, including building containers, installing dependencies, and executing the test suite.

```bash
make up
make install
make test
```

--------------------------------

### Implement a Complete Flashcard Learning Session

Source: https://context7.com/scottlaurent/fsrs/llms.txt

A full-featured example showing how to initialize the FSRS manager, generate repetition schedules, process card reviews, and serialize card data for storage. It demonstrates the workflow from initial study to updating card metrics and filtering due cards.

```php
<?php

use Scottlaurent\FSRS\Manager;
use Scottlaurent\FSRS\Card;
use Scottlaurent\FSRS\Rating;
use Scottlaurent\FSRS\State;

$fsrs = new Manager(
    defaultRequestRetention: 0.90,
    learningSteps: [1, 10, 60],
    relearningSteps: [10, 30],
    enableFuzzing: true
);

$deck = [];
for ($i = 1; $i <= 5; $i++) {
    $deck[] = [
        'card' => new Card(),
        'front' => "Question $i",
        'back' => "Answer $i"
    ];
}

foreach ($deck as $index => &$item) {
    $card = $item['card'];
    $schedule = $fsrs->generateRepetitionSchedule($card);
    $userRating = rand(2, 4);
    $result = $fsrs->reviewCard($card, $userRating, null, rand(1000, 5000));
    $item['card'] = $result['card'];
}

$savedDeck = array_map(function($item) {
    return [
        'card' => $item['card']->toArray(),
        'front' => $item['front'],
        'back' => $item['back']
    ];
}, $deck);

$json = json_encode($savedDeck, JSON_PRETTY_PRINT);
$loadedDeck = array_map(function($item) {
    return [
        'card' => Card::fromArray($item['card']),
        'front' => $item['front'],
        'back' => $item['back']
    ];
}, json_decode($json, true));
```

--------------------------------

### Install FSRS PHP via Composer

Source: https://context7.com/scottlaurent/fsrs/llms.txt

The standard method to integrate the FSRS PHP library into a project using the Composer dependency manager.

```bash
composer require scottlaurent/fsrs
```

--------------------------------

### Quickstart FSRS PHP Scheduler and Card Generation

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Demonstrates the basic usage of the FSRS PHP library. It initializes the scheduler, creates a new card, generates scheduling options based on different user ratings, and displays the next review date and interval.

```php
<?php

use Scottlaurent\FSRS\Manager;
use Scottlaurent\FSRS\Card;

// Create a scheduler with default settings
$fsrs = new Manager();

// Create a new card
$card = new Card(new DateTime('2024-01-01', new DateTimeZone('UTC')));

// Generate scheduling options for different ratings
$schedule = $fsrs->generateRepetitionSchedule($card);

// Choose a rating and get the updated card
// 1 = Again, 2 = Hard, 3 = Good, 4 = Easy
$updatedCard = $schedule[3]->card; // User rated "Good"

echo "Next review: " . $updatedCard->due->format('Y-m-d H:i:s');
echo "\nInterval: " . $updatedCard->scheduledDays . " days";

```

--------------------------------

### Review a Card and Get Results (PHP)

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Demonstrates using the reviewCard method to process a card review. It returns an array containing the updated Card object and the review log.

```php
$result = $fsrs->reviewCard($card, 3, null, 2500);
$updatedCard = $result['card'];
$reviewLog = $result['log'];

```

--------------------------------

### Calculate Card Retrievability (PHP)

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Example of calculating the probability of recalling a card using the getCardRetrievability method of the FSRS Manager. It takes a Card object and an optional DateTime object.

```php
$retrievability = $fsrs->getCardRetrievability($card);
echo "Recall probability: " . ($retrievability * 100) . "%\n";

```

--------------------------------

### Initialize FSRS Manager with Custom Parameters (PHP)

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Demonstrates how to create a new FSRS Manager instance with custom parameters for retention rate, model weights, maximum interval, learning/relearning steps, and fuzzing.

```php
$fsrs = new Manager(
    defaultRequestRetention: 0.85,    // Target retention rate (85%)
    weights: [
        0.4872, 1.4003, 3.7145, 13.8206, 5.1618, 1.2298, 0.8975, 0.031,
        1.6474, 0.1367, 1.0461, 2.1072, 0.0793, 0.3246, 1.587, 0.2272, 2.8755
    ], // Custom model weights
    defaultMaximumInterval: 36500,    // Maximum interval in days (100 years)
    learningSteps: [1, 10],           // Learning phase intervals (minutes)
    relearningSteps: [10],            // Relearning phase intervals (minutes)
    enableFuzzing: true               // Add randomness to intervals
);

```

--------------------------------

### FSRS PHP Manager with Custom Learning Steps

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Demonstrates how to instantiate the FSRS Manager with custom learning and relearning steps, and how to disable fuzzing. This allows for fine-tuning the spaced repetition intervals based on specific learning requirements.

```php
// Custom learning steps
$customFsrs = new Manager(
    learningSteps: [1, 5, 15, 30],
    relearningSteps: [5, 15],
    enableFuzzing: false
);

```

--------------------------------

### Basic FSRS PHP Card Review Workflow

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Illustrates a typical card review process using the FSRS PHP library. It shows how to generate a schedule for a new card and then how to generate a subsequent schedule after a review with a specific rating and review date.

```php
$fsrs = new Manager();
$card = new Card(new DateTime('now', new DateTimeZone('UTC')));

// First review
$schedule = $fsrs->generateRepetitionSchedule($card);
$card = $schedule[3]->card; // Good rating

// Subsequent reviews
$reviewDate = new DateTime('2024-01-05', new DateTimeZone('UTC'));
$schedule = $fsrs->generateRepetitionSchedule($card, $reviewDate);
$card = $schedule[2]->card; // Hard rating

```

--------------------------------

### Initialize and Configure FSRS Manager

Source: https://context7.com/scottlaurent/fsrs/llms.txt

The Manager class serves as the primary interface for the FSRS algorithm. It allows for custom retention targets, model weights, and scheduling behavior, with support for exporting and restoring configurations.

```php
<?php

use Scottlaurent\FSRS\Manager;

// Default configuration (90% retention target)
$fsrs = new Manager();

// Custom configuration for stricter retention
$fsrs = new Manager(
    defaultRequestRetention: 0.85,      // 85% target retention rate
    weights: [                           // Custom model weights (17 parameters)
        0.4872, 1.4003, 3.7145, 13.8206, 5.1618, 1.2298, 0.8975, 0.031,
        1.6474, 0.1367, 1.0461, 2.1072, 0.0793, 0.3246, 1.587, 0.2272, 2.8755
    ],
    defaultMaximumInterval: 36500,       // Max 100 years between reviews
    learningSteps: [1, 5, 15, 30],       // Learning intervals in minutes
    relearningSteps: [5, 15],            // Relearning intervals in minutes
    enableFuzzing: true                  // Add randomness to prevent clustering
);

// Export configuration for storage
$config = $fsrs->toArray();

// Restore from saved configuration
$restoredFsrs = Manager::fromArray($config);
```

--------------------------------

### Manage Card States and Ratings in PHP

Source: https://context7.com/scottlaurent/fsrs/llms.txt

Demonstrates how to use the State and Rating classes to maintain type-safe code when handling flashcard lifecycle states and user performance feedback. It maps internal constants to human-readable labels for UI implementation.

```php
<?php

use Scottlaurent\FSRS\State;
use Scottlaurent\FSRS\Rating;
use Scottlaurent\FSRS\Card;
use Scottlaurent\FSRS\Manager;

$card = new Card();
if ($card->state === State::NEW) {
    echo "This is a new card\n";
}

$stateNames = [
    State::NEW => 'New',
    State::LEARNING => 'Learning',
    State::REVIEW => 'Review',
    State::RELEARNING => 'Relearning'
];
echo "Current state: " . $stateNames[$card->state] . "\n";

$fsrs = new Manager();
$schedule = $fsrs->generateRepetitionSchedule($card);

$againCard = $schedule[Rating::AGAIN]->card;
$hardCard = $schedule[Rating::HARD]->card;
$goodCard = $schedule[Rating::GOOD]->card;
$easyCard = $schedule[Rating::EASY]->card;

$ratingLabels = [
    Rating::AGAIN => 'Again - Forgot completely',
    Rating::HARD => 'Hard - Remembered with difficulty',
    Rating::GOOD => 'Good - Remembered with hesitation',
    Rating::EASY => 'Easy - Remembered perfectly'
];

foreach ($ratingLabels as $rating => $label) {
    $nextDue = $schedule[$rating]->card->due->format('Y-m-d');
    echo "$label -> Next: $nextDue\n";
}
```

--------------------------------

### Serialize and Restore Review Logs in PHP

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Demonstrates how to convert a ReviewLog object into array or JSON formats and how to reconstruct the object from those serialized states. This is essential for persisting review history in databases or external storage.

```php
$logData = $reviewLog->toArray();
$jsonString = $reviewLog->toJson();

$reviewLog = ReviewLog::fromArray($logData);
$reviewLog = ReviewLog::fromJson($jsonString);
```

--------------------------------

### FSRS ReviewLog Constructor Signature (PHP)

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Displays the constructor signature for the ReviewLog class, outlining its parameters for creating a new review log entry.

```php
new ReviewLog(
    int $rating,
    int $scheduledDays,
    int $elapsedDays,
    DateTime $review,
    int $state,
    ?string $cardId = null,
    ?DateTime $reviewDateTime = null,
    ?int $reviewDurationMs = null
)

```

--------------------------------

### Export and Restore FSRS Manager Configuration (PHP)

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Shows how to export the current FSRS Manager configuration to an array using toArray() and restore it from an array using the static fromArray() method.

```php
// Export configuration
$config = $fsrs->toArray();

// Restore from configuration
$fsrs = Manager::fromArray($config);

```

--------------------------------

### Generate Repetition Schedule for Card Reviews (PHP)

Source: https://context7.com/scottlaurent/fsrs/llms.txt

Calculates scheduling options for a given card based on four possible user ratings (Again, Hard, Good, Easy). It returns an array of scheduling options, allowing for previewing the outcome of each rating. Dependencies include the Manager and Card classes from the ScottlaurentFSRS library.

```php
<?php

use Scottlaurent\FSRS\Manager;
use Scottlaurent\FSRS\Card;

$fsrs = new Manager();
$card = new Card(new DateTime('2024-01-01', new DateTimeZone('UTC')));

// Generate all scheduling options
$schedule = $fsrs->generateRepetitionSchedule($card);

// Each key (1-4) represents a rating option
// 1 = Again (forgot), 2 = Hard, 3 = Good, 4 = Easy

foreach ([1 => 'Again', 2 => 'Hard', 3 => 'Good', 4 => 'Easy'] as $rating => $label) {
    $info = $schedule[$rating];
    $updatedCard = $info->card;
    $log = $info->reviewLog;

    echo "$label:\n";
    echo "  Due: " . $updatedCard->due->format('Y-m-d H:i:s') . "\n";
    echo "  Interval: " . $updatedCard->scheduledDays . " days\n";
    echo "  State: " . $updatedCard->state . "\n";
    echo "  Stability: " . round($updatedCard->stability, 2) . "\n";
    echo "  Difficulty: " . round($updatedCard->difficulty, 2) . "\n\n";
}

// Apply user's choice (e.g., user rated "Good")
$rating = 3;
$updatedCard = $schedule[$rating]->card;

// Generate next schedule at a specific date
$nextReviewDate = new DateTime('2024-01-05', new DateTimeZone('UTC'));
$nextSchedule = $fsrs->generateRepetitionSchedule($updatedCard, $nextReviewDate);

```

--------------------------------

### FSRS Card Constructor Signature (PHP)

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Presents the constructor signature for the FSRS Card class, detailing its optional parameters for initializing a new card.

```php
new Card(
    ?DateTime $due = null,
    float $stability = 0,
    float $difficulty = 0,
    int $reps = 0,
    int $lapses = 0,
    int $state = 0,
    ?DateTime $lastReview = null,
    int $step = 0,
    ?string $cardId = null
)

```

--------------------------------

### Export and Restore Card Data (PHP)

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Illustrates exporting Card data to an array or JSON string using toArray() and toJson(), and restoring it from data using static fromArray() and fromJson() methods.

```php
// Export card data
$cardData = $card->toArray();
$jsonString = $card->toJson();

// Restore from data
$card = Card::fromArray($cardData);
$card = Card::fromJson($jsonString);

```

--------------------------------

### Serialize and Deserialize Card Objects (PHP)

Source: https://context7.com/scottlaurent/fsrs/llms.txt

Demonstrates how to convert Card objects to array and JSON formats for storage and transmission, and how to reconstruct Card objects from these formats. Supports database storage, API transmission, and session persistence.

```php
<?php

use Scottlaurent\FSRS\Card;
use Scottlaurent\FSRS\State;

// Create a card with some history
$card = new Card(
    due: new DateTime('2024-01-15', new DateTimeZone('UTC')),
    stability: 8.5,
    difficulty: 4.2,
    reps: 10,
    lapses: 2,
    state: State::REVIEW,
    lastReview: new DateTime('2024-01-08', new DateTimeZone('UTC'))
);

// Export to array (for database storage)
$cardData = $card->toArray();
/*
[
    'cardId' => 'card_65abc...',
    'due' => '2024-01-15T00:00:00+00:00',
    'stability' => 8.5,
    'difficulty' => 4.2,
    'elapsedDays' => 0,
    'scheduledDays' => 0,
    'reps' => 10,
    'lapses' => 2,
    'state' => 2,
    'step' => 0,
    'lastReview' => '2024-01-08T00:00:00+00:00',
    'retrievability' => null
]
*/

// Store in database
// $db->insert('cards', $cardData);

// Restore from array
$restoredCard = Card::fromArray($cardData);
echo "Restored card due: " . $restoredCard->due->format('Y-m-d') . "\n";

// Export to JSON (for API responses)
$jsonString = $card->toJson();
echo $jsonString . "\n";

// Restore from JSON
$cardFromJson = Card::fromJson($jsonString);
echo "Card from JSON - Stability: " . $cardFromJson->stability . "\n";

// Example: Store and retrieve from session
$_SESSION['flashcard'] = $card->toJson();
$sessionCard = Card::fromJson($_SESSION['flashcard']);

```

--------------------------------

### FSRS Manager Constructor Signature (PHP)

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Shows the constructor signature for the FSRS Manager class, outlining its default parameters for creating a new manager instance.

```php
new Manager(
    float $defaultRequestRetention = 0.90,
    array $weights = [...],
    int $defaultMaximumInterval = 36500,
    array $learningSteps = [1, 10],
    array $relearningSteps = [10],
    bool $enableFuzzing = true
)

```

--------------------------------

### Perform Card Review with Rating Selection (PHP)

Source: https://context7.com/scottlaurent/fsrs/llms.txt

A convenience method that simplifies the process of reviewing a card by combining scheduling generation and rating selection into a single call. It returns both the updated card object and a review log. Dependencies include Manager, Card, and Rating classes from the ScottlaurentFSRS library.

```php
<?php

use Scottlaurent\FSRS\Manager;
use Scottlaurent\FSRS\Card;
use Scottlaurent\FSRS\Rating;

$fsrs = new Manager();
$card = new Card(new DateTime('now', new DateTimeZone('UTC')));

// Review a card with a rating
// Rating::AGAIN (1), Rating::HARD (2), Rating::GOOD (3), Rating::EASY (4)
$result = $fsrs->reviewCard(
    card: $card,
    rating: Rating::GOOD,                                      // User rated "Good"
    reviewDate: new DateTime('now', new DateTimeZone('UTC')),  // When review happened
    reviewDurationMs: 2500                                     // Review took 2.5 seconds
);

$updatedCard = $result['card'];
$reviewLog = $result['log'];

// Use the updated card for next review
echo "Next due: " . $updatedCard->due->format('Y-m-d H:i:s') . "\n";
echo "Interval: " . $updatedCard->scheduledDays . " days\n";

// Access review log metadata
echo "Rating given: " . $reviewLog->rating . "\n";
echo "Review time: " . $reviewLog->review->format('Y-m-d H:i:s') . "\n";
echo "Duration: " . $reviewLog->reviewDurationMs . "ms\n";

// Chain multiple reviews
$card = new Card();
$ratings = [Rating::GOOD, Rating::GOOD, Rating::HARD, Rating::EASY];

foreach ($ratings as $i => $rating) {
    $reviewDate = (new DateTime())->modify("+{$i} days");
    $result = $fsrs->reviewCard($card, $rating, $reviewDate);
    $card = $result['card'];

    echo "Review " . ($i + 1) . ": Next due in {$card->scheduledDays} days\n";
}

```

--------------------------------

### Advanced FSRS PHP Card Operations and Serialization

Source: https://github.com/scottlaurent/fsrs/blob/main/README.md

Covers advanced functionalities of the FSRS PHP library, including checking card retrievability, performing a review with timing data, serializing card objects to array and JSON formats, and restoring them.

```php
// Check card retrievability
$retrievability = $fsrs->getCardRetrievability($card);
echo "Recall probability: " . ($retrievability * 100) . "%\n";

// Review card with timing data
$result = $fsrs->reviewCard($card, 3, new DateTime(), 2500);
$updatedCard = $result['card'];
$reviewLog = $result['log'];

// Serialize card data
$cardData = $card->toArray();
$cardJson = $card->toJson();

// Restore from serialized data
$restoredCard = Card::fromArray($cardData);
$cardFromJson = Card::fromJson($cardJson);

```

--------------------------------

### Serialize and Deserialize ReviewLog Objects (PHP)

Source: https://context7.com/scottlaurent/fsrs/llms.txt

Shows how to convert ReviewLog objects into array and JSON formats for data persistence and how to reconstruct ReviewLog objects from these serialized formats. Useful for analytics and debugging review sessions.

```php
<?php

use Scottlaurent\FSRS\ReviewLog;
use Scottlaurent\FSRS\State;
use Scottlaurent\FSRS\Rating;

// Create a review log manually
$reviewLog = new ReviewLog(
    rating: Rating::GOOD,                                     // User's rating (1-4)
    scheduledDays: 7,                                          // Days since last scheduled
    elapsedDays: 8,                                            // Actual days elapsed
    review: new DateTime('2024-01-15', new DateTimeZone('UTC')),
    state: State::REVIEW,                                      // Card state at review time
    cardId: 'card_abc123',                                     // Link to card
    reviewDateTime: new DateTime('2024-01-15 14:30:00', new DateTimeZone('UTC')),
    reviewDurationMs: 3500                                     // 3.5 seconds to respond
);

// Access review log properties
echo "Rating: " . $reviewLog->rating . "\n";
echo "Card ID: " . $reviewLog->cardId . "\n";
echo "Duration: " . $reviewLog->reviewDurationMs . "ms\n";
echo "Scheduled: " . $reviewLog->scheduledDays . " days\n";
echo "Actual: " . $reviewLog->elapsedDays . " days\n";

// Serialize for storage
$logData = $reviewLog->toArray();
$jsonLog = $reviewLog->toJson();

// Restore from storage
$restoredLog = ReviewLog::fromArray($logData);
$logFromJson = ReviewLog::fromJson($jsonLog);

// Store review history in database
$reviews = [];
$reviews[] = $reviewLog->toArray();
// $db->insert('review_logs', $reviewLog->toArray());

// Analyze review patterns
$avgDuration = array_sum(array_column($reviews, 'reviewDurationMs')) / count($reviews);
echo "Average review time: " . round($avgDuration) . "ms\n";

```

--------------------------------

### Create and Manage Flashcards with Card Class

Source: https://context7.com/scottlaurent/fsrs/llms.txt

The Card class tracks the memory state of individual items. It supports instantiation with default values or full parameter sets for restoring existing card data from a database.

```php
<?php

use Scottlaurent\FSRS\Card;
use Scottlaurent\FSRS\State;

// Create a new card (defaults to current time)
$card = new Card();

// Create card with specific due date
$card = new Card(
    due: new DateTime('2024-01-01', new DateTimeZone('UTC'))
);

// Create card with full parameters (for restoring from database)
$card = new Card(
    due: new DateTime('2024-01-15', new DateTimeZone('UTC')),
    stability: 4.5,           // Memory stability value
    difficulty: 5.2,          // Card difficulty (1-10 scale)
    elapsedDays: 3,           // Days since last review
    scheduledDays: 7,         // Days until next review
    reps: 5,                  // Total review count
    lapses: 1,                // Times forgotten
    state: State::REVIEW,     // Current state (0=New, 1=Learning, 2=Review, 3=Relearning)
    step: 0,                  // Learning step index
    lastReview: new DateTime('2024-01-08', new DateTimeZone('UTC')),
    cardId: 'card_abc123'     // Optional custom ID
);

// Access card properties
echo "Due: " . $card->due->format('Y-m-d H:i:s') . "\n";
echo "State: " . $card->state . "\n";           // 0, 1, 2, or 3
echo "Stability: " . $card->stability . "\n";    // Higher = longer intervals
echo "Difficulty: " . $card->difficulty . "\n";  // 1-10 scale
echo "Repetitions: " . $card->reps . "\n";
echo "Lapses: " . $card->lapses . "\n";
echo "Card ID: " . $card->cardId . "\n";
```

--------------------------------

### Calculate Card Recall Probability (PHP)

Source: https://context7.com/scottlaurent/fsrs/llms.txt

Calculates the probability of successfully recalling a card at a specific point in time. This is useful for visualizing memory strength or optimizing review order. It requires the Manager, Card, and State classes from the ScottlaurentFSRS library. New cards have a retrievability of 0.0.

```php
<?php

use Scottlaurent\FSRS\Manager;
use Scottlaurent\FSRS\Card;
use Scottlaurent\FSRS\State;

$fsrs = new Manager();

// Create a card that has been reviewed
$card = new Card(
    due: new DateTime('2024-01-10', new DateTimeZone('UTC')),
    stability: 10.0,
    difficulty: 5.0,
    state: State::REVIEW,
    lastReview: new DateTime('2024-01-01', new DateTimeZone('UTC'))
);

// Get retrievability at current time
$retrievability = $fsrs->getCardRetrievability($card);
echo "Current recall probability: " . round($retrievability * 100, 1) . "%\n";

// Get retrievability at a specific future date
$futureDate = new DateTime('2024-01-15', new DateTimeZone('UTC'));
$futureRetrievability = $fsrs->getCardRetrievability($card, $futureDate);
echo "Future recall probability: " . round($futureRetrievability * 100, 1) . "%\n";

// Track retrievability decay over time
echo "\nRetrievability decay:\n";
for ($days = 0; $days <= 30; $days += 5) {
    $checkDate = (new DateTime('2024-01-01', new DateTimeZone('UTC')))->modify("+{$days} days");
    $r = $fsrs->getCardRetrievability($card, $checkDate);
    echo "Day $days: " . round($r * 100, 1) . "%\n";
}

// Note: New cards always return 0.0 retrievability
$newCard = new Card();
$r = $fsrs->getCardRetrievability($newCard);
echo "\nNew card retrievability: " . $r . "\n"; // Output: 0

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.