Storage Lifecycle Management

Purpose and Scope

This document explains how Telescope's ListensForStorageOpportunities trait determines when to start recording entries and when to trigger their storage to the repository. The trait provides the critical lifecycle management that bridges application events with Telescope's recording system across three execution contexts: HTTP requests, console commands, and queue jobs.

For details on the recording and storage mechanisms themselves, see Telescope Core System. For information on context-scoped state management and batch IDs, see Context and Batch Management. For repository implementations, see Repository Pattern.

Overview

The ListensForStorageOpportunities trait is mixed into the Telescope class src/Telescope.php33 and provides methods that register event listeners to detect when the application begins and ends various execution contexts. The trait ensures that:

1. Recording starts when an appropriate execution context begins
2. Storage is triggered when that context completes
3. Nested contexts (e.g., jobs dispatched during requests) are handled correctly
4. Developers can customize when Telescope should listen

Sources: src/ListensForStorageOpportunities.php1-177 src/Telescope.php29-34

Core Responsibilities

The trait provides three main methods registered by TelescopeServiceProvider:

Method	Purpose	Registered By
recordEntriesForRequests()	Starts recording when HTTP requests arrive	TelescopeServiceProvider::boot()
manageRecordingStateForCommands()	Starts/stops recording for console commands	TelescopeServiceProvider::boot()
storeEntriesAfterWorkerLoop()	Manages recording lifecycle for queue jobs	TelescopeServiceProvider::boot()

The central registration point is listenForStorageOpportunities() src/ListensForStorageOpportunities.php33-38 which invokes all three methods to set up the complete lifecycle management system.

Sources: src/ListensForStorageOpportunities.php33-38 src/TelescopeServiceProvider.php54-56

Execution Context Detection

HTTP Request Lifecycle

The HTTP request lifecycle begins when RequestReceived event fires src/ListensForStorageOpportunities.php66 The registered listener:

1. Checks if listening should occur via shouldListen() src/ListensForStorageOpportunities.php67
2. Validates the URI using requestIsToApprovedUri() src/ListensForStorageOpportunities.php68 to exclude ignored paths
3. Starts recording by calling Telescope::startRecording() src/ListensForStorageOpportunities.php70

Once recording starts, the deferred storage mechanism (registered in Telescope::record() src/Telescope.php286-289) automatically triggers at request completion. No explicit listener for RequestHandled or termination events is needed because Hyperf's defer() function handles this.

Sources: src/ListensForStorageOpportunities.php63-73 src/Telescope.php216-234 src/Telescope.php579-591

Console Command Lifecycle

Console commands follow a synchronous lifecycle with explicit start and stop points:

1. BeforeHandleCommand event src/ListensForStorageOpportunities.php81 triggers the start listener:

   • Checks shouldListen() and runningApprovedArtisanCommand() src/ListensForStorageOpportunities.php82-83
   • Calls Telescope::startRecording() src/ListensForStorageOpportunities.php85 if approved

2. AfterExecuteCommand event src/ListensForStorageOpportunities.php89 triggers the completion listener:

   • Directly calls Telescope::store() src/ListensForStorageOpportunities.php90-92 with the repository
   • No conditional checks needed - storage is safe even if no entries were recorded

The approved command check uses Telescope::runningApprovedArtisanCommand() src/Telescope.php140-161 which excludes commands like migrate:rollback, queue:work, and those in the telescope.ignore_commands configuration.

Sources: src/ListensForStorageOpportunities.php78-94 src/Telescope.php140-161

Queue Job Lifecycle with Nesting Support

Queue jobs require sophisticated tracking because jobs can dispatch other jobs, creating nested execution contexts. The trait maintains a stack in Context::get(PROCESSING_JOBS) src/ListensForStorageOpportunities.php23 to track the nesting level.

Job Processing Stack Management:

Event	Action	Method	Stack Operation
JobProcessing	Start recording (if sync connection)	addProcessingJob()	Push true onto stack
JobProcessed	Store if stack becomes empty	storeIfDoneProcessingJob()	Pop from stack
JobFailed	Store if stack becomes empty	storeIfDoneProcessingJob()	Pop from stack
JobExceptionOccurred	Pop without storage	popProcessingJob()	Pop from stack

Event Listener Registration src/ListensForStorageOpportunities.php133-163:

JobProcessing event:
 → Check shouldListen() && connectionName !== 'sync'
 → startRecording()
 → addProcessingJob()

JobProcessed/JobFailed events:
 → Check shouldListen()
 → storeIfDoneProcessingJob()
 → popProcessingJob()
 → if stack empty && connectionName !== 'sync':
 → store(repository)
 → stopRecording()

JobExceptionOccurred event:
 → Check shouldListen()
 → popProcessingJob() (no storage)

The sync connection is explicitly excluded src/ListensForStorageOpportunities.php137 because synchronous jobs execute within the same request context and should not trigger separate recording/storage cycles.

Sources: src/ListensForStorageOpportunities.php99-176

Context-Scoped State Keys

The trait defines and manages one context key for job tracking:

Context Key	Type	Purpose
PROCESSING_JOBS	array	Stack of boolean flags tracking nested job execution depth

This key is defined at src/ListensForStorageOpportunities.php23 and accessed via:

• getProcessingJobs() src/ListensForStorageOpportunities.php99-102 - Retrieves current stack
• addProcessingJob() src/ListensForStorageOpportunities.php107-115 - Pushes onto stack
• popProcessingJob() src/ListensForStorageOpportunities.php120-128 - Pops from stack

The trait also triggers the setting of keys defined in the Telescope class:

• SHOULD_RECORD - Set via startRecording() src/Telescope.php231
• BATCH_ID - Set via getBatchId() src/Telescope.php233

Sources: src/ListensForStorageOpportunities.php23 src/ListensForStorageOpportunities.php99-128

Customizable Listening Behavior

The shouldListen() Callback Mechanism

Developers can customize when Telescope listens for storage opportunities using the shouldListenUsing() method src/ListensForStorageOpportunities.php43-46:

The shouldListen() method src/ListensForStorageOpportunities.php51-58 is called by all three lifecycle methods before initiating recording:

1. recordEntriesForRequests() checks it at src/ListensForStorageOpportunities.php67
2. manageRecordingStateForCommands() checks it at src/ListensForStorageOpportunities.php82
3. storeEntriesAfterWorkerLoop() checks it at src/ListensForStorageOpportunities.php137 src/ListensForStorageOpportunities.php144 src/ListensForStorageOpportunities.php151 src/ListensForStorageOpportunities.php158

If no callback is set, shouldListen() returns true by default src/ListensForStorageOpportunities.php54 enabling recording for all execution contexts.

Sources: src/ListensForStorageOpportunities.php43-58 src/ListensForStorageOpportunities.php67 src/ListensForStorageOpportunities.php82

Integration with Core Recording System

Method Call Chain from Lifecycle to Storage

The trait works in concert with Telescope core methods:

1. Lifecycle trait detects execution context and calls Telescope::startRecording() src/Telescope.php216-234
2. startRecording() sets SHOULD_RECORD context flag to true src/Telescope.php231
3. Watchers check Telescope::isRecording() src/Telescope.php263-270 and call recordX() methods
4. record() method src/Telescope.php275-319 queues entries and schedules deferred storage on first entry src/Telescope.php286-289
5. Deferred callback or explicit store() calls executeStore() src/Telescope.php596-637 which persists to repository

Sources: src/ListensForStorageOpportunities.php70 src/ListensForStorageOpportunities.php90-92 src/Telescope.php216-234 src/Telescope.php263-270 src/Telescope.php275-319 src/Telescope.php579-637

Summary of Trait Methods

Method	Visibility	Purpose	Called By
listenForStorageOpportunities()	public static	Main entry point; registers all lifecycle listeners	TelescopeServiceProvider::boot()
shouldListenUsing()	public static	Sets custom callback for determining when to listen	Application code (optional)
shouldListen()	public static	Evaluates if Telescope should listen in current context	All lifecycle methods
recordEntriesForRequests()	public static	Registers HTTP request lifecycle listener	listenForStorageOpportunities()
manageRecordingStateForCommands()	public static	Registers console command lifecycle listeners	listenForStorageOpportunities()
storeEntriesAfterWorkerLoop()	protected static	Registers queue job lifecycle listeners	listenForStorageOpportunities()
getProcessingJobs()	protected static	Retrieves current job processing stack	storeIfDoneProcessingJob()
addProcessingJob()	protected static	Pushes onto job processing stack	JobProcessing event listener
popProcessingJob()	protected static	Pops from job processing stack	JobProcessed, JobFailed, JobExceptionOccurred listeners
storeIfDoneProcessingJob()	protected static	Triggers storage when job stack becomes empty	JobProcessed, JobFailed event listeners

Sources: src/ListensForStorageOpportunities.php1-177