1<?php
  2/**
  3 * Locale API: WP_Textdomain_Registry class.
  4 *
  5 * This file uses rtrim() instead of untrailingslashit() and trailingslashit()
  6 * to avoid formatting.php dependency.
  7 *
  8 * @package WordPress
  9 * @subpackage i18n
 10 * @since 6.1.0
 11 */
 12
 13/**
 14 * Core class used for registering text domains.
 15 *
 16 * @since 6.1.0
 17 */
 18#[AllowDynamicProperties]
 19class WP_Textdomain_Registry {
 20	/**
 21	 * List of domains and all their language directory paths for each locale.
 22	 *
 23	 * @since 6.1.0
 24	 *
 25	 * @var array
 26	 */
 27	protected $all = array();
 28
 29	/**
 30	 * List of domains and their language directory path for the current (most recent) locale.
 31	 *
 32	 * @since 6.1.0
 33	 *
 34	 * @var array
 35	 */
 36	protected $current = array();
 37
 38	/**
 39	 * List of domains and their custom language directory paths.
 40	 *
 41	 * @see load_plugin_textdomain()
 42	 * @see load_theme_textdomain()
 43	 *
 44	 * @since 6.1.0
 45	 *
 46	 * @var array
 47	 */
 48	protected $custom_paths = array();
 49
 50	/**
 51	 * Holds a cached list of available .mo files to improve performance.
 52	 *
 53	 * @since 6.1.0
 54	 * @since 6.5.0 This property is no longer used.
 55	 *
 56	 * @var array
 57	 *
 58	 * @deprecated
 59	 */
 60	protected $cached_mo_files = array();
 61
 62	/**
 63	 * Holds a cached list of domains with translations to improve performance.
 64	 *
 65	 * @since 6.2.0
 66	 *
 67	 * @var string[]
 68	 */
 69	protected $domains_with_translations = array();
 70
 71	/**
 72	 * Initializes the registry.
 73	 *
 74	 * Hooks into the {@see 'upgrader_process_complete'} filter
 75	 * to invalidate MO files caches.
 76	 *
 77	 * @since 6.5.0
 78	 */
 79	public function init() {
 80		add_action( 'upgrader_process_complete', array( $this, 'invalidate_mo_files_cache' ), 10, 2 );
 81	}
 82
 83	/**
 84	 * Returns the languages directory path for a specific domain and locale.
 85	 *
 86	 * @since 6.1.0
 87	 *
 88	 * @param string $domain Text domain.
 89	 * @param string $locale Locale.
 90	 *
 91	 * @return string|false Languages directory path or false if there is none available.
 92	 */
 93	public function get( $domain, $locale ) {
 94		$path = $this->all[ $domain ][ $locale ] ?? $this->get_path_from_lang_dir( $domain, $locale );
 95
 96		/**
 97		 * Filters the determined languages directory path for a specific domain and locale.
 98		 *
 99		 * @since 6.6.0
100		 *
101		 * @param string|false $path   Languages directory path for the given domain and locale.
102		 * @param string       $domain Text domain.
103		 * @param string       $locale Locale.
104		 */
105		return apply_filters( 'lang_dir_for_domain', $path, $domain, $locale );
106	}
107
108	/**
109	 * Determines whether any MO file paths are available for the domain.
110	 *
111	 * This is the case if a path has been set for the current locale,
112	 * or if there is no information stored yet, in which case
113	 * {@see _load_textdomain_just_in_time()} will fetch the information first.
114	 *
115	 * @since 6.1.0
116	 *
117	 * @param string $domain Text domain.
118	 * @return bool Whether any MO file paths are available for the domain.
119	 */
120	public function has( $domain ) {
121		return (
122			isset( $this->current[ $domain ] ) ||
123			empty( $this->all[ $domain ] ) ||
124			in_array( $domain, $this->domains_with_translations, true )
125		);
126	}
127
128	/**
129	 * Sets the language directory path for a specific domain and locale.
130	 *
131	 * Also sets the 'current' property for direct access
132	 * to the path for the current (most recent) locale.
133	 *
134	 * @since 6.1.0
135	 *
136	 * @param string       $domain Text domain.
137	 * @param string       $locale Locale.
138	 * @param string|false $path   Language directory path or false if there is none available.
139	 */
140	public function set( $domain, $locale, $path ) {
141		$this->all[ $domain ][ $locale ] = $path ? rtrim( $path, '/' ) . '/' : false;
142		$this->current[ $domain ]        = $this->all[ $domain ][ $locale ];
143	}
144
145	/**
146	 * Sets the custom path to the plugin's/theme's languages directory.
147	 *
148	 * Used by {@see load_plugin_textdomain()} and {@see load_theme_textdomain()}.
149	 *
150	 * @since 6.1.0
151	 *
152	 * @param string $domain Text domain.
153	 * @param string $path   Language directory path.
154	 */
155	public function set_custom_path( $domain, $path ) {
156		// If just-in-time loading was triggered before, reset the entry so it can be tried again.
157
158		if ( isset( $this->all[ $domain ] ) ) {
159			$this->all[ $domain ] = array_filter( $this->all[ $domain ] );
160		}
161
162		if ( empty( $this->current[ $domain ] ) ) {
163			unset( $this->current[ $domain ] );
164		}
165
166		$this->custom_paths[ $domain ] = rtrim( $path, '/' );
167	}
168
169	/**
170	 * Retrieves translation files from the specified path.
171	 *
172	 * Allows early retrieval through the {@see 'pre_get_mo_files_from_path'} filter to optimize
173	 * performance, especially in directories with many files.
174	 *
175	 * @since 6.5.0
176	 *
177	 * @param string $path The directory path to search for translation files.
178	 * @return array Array of translation file paths. Can contain .mo and .l10n.php files.
179	 */
180	public function get_language_files_from_path( $path ) {
181		$path = rtrim( $path, '/' ) . '/';
182
183		/**
184		 * Filters the translation files retrieved from a specified path before the actual lookup.
185		 *
186		 * Returning a non-null value from the filter will effectively short-circuit
187		 * the MO files lookup, returning that value instead.
188		 *
189		 * This can be useful in situations where the directory contains a large number of files
190		 * and the default glob() function becomes expensive in terms of performance.
191		 *
192		 * @since 6.5.0
193		 *
194		 * @param null|array $files List of translation files. Default null.
195		 * @param string     $path  The path from which translation files are being fetched.
196		 */
197		$files = apply_filters( 'pre_get_language_files_from_path', null, $path );
198
199		if ( null !== $files ) {
200			return $files;
201		}
202
203		$cache_key = md5( $path );
204		$files     = wp_cache_get( $cache_key, 'translation_files' );
205
206		if ( false === $files ) {
207			$files = glob( $path . '*.mo' );
208			if ( false === $files ) {
209				$files = array();
210			}
211
212			$php_files = glob( $path . '*.l10n.php' );
213			if ( is_array( $php_files ) ) {
214				$files = array_merge( $files, $php_files );
215			}
216
217			wp_cache_set( $cache_key, $files, 'translation_files', HOUR_IN_SECONDS );
218		}
219
220		return $files;
221	}
222
223	/**
224	 * Invalidate the cache for .mo files.
225	 *
226	 * This function deletes the cache entries related to .mo files when triggered
227	 * by specific actions, such as the completion of an upgrade process.
228	 *
229	 * @since 6.5.0
230	 *
231	 * @param WP_Upgrader $upgrader   Unused. WP_Upgrader instance. In other contexts this might be a
232	 *                                Theme_Upgrader, Plugin_Upgrader, Core_Upgrade, or Language_Pack_Upgrader instance.
233	 * @param array       $hook_extra {
234	 *     Array of bulk item update data.
235	 *
236	 *     @type string $action       Type of action. Default 'update'.
237	 *     @type string $type         Type of update process. Accepts 'plugin', 'theme', 'translation', or 'core'.
238	 *     @type bool   $bulk         Whether the update process is a bulk update. Default true.
239	 *     @type array  $plugins      Array of the basename paths of the plugins' main files.
240	 *     @type array  $themes       The theme slugs.
241	 *     @type array  $translations {
242	 *         Array of translations update data.
243	 *
244	 *         @type string $language The locale the translation is for.
245	 *         @type string $type     Type of translation. Accepts 'plugin', 'theme', or 'core'.
246	 *         @type string $slug     Text domain the translation is for. The slug of a theme/plugin or
247	 *                                'default' for core translations.
248	 *         @type string $version  The version of a theme, plugin, or core.
249	 *     }
250	 * }
251	 */
252	public function invalidate_mo_files_cache( $upgrader, $hook_extra ) {
253		if (
254			! isset( $hook_extra['type'] ) ||
255			'translation' !== $hook_extra['type'] ||
256			array() === $hook_extra['translations']
257		) {
258			return;
259		}
260
261		$translation_types = array_unique( wp_list_pluck( $hook_extra['translations'], 'type' ) );
262
263		foreach ( $translation_types as $type ) {
264			switch ( $type ) {
265				case 'plugin':
266					wp_cache_delete( md5( WP_LANG_DIR . '/plugins/' ), 'translation_files' );
267					break;
268				case 'theme':
269					wp_cache_delete( md5( WP_LANG_DIR . '/themes/' ), 'translation_files' );
270					break;
271				default:
272					wp_cache_delete( md5( WP_LANG_DIR . '/' ), 'translation_files' );
273					break;
274			}
275		}
276	}
277
278	/**
279	 * Returns possible language directory paths for a given text domain.
280	 *
281	 * @since 6.2.0
282	 *
283	 * @param string $domain Text domain.
284	 * @return string[] Array of language directory paths.
285	 */
286	private function get_paths_for_domain( $domain ) {
287		$locations = array(
288			WP_LANG_DIR . '/plugins',
289			WP_LANG_DIR . '/themes',
290		);
291
292		if ( isset( $this->custom_paths[ $domain ] ) ) {
293			$locations[] = $this->custom_paths[ $domain ];
294		}
295
296		return $locations;
297	}
298
299	/**
300	 * Gets the path to the language directory for the current domain and locale.
301	 *
302	 * Checks the plugins and themes language directories as well as any
303	 * custom directory set via {@see load_plugin_textdomain()} or {@see load_theme_textdomain()}.
304	 *
305	 * @since 6.1.0
306	 *
307	 * @see _get_path_to_translation_from_lang_dir()
308	 *
309	 * @param string $domain Text domain.
310	 * @param string $locale Locale.
311	 * @return string|false Language directory path or false if there is none available.
312	 */
313	private function get_path_from_lang_dir( $domain, $locale ) {
314		$locations = $this->get_paths_for_domain( $domain );
315
316		$found_location = false;
317
318		foreach ( $locations as $location ) {
319			$files = $this->get_language_files_from_path( $location );
320
321			$mo_path  = "$location/$domain-$locale.mo";
322			$php_path = "$location/$domain-$locale.l10n.php";
323
324			foreach ( $files as $file_path ) {
325				if (
326					! in_array( $domain, $this->domains_with_translations, true ) &&
327					str_starts_with( str_replace( "$location/", '', $file_path ), "$domain-" )
328				) {
329					$this->domains_with_translations[] = $domain;
330				}
331
332				if ( $file_path === $mo_path || $file_path === $php_path ) {
333					$found_location = rtrim( $location, '/' ) . '/';
334					break 2;
335				}
336			}
337		}
338
339		if ( $found_location ) {
340			$this->set( $domain, $locale, $found_location );
341
342			return $found_location;
343		}
344
345		/*
346		 * If no path is found for the given locale and a custom path has been set
347		 * using load_plugin_textdomain/load_theme_textdomain, use that one.
348		 */
349		if ( isset( $this->custom_paths[ $domain ] ) ) {
350			$fallback_location = rtrim( $this->custom_paths[ $domain ], '/' ) . '/';
351			$this->set( $domain, $locale, $fallback_location );
352			return $fallback_location;
353		}
354
355		$this->set( $domain, $locale, false );
356
357		return false;
358	}
359}
360