Property Extraction Utilities

Purpose and Scope

This document covers the ExtractProperties utility class, which provides a mechanism for safely extracting and formatting object properties for storage in Telescope. This utility is used throughout the watcher system whenever object data needs to be captured and persisted. For information about the data structures that utilize this utility, see IncomingEntry and EntryResult.

Overview

The ExtractProperties class provides a single static method that uses PHP reflection to extract all properties from an object and format them into an array suitable for JSON serialization and database storage. The utility handles various scenarios including uninitialized properties, Eloquent models, nested objects, and primitive values.

Class Location: src/ExtractProperties.php11-44

Primary Method: ExtractProperties::from(mixed $target): array

The extracted properties are returned as an associative array where keys are property names and values are formatted representations of the property values.

Sources: src/ExtractProperties.php1-45

Property Extraction Process

The extraction process follows a multi-step pipeline that leverages Hyperf's Collection class for functional data manipulation. The following diagram illustrates the complete extraction flow:

Sources: src/ExtractProperties.php18-43

Step-by-Step Breakdown

Step	Code Reference	Description
1. Reflection	src/ExtractProperties.php20	Uses ReflectionClass to introspect the target object and retrieve all declared properties
2. Collection Creation	src/ExtractProperties.php20	Wraps properties in a Hyperf\Collection\Collection for functional operations
3. Property Iteration	src/ExtractProperties.php21	Uses mapWithKeys() to transform each property into a key-value pair
4. Accessibility	src/ExtractProperties.php22	Calls setAccessible(true) to access private and protected properties
5. Initialization Check	src/ExtractProperties.php24-26	For PHP 7.4+, skips uninitialized typed properties to avoid errors
6. Value Extraction	src/ExtractProperties.php28	Retrieves the property value from the target object
7. Type-Specific Formatting	src/ExtractProperties.php28-41	Applies different formatting strategies based on value type
8. Array Conversion	src/ExtractProperties.php42	Converts the collection to a plain PHP array

Sources: src/ExtractProperties.php18-43

Type Handling Strategies

The utility employs three distinct strategies for handling different value types, ensuring that all data is normalized into a JSON-serializable format.

Model Instance Handling

When a property value is an instance of Hyperf\Database\Model\Model, the utility delegates to the FormatModel::given() method:

Code Reference: src/ExtractProperties.php28-29

This delegation ensures consistent formatting of Eloquent models across all Telescope watchers. The FormatModel utility (defined elsewhere in the codebase) extracts the model's class name, key, and relevant attributes.

Sources: src/ExtractProperties.php28-29

Object Handling

For non-model objects, the utility first checks for a custom formatting method, then falls back to JSON serialization:

Code Reference: src/ExtractProperties.php31-39

The resulting structure is:

This dual-key structure preserves both the object's type information and its internal state.

Sources: src/ExtractProperties.php31-39

Primitive Value Handling

For scalar values (strings, integers, booleans, arrays, etc.), the utility applies a JSON encode/decode cycle:

Code Reference: src/ExtractProperties.php41

Rationale: The JSON encode/decode cycle normalizes all values into JSON-compatible types, converting:

• Resource types to null
• Special float values (INF, NAN) to null
• Objects implementing JsonSerializable to their serialized form

Sources: src/ExtractProperties.php41

Uninitialized Property Handling

PHP 7.4 introduced typed properties, which can be in an uninitialized state. Attempting to read an uninitialized typed property throws a TypeError. The utility detects this condition and skips such properties:

Code Reference: src/ExtractProperties.php24-26

By returning an empty array for uninitialized properties, they are excluded from the final result via mapWithKeys(), which filters out empty results.

Sources: src/ExtractProperties.php24-26

Integration with the Telescope System

The ExtractProperties utility is used throughout the Telescope codebase wherever object inspection is required. Common usage patterns include:

Usage Context

Context	Purpose	Example Watchers
Exception Capturing	Extract properties from exception objects for debugging	ExceptionWatcher
Event Monitoring	Capture event object state	EventWatcher
Job Inspection	Extract job payload and properties	JobWatcher
Model Auditing	Capture model state changes	ModelWatcher
Custom Objects	Any watcher needing to inspect application-specific objects	All watchers

The utility is particularly valuable when watchers encounter user-defined classes or framework objects that need to be persisted to the database.

Sources: src/ExtractProperties.php1-45

Custom Formatting Support

Objects can implement a formatForTelescope() method to provide custom formatting logic. This allows application code to control exactly what data is exposed to Telescope:

Method Signature: public function formatForTelescope(): array

Example Use Case: A class containing sensitive data (passwords, tokens) can implement this method to return a sanitized version of its properties:

When ExtractProperties::from() encounters such an object, it will call formatForTelescope() instead of performing automatic JSON serialization, giving the object full control over its Telescope representation.

Code Reference: src/ExtractProperties.php35-36

Sources: src/ExtractProperties.php31-39

Data Flow Summary

The following diagram shows how ExtractProperties fits into the broader Telescope data collection pipeline:

Sources: src/ExtractProperties.php1-45

Performance Considerations

The utility uses PHP reflection, which has performance implications:

Consideration	Impact	Mitigation
Reflection Overhead	Reflection operations are slower than direct property access	Only used during recording, not on production hot paths
Property Count	More properties = longer extraction time	Watchers should use this selectively, not on every object
Nested Objects	Deep object graphs can be expensive to serialize	Consider implementing formatForTelescope() to limit depth
Memory Usage	JSON encode/decode creates temporary strings	Acceptable for debugging/monitoring use case

Since Telescope recording can be disabled in production (via configuration), the performance impact is limited to development and debugging scenarios where the overhead is acceptable.

Sources: src/ExtractProperties.php1-45