Repository Pattern

Purpose and Scope

This document describes Telescope's repository pattern implementation, which provides an abstraction layer over the data storage mechanism. The repository pattern separates business logic from data persistence concerns, allowing Telescope to support multiple storage drivers while maintaining a consistent interface.

For information about the underlying database schema structure, see Database Schema. For details on how entries flow through the system before reaching storage, see Telescope Facade.

---

Repository Contracts

Telescope defines three distinct repository interfaces that segregate storage responsibilities by functional area. This follows the Interface Segregation Principle, allowing consuming code to depend only on the capabilities it needs.

Interface Overview

Contract	Purpose	Primary Consumer
EntriesRepository	Create, read, update entries	Telescope facade
ClearableRepository	Delete all entries	telescope:clear command
PrunableRepository	Remove old entries	telescope:prune command

EntriesRepository

The EntriesRepository interface is the primary contract for entry storage and retrieval operations. It is used by the Telescope facade to persist monitored data.

Key Methods:

• store(Collection $entries) - Persists a batch of entries
• update(Collection $updates) - Updates existing entry content
• find(string $id) - Retrieves a single entry by UUID
• get(string $type, EntryQueryOptions $options) - Queries entries by type with filtering

The interface is defined in src/Contracts/EntriesRepository.php (file not provided but referenced in service provider).

ClearableRepository

The ClearableRepository interface provides a single method for removing all Telescope data from storage:

This interface is used exclusively by the telescope:clear console command to completely purge monitoring data.

Sources: src/Contracts/ClearableRepository.php1-14

PrunableRepository

The PrunableRepository interface handles selective deletion of old entries:

The method accepts a cutoff timestamp and returns the count of deleted entries. The $keepExceptions parameter allows exception entries to be preserved even when pruning other old data.

Sources: Referenced in src/Console/PruneCommand.php26-28

---

DatabaseEntriesRepository Implementation

The DatabaseEntriesRepository class is the concrete implementation of all three repository contracts. It uses the database driver to persist entries to the telescope_entries and telescope_entries_tags tables.

Implementation Architecture

Sources: src/TelescopeServiceProvider.php163-178

Storage Operations

The DatabaseEntriesRepository performs several key operations:

Entry Storage:

• Batches entries into chunks (configured via storage.database.chunk)
• Inserts entries with JSON-encoded content
• Bulk inserts associated tags
• Handles duplicate entries by updating content on conflict

Entry Updates:

• Updates existing entry content and metadata
• Used for entries that require post-processing (e.g., HTTP client requests)

Entry Retrieval:

• Joins telescope_entries with telescope_entries_tags for filtering
• Supports pagination through EntryQueryOptions
• Filters by entry type, batch ID, tags, and family hash

Data Cleanup:

• clear() truncates all three tables
• prune() deletes entries older than specified timestamp
• Respects exception preservation flag

Sources: Implementation details referenced from src/TelescopeServiceProvider.php163-178

---

Service Registration

The repository binding occurs during the service provider's registration phase, establishing the dependency injection mappings before the application boots.

Registration Flow

Sources: src/TelescopeServiceProvider.php112-179

Driver Selection Logic

The service provider uses a convention-based approach to register storage drivers:

1. Reads telescope.driver configuration value (defaults to 'database')
2. Checks for method named register{Driver}Driver() using reflection
3. Calls the driver-specific registration method if it exists
4. For database driver, binds all three interfaces to DatabaseEntriesRepository

This design allows future storage drivers (e.g., Redis, Elasticsearch) to be added by implementing the registration method without modifying existing code.

Implementation:

src/TelescopeServiceProvider.php150-158 - Driver selection logic

src/TelescopeServiceProvider.php163-179 - Database driver registration

Sources: src/TelescopeServiceProvider.php150-179

---

Usage Patterns

Telescope Facade Integration

The Telescope facade injects EntriesRepository to persist entries during the storage phase:

Entry Storage Flow:

1. Facade collects entries in coroutine context queues
2. At end of request/coroutine, store() method is called
3. Repository batches entries and inserts into database
4. Tags are bulk-inserted with foreign key references
5. Updates queue is processed for modified entries

The facade does not directly instantiate the repository; it receives it through dependency injection, allowing the storage mechanism to be swapped without modifying the facade code.

Sources: Referenced from architecture diagrams

Console Commands

Console commands demonstrate clear separation of concerns through interface dependency:

ClearCommand:

• Depends only on ClearableRepository interface
• Calls single clear() method
• Independent of storage implementation details

src/Console/ClearCommand.php25-29

PruneCommand:

• Depends only on PrunableRepository interface
• Passes configurable retention period via options
• Receives count of pruned entries for user feedback

src/Console/PruneCommand.php26-28

Sources: src/Console/ClearCommand.php25-29 src/Console/PruneCommand.php26-28

---

Repository Dependencies by Consumer

The following table shows which components depend on each repository interface:

Component	Repository Interface	Usage
Telescope::store()	EntriesRepository	Persist monitored entries
Telescope::update()	EntriesRepository	Update entry content
ClearCommand	ClearableRepository	Delete all data
PruneCommand	PrunableRepository	Remove old entries
Dashboard controllers	EntriesRepository	Query entries for API

Dependency Graph

Sources: src/TelescopeServiceProvider.php163-179 src/Console/ClearCommand.php25 src/Console/PruneCommand.php26

---

Extension Points

The repository pattern design supports future extensibility:

Alternative Storage Drivers:

• Implement the three repository interfaces
• Add register{DriverName}Driver() method to service provider
• Set telescope.driver configuration to new driver name

Custom Query Capabilities:

• Extend EntriesRepository with additional query methods
• Implement in DatabaseEntriesRepository or custom repository
• Maintain backward compatibility with existing interface

Storage Optimization:

• Replace repository implementation without changing consumers
• Add caching layer between interface and implementation
• Implement write-behind patterns for high-volume scenarios

Sources: src/TelescopeServiceProvider.php150-158