plugin-check / includes / Traits / File_Editor_URL.php

File_Editor_URL.php in Plugin Check (PCP) trunk, at includes/Traits/File_Editor_URL.php

182 lines 5.7 KB

Raw Download Zip

1	<?php
2	/**
3	* Trait WordPress\Plugin_Check\Traits\File_Editor_URL
4	*
5	* @package plugin-check
6	*/
7
8	namespace WordPress\Plugin_Check\Traits;
9
10	use WordPress\Plugin_Check\Checker\Check_Result;
11
12	/**
13	* Trait for file editor URL.
14	*
15	* @since 1.0.0
16	*/
17	trait File_Editor_URL {
18
19	/**
20	* Gets the URL for opening the plugin file in an external editor.
21	*
22	* @since 1.0.0
23	*
24	* @param Check_Result $result The check result to amend, including the plugin context to check.
25	* @param string $filename Error file name.
26	* @param int $line Optional. Line number of error. Default 0 (no specific line).
27	* @return string\|null File editor URL or null if not available.
28	*
29	* @SuppressWarnings(PHPMD.NPathComplexity)
30	* @SuppressWarnings(PHPMD.ExcessiveMethodLength)
31	*/
32	protected function get_file_editor_url( Check_Result $result, $filename, $line = 0 ) {
33
34	$edit_url = null;
35	$line = (int) $line;
36
37	$plugin_path = $result->plugin()->path( '/' );
38	$plugin_slug = $result->plugin()->slug();
39	$filename = str_replace( $plugin_path, '', $filename );
40
41	$file_path = WP_PLUGIN_DIR . '/' . $plugin_slug;
42	if ( $plugin_slug !== $filename ) {
43	$file_path .= '/' . $filename;
44	}
45
46	$source = array(
47	'file' => $file_path,
48	'line' => $line,
49	'plugin' => $plugin_slug,
50	'filename' => $filename,
51	);
52
53	/**
54	* Filters the URL for linking to an external editor to open a file for editing.
55	*
56	* Users of IDEs that support opening files via web protocols can use this filter to
57	* override the edit link so it opens in their editor rather than the plugin editor.
58	*
59	* The initial filtered value is null, requiring extension plugins to supply the URL
60	* themselves. If no URL is provided, links to the plugin editor are used if available.
61	* Returning a string that contains `{{file}}` or `{{line}}` placeholders causes them
62	* to be substituted with the raw filesystem path and the integer line number
63	* respectively. Returning a string without placeholders uses it verbatim.
64	*
65	* For example, to cause file edit links to open in an IDE:
66	*
67	* # PhpStorm
68	* add_filter( 'wp_plugin_check_validation_error_source_url', function ( $url, $source ) {
69	* return 'phpstorm://open?file=' . rawurlencode( $source['file'] ) . '&line=' . (int) $source['line'];
70	* }, 10, 2 );
71	*
72	* # VS Code (using placeholders)
73	* add_filter( 'wp_plugin_check_validation_error_source_url', function ( $url ) {
74	* return 'vscode://file/{{file}}:{{line}}';
75	* } );
76	*
77	* @since 2.1.0
78	*
79	* @param string\|null $url Editor URL. Default null.
80	* @param array $source Source information: file, line, plugin, filename.
81	*/
82	$url = apply_filters( 'wp_plugin_check_validation_error_source_url', null, $source );
83
84	if ( is_string( $url ) && '' !== $url && file_exists( $file_path ) ) {
85	$edit_url = str_replace(
86	array(
87	'{{file}}',
88	'{{line}}',
89	),
90	array(
91	$file_path,
92	$line,
93	),
94	$url
95	);
96	}
97
98	// Backward compatibility for the two-filter chain that this single filter replaces.
99	if ( ! $edit_url && has_filter( 'wp_plugin_check_validation_error_source_file_editor_url_template' ) ) {
100	/**
101	* Filters the template for the URL for linking to an external editor to open a file for editing.
102	*
103	* Users of IDEs that support opening files via web protocols can use this filter to override
104	* the edit link to result in their editor opening rather than the plugin editor.
105	*
106	* @deprecated 2.1.0 Use the `wp_plugin_check_validation_error_source_url` filter instead.
107	*
108	* @since 1.0.0
109	*
110	* @param string\|null $editor_url_template Editor URL template. Default null.
111	*/
112	$editor_url_template = apply_filters_deprecated(
113	'wp_plugin_check_validation_error_source_file_editor_url_template',
114	array( null ),
115	'2.1.0',
116	'wp_plugin_check_validation_error_source_url'
117	);
118
119	// Supply the file path to the editor template.
120	if ( is_string( $editor_url_template ) && str_contains( $editor_url_template, '{{file}}' ) && file_exists( $file_path ) ) {
121	/**
122	* Filters the file path to be opened in an external editor for a given PHPCS error source.
123	*
124	* This is useful to map the file path from inside of a Docker container or VM to the host machine.
125	*
126	* @deprecated 2.1.0 Use the `wp_plugin_check_validation_error_source_url` filter instead.
127	*
128	* @since 1.0.0
129	*
130	* @param string\|null $file_path File path to be opened in the external editor.
131	* @param array $source Source information.
132	*/
133	$file_path = apply_filters_deprecated(
134	'wp_plugin_check_validation_error_source_file_path',
135	array( $file_path, array( $plugin_slug, $filename, $line ) ),
136	'2.1.0',
137	'wp_plugin_check_validation_error_source_url'
138	);
139	if ( $file_path ) {
140	$edit_url = str_replace(
141	array(
142	'{{file}}',
143	'{{line}}',
144	),
145	array(
146	rawurlencode( $file_path ),
147	$line,
148	),
149	$editor_url_template
150	);
151	}
152	}
153	}
154
155	// Fall back to using the plugin editor if no external editor is offered.
156	if ( ! $edit_url && current_user_can( 'edit_plugins' ) ) {
157	$file = '';
158
159	if ( $result->plugin()->is_single_file_plugin() ) {
160	$file = $filename;
161	} elseif ( $result->plugin()->is_file_editable( $filename ) ) {
162	$file = $plugin_slug . '/' . $filename;
163	}
164
165	if ( ! empty( $file ) ) {
166	$query_args = array(
167	'plugin' => rawurlencode( $result->plugin()->basename() ),
168	'file' => rawurlencode( $file ),
169	);
170	if ( $line ) {
171	$query_args['line'] = $line;
172	}
173	return add_query_arg(
174	$query_args,
175	admin_url( 'plugin-editor.php' )
176	);
177	}
178	}
179	return $edit_url;
180	}
181	}
182