README

A PHP library for handling scripture ranges with exclusions and JSON serialization. Create complex scripture ranges with a clean, fluent API.

Installation

composer require bkuhl/scripture-ranges

Creating Ranges (Recommended)

Use the ScriptureRangeBuilder with multiple syntax options:

use BKuhl\ScriptureRanges\ScriptureRangeBuilder;
use BKuhl\ScriptureRanges\ChapterRange;

$builder = new ScriptureRangeBuilder([$myBookResolver]);

// 1. Traditional parameter syntax
$collection = $builder
    ->with(BookEnum::JOHN, chapter: 3, verse: 1, toVerse: 36)
    ->without(BookEnum::JOHN, chapter: 3, verse: 16, toVerse: 17)
    ->build();

// 2. Chapter range syntax
$collection = $builder
    ->with(BookEnum::JOHN, chapter: 3, chapterEnd: 5)      // Multiple chapters
    ->with('Matthew', chapter: 5, verse: 1, toVerse: 48)   // Mixed with verse ranges
    ->build();

// 3. ChapterRange object syntax (cleanest for chapter ranges!)
$collection = $builder
    ->with(BookEnum::JOHN, ChapterRange::range(3, 5))      // Chapters 3-5
    ->with('Matthew', chapter: 5, verse: 1, toVerse: 48)   // Use traditional syntax for verses
    ->without(BookEnum::JOHN, chapter: 3, verse: 16)       // Use traditional syntax for single verses
    ->build();

// ChapterRange factory method:
ChapterRange::range(3, 5)             // Chapters 3-5 (full chapters)

Book Resolvers

To use flexible input types (strings, enums, integers), implement a BookResolverInterface:

use BKuhl\ScriptureRanges\Interfaces\BookResolverInterface;

class MyBookResolver implements BookResolverInterface
{
    public function resolve(mixed $book): BookInterface
    {
        if (is_string($book)) {
            return $this->getBookFromString($book);
        }
        
        if ($book instanceof MyBookEnum) {
            return $this->getBookFromEnum($book);
        }
        
        throw new InvalidArgumentException('Unable to resolve book');
    }

    public function canResolve(mixed $book): bool
    {
        return is_string($book) || $book instanceof MyBookEnum;
    }
}

// Use with builder
$builder = new ScriptureRangeBuilder([$myResolver]);

Working with Collections

// Create a collection with ID and name
$collection = new RangeCollection('reading-plan-123', 'Daily Reading');

// Or create without metadata
$collection = new RangeCollection();

// Set or update name and ID
$collection->setName('Morning Reading');
$collection->setId('morning-plan-456');

// Get name and ID
echo $collection->getName(); // "Morning Reading"
echo $collection->getId();   // "morning-plan-456"

// Check if a verse is in any range
echo $collection->contains($verse); // true/false

// Get formatted reference
echo $collection->reference(); // "John 3:16-17, Matthew 5:1-12"

// JSON serialization includes name and ID
$json = $collection->toJson();
// {
//   "name": "Morning Reading",
//   "id": "morning-plan-456", 
//   "ranges": [...]
// }

ChapterRange Quick Example

For working with chapter ranges, use the ChapterRange class:

use BKuhl\ScriptureRanges\ChapterRange;

// Create a chapter range
$range = ChapterRange::range(3, 5);  // Chapters 3-5

// Get start and end chapters
$start = $range->getStart();  // 3
$end = $range->getEnd();      // 5

// Use with ScriptureRangeBuilder
$collection = $builder
    ->with($book, ChapterRange::range(1, 3))    // Full chapters 1-3
    ->with($book, chapter: 4, verse: 1, toVerse: 10)  // Specific verses
    ->build();

Combining Ranges

Combine multiple ranges in the same book into a single range:

use BKuhl\ScriptureRanges\ScriptureRange;

$range1 = new ScriptureRange($book, 1, 2, 1, 25);
$range2 = new ScriptureRange($book, 3, 4, 1, 24);

$combined = ScriptureRange::combine([$range1, $range2]);
// Result: Genesis 1-4 with gaps between ranges excluded

Checking Consecutive Chapters

Check if ranges contain a minimum number of consecutive full chapters:

// Check a single range
$range = new ScriptureRange($book, 1, 3, 1, 24);
$range->hasConsecutiveChapters(3); // true if chapters 1, 2, 3 are all full

// Check across multiple ranges in a collection
$collection = (new ScriptureRangeBuilder())
    ->with($book, chapter: 1, chapterEnd: 2)
    ->with($book, chapter: 3, chapterEnd: 4)
    ->build();

$collection->hasConsecutiveChapters(4); // true if chapters 1-4 are all full across ranges