telescope:publish

Purpose and Scope

The telescope:publish command deploys Telescope's configuration files and frontend assets from the package vendor directory to the application's public directories, making them accessible for customization and serving. This command is typically executed during initial Telescope installation and when updating to new versions that include asset changes.

For information about other Telescope management commands, see Management Commands Overview.

Sources: src/Console/PublishCommand.php1-36

---

Command Overview

The PublishCommand class provides a single console command that publishes two categories of Telescope resources by delegating to Hypervel's vendor:publish infrastructure. It extends Hypervel\Console\Command and orchestrates the deployment of both configuration and frontend assets.

Sources: src/Console/PublishCommand.php9-36

---

Command Signature and Options

The command is invoked with the following signature:

telescope:publish {--force : Overwrite any existing files}

Command Name

• telescope:publish: The command identifier registered in the console kernel

Options

Option	Type	Required	Description
--force	Flag	No	Forces overwriting of existing files during configuration publishing

Sources: src/Console/PublishCommand.php14

---

Execution Flow

The handle() method executes a two-phase publishing process:

Phase 1: Configuration Publishing

src/Console/PublishCommand.php26-29

This phase publishes the configuration file with conditional overwriting:

• Tag: telescope-config
• Force behavior: Respects the --force option passed by the user
• If --force is not provided and config/telescope.php exists, the existing file is preserved

Phase 2: Asset Publishing

src/Console/PublishCommand.php31-34

This phase publishes frontend assets with automatic overwriting:

• Tag: telescope-assets
• Force behavior: Always true, regardless of user input
• Ensures users always receive the latest JavaScript, CSS, and other static files
• Critical for compatibility when upgrading Telescope versions

Sources: src/Console/PublishCommand.php24-35

---

Published Resources

Configuration Files

Tag: telescope-config

The configuration publishing deploys a single file:

Source	Destination	Overwrite Behavior
vendor/hypervel/telescope/config/telescope.php	config/telescope.php	Conditional (respects --force flag)

This file contains all Telescope settings including watcher configuration, filtering rules, storage settings, and middleware configuration. For detailed configuration options, see Core Settings and Watcher Configuration.

Frontend Assets

Tag: telescope-assets

The asset publishing deploys the complete Vue.js single-page application:

Source	Destination	Overwrite Behavior
vendor/hypervel/telescope/public/vendor/telescope/*	public/vendor/telescope/*	Always overwrites

Assets include:

• app.js: Compiled Vue.js application bundle
• app.css: Compiled stylesheet bundle
• mix-manifest.json: Laravel Mix asset versioning manifest
• Additional static resources (fonts, images, etc.)

The forced overwriting ensures users always receive the correct frontend version matching their installed Telescope package version, preventing compatibility issues.

Sources: src/Console/PublishCommand.php26-34

---

Use Cases

Initial Installation

When first installing Telescope in an application, run the publish command to deploy both configuration and assets:

This creates config/telescope.php for customization and deploys the web interface to public/vendor/telescope/.

Upgrading Telescope Versions

After upgrading the Telescope package via Composer, republish to ensure frontend assets match the new version:

The --force flag ensures any customized configuration file is also updated. Review the new configuration template and merge any custom settings.

Recovering Default Configuration

If the configuration file becomes corrupted or requires reset, republish with force:

Warning: This overwrites any custom configuration settings. Back up customizations before forcing a republish.

Asset Redeployment

If frontend assets are accidentally deleted or corrupted, republish without force to restore them while preserving custom configuration:

Assets are always redeployed regardless of the --force flag.

Sources: src/Console/PublishCommand.php1-36

---

Integration with vendor:publish System

The PublishCommand relies on Hypervel's vendor:publish infrastructure, which provides a standardized mechanism for deploying package resources. During Telescope's service provider registration, publishable resources are tagged and registered with the framework.

Registration Process

The TelescopeServiceProvider registers publishable resources during the boot phase using the publishes() method. This establishes the mapping between source files in the vendor directory and their destination paths in the application directory.

For configuration:

For assets:

Resolution Process

When PublishCommand::handle() calls vendor:publish with a specific tag, the framework:

1. Looks up all resources registered under that tag
2. Determines source and destination paths
3. Checks for existing destination files
4. Applies force/conditional overwrite logic
5. Copies files to their destinations
6. Reports success or conflicts

This abstraction allows Telescope to leverage framework-level publishing capabilities without implementing custom file copying logic.

Sources: src/Console/PublishCommand.php9-36

---

Relationship to Other Commands

The telescope:publish command complements other Telescope management commands:

Command	Relationship	Use Together
telescope:clear	Independent	Clear old data before republishing configuration with different retention settings
telescope:pause	Independent	Pause recording before republishing to avoid capturing deployment activity
telescope:resume	Independent	Resume recording after republishing and verifying configuration
telescope:prune	Independent	Prune entries using old retention settings before republishing with new settings

While these commands can be used in sequence during deployment, each operates independently on different aspects of the Telescope system.

Sources: src/Console/PublishCommand.php1-36