16696225597

Committed 02 Aug 2025 05:54PM UTC coverage: 84.279%. First build

Build # 16696225597

Build Type

Pull #9656

github

Committed by

web-flow

Commit Message

Merge 4edaf94ee into 59de29e3d

Pull Request Pull Request #9656: refactor: fix phpdoc and improve code in `Language`

Run Details

34 of 36 new or added lines in 2 files covered. (94.44%)

20822 of 24706 relevant lines covered (84.28%)

194.14 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

97.83

/system/Language/Language.php

<?php

declare(strict_types=1);

/**
 * This file is part of CodeIgniter 4 framework.
 *
 * (c) CodeIgniter Foundation <admin@codeigniter.com>
 *
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this source code.
 */

namespace CodeIgniter\Language;

use IntlException;
use MessageFormatter;

/**
 * Handle system messages and localization.
 *
 * Locale-based, built on top of PHP internationalization.
 *
 * @phpstan-type LoadedStrings array<string, array<string, array<string, string>|string>|string|list<string>>
 *
 * @see \CodeIgniter\Language\LanguageTest
 */
class Language
{
    /**
     * Stores the retrieved language lines
     * from files for faster retrieval on
     * second use.
     *
     * @var array<non-empty-string, array<non-empty-string, LoadedStrings>>
     */
    protected $language = [];

    /**
     * The current locale to work with.
     *
     * @var non-empty-string
     */
    protected $locale;

    /**
     * Boolean value whether the `intl` extension exists on the system.
     *
     * @var bool
     */
    protected $intlSupport = false;

    /**
     * Stores filenames that have been
     * loaded so that we don't load them again.
     *
     * @var array<non-empty-string, list<non-empty-string>>
     */
    protected $loadedFiles = [];

    /**
     * @param non-empty-string $locale
     */
    public function __construct(string $locale)
    {
        $this->locale = $locale;

        if (class_exists(MessageFormatter::class)) {
            $this->intlSupport = true;
        }
    }

    /**
     * Sets the current locale to use when performing string lookups.
     *
     * @param non-empty-string|null $locale
     *
     * @return $this
     */
    public function setLocale(?string $locale = null)
    {
        if ($locale !== null) {
            $this->locale = $locale;
        }

        return $this;
    }

    public function getLocale(): string
    {
        return $this->locale;
    }

    /**
     * Parses the language string for a file, loads the file, if necessary,
     * getting the line.
     *
     * @param array<array-key, float|int|string> $args
     *
     * @return list<string>|string
     */
    public function getLine(string $line, array $args = [])
    {
        // 1. Format the line as-is if it does not have a file.
        if (! str_contains($line, '.')) {
            return $this->formatMessage($line, $args);
        }

        // 2. Get the formatted line using the file and line extracted from $line and the current locale.
        [$file, $parsedLine] = $this->parseLine($line, $this->locale);

        $output = $this->getTranslationOutput($this->locale, $file, $parsedLine);

        // 3. If not found, try the locale without region (e.g., 'en-US' -> 'en').
        if ($output === null && str_contains($this->locale, '-')) {
            [$locale] = explode('-', $this->locale, 2);

            [$file, $parsedLine] = $this->parseLine($line, $locale);

            $output = $this->getTranslationOutput($locale, $file, $parsedLine);
        }

        // 4. If still not found, try English.
        if ($output === null) {
            [$file, $parsedLine] = $this->parseLine($line, 'en');

            $output = $this->getTranslationOutput('en', $file, $parsedLine);
        }

        // 5. Fallback to the original line if no translation was found.
        $output ??= $line;

        return $this->formatMessage($output, $args);
    }

    /**
     * @return list<string>|string|null
     */
    protected function getTranslationOutput(string $locale, string $file, string $parsedLine)
    {
        $output = $this->language[$locale][$file][$parsedLine] ?? null;

        if ($output !== null) {
            return $output;
        }

        // Fallback: try to traverse dot notation
        $current = $this->language[$locale][$file] ?? null;

        if (is_array($current)) {
            foreach (explode('.', $parsedLine) as $segment) {
                $output = $current[$segment] ?? null;

                if ($output === null) {
                    break;
                }

                if (is_array($output)) {
                    $current = $output;
                }
            }

            if ($output !== null && ! is_array($output)) {
                return $output;
            }
        }

        // Final fallback: try two-level access manually
        [$first, $rest] = explode('.', $parsedLine, 2) + ['', ''];

        return $this->language[$locale][$file][$first][$rest] ?? null;
    }

    /**
     * Parses the language string which should include the
     * filename as the first segment (separated by period).
     *
     * @return array{non-empty-string, non-empty-string}
     */
    protected function parseLine(string $line, string $locale): array
    {
        [$file, $line] = explode('.', $line, 2);

        if (! isset($this->language[$locale][$file]) || ! array_key_exists($line, $this->language[$locale][$file])) {
            $this->load($file, $locale);
        }

        return [$file, $line];
    }

    /**
     * Advanced message formatting.
     *
     * @param list<string>|string                $message
     * @param array<array-key, float|int|string> $args
     *
     * @return ($message is list<string> ? list<string> : string)
     */
    protected function formatMessage($message, array $args = [])
    {
        if (! $this->intlSupport || $args === []) {
            return $message;
        }

        if (is_array($message)) {
            foreach ($message as $index => $value) {
                $message[$index] = $this->formatMessage($value, $args);
            }

            return $message;
        }

        $formatted = MessageFormatter::formatMessage($this->locale, $message, $args);

        if ($formatted === false) {
            // Format again to get the error message.
            try {
                $formatter = new MessageFormatter($this->locale, $message);
                $formatted = $formatter->format($args);
                $fmtError  = sprintf('"%s" (%d)', $formatter->getErrorMessage(), $formatter->getErrorCode());
            } catch (IntlException $e) {
                $fmtError = sprintf('"%s" (%d)', $e->getMessage(), $e->getCode());
            }

            $argsAsString   = sprintf('"%s"', implode('", "', $args));
            $urlEncodedArgs = sprintf('"%s"', implode('", "', array_map(rawurlencode(...), $args)));

            log_message('error', sprintf(
                'Invalid message format: $message: "%s", $args: %s (urlencoded: %s), MessageFormatter Error: %s',
                $message,
                $argsAsString,
                $urlEncodedArgs,
                $fmtError,
            ));

            return $message . "\n【Warning】Also, invalid string(s) was passed to the Language class. See log file for details.";
        }

        return $formatted;
    }

    /**
     * Loads a language file in the current locale. If $return is true,
     * will return the file's contents, otherwise will merge with
     * the existing language lines.
     *
     * @return ($return is true ? LoadedStrings : null)
     */
    protected function load(string $file, string $locale, bool $return = false)
    {
        if (! array_key_exists($locale, $this->loadedFiles)) {
            $this->loadedFiles[$locale] = [];
        }

        if (in_array($file, $this->loadedFiles[$locale], true)) {
            // Don't load it more than once.
            return [];
        }

        if (! array_key_exists($locale, $this->language)) {
            $this->language[$locale] = [];
        }

        if (! array_key_exists($file, $this->language[$locale])) {
            $this->language[$locale][$file] = [];
        }

        $path = "Language/{$locale}/{$file}.php";

        $lang = $this->requireFile($path);

        if ($return) {
            return $lang;
        }

        $this->loadedFiles[$locale][] = $file;

        // Merge our string
        $this->language[$locale][$file] = $lang;

        return null;
    }

    /**
     * A simple method for including files that can be overridden during testing.
     *
     * @return LoadedStrings
     */
    protected function requireFile(string $path): array
    {
        $files   = service('locator')->search($path, 'php', false);
        $strings = [];

        foreach ($files as $file) {
            if (is_file($file)) {
                // On some OS, we were seeing failures on this command returning boolean instead
                // of array during testing, so we've removed the require_once for now.
                $loadedStrings = require $file;

                if (is_array($loadedStrings)) {
                    /** @var LoadedStrings $loadedStrings */
                    $strings[] = $loadedStrings;
                }
            }
        }

        $count = count($strings);

        if ($count > 1) {
            $base = array_shift($strings);

            $strings = array_replace_recursive($base, ...$strings);
        } elseif ($count === 1) {
            $strings = $strings[0];
        }

        return $strings;
    }
}

1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* This file is part of CodeIgniter 4 framework.
7	*
8	* (c) CodeIgniter Foundation <admin@codeigniter.com>
9	*
10	* For the full copyright and license information, please view
11	* the LICENSE file that was distributed with this source code.
12	*/
13
14	namespace CodeIgniter\Language;
15
16	use IntlException;
17	use MessageFormatter;
18
19	/**
20	* Handle system messages and localization.
21	*
22	* Locale-based, built on top of PHP internationalization.
23	*
24	* @phpstan-type LoadedStrings array<string, array<string, array<string, string>\|string>\|string\|list<string>>
25	*
26	* @see \CodeIgniter\Language\LanguageTest
27	*/
28	class Language
29	{
30	/**
31	* Stores the retrieved language lines
32	* from files for faster retrieval on
33	* second use.
34	*
35	* @var array<non-empty-string, array<non-empty-string, LoadedStrings>>
36	*/
37	protected $language = [];
38
39	/**
40	* The current locale to work with.
41	*
42	* @var non-empty-string
43	*/
44	protected $locale;
45
46	/**
47	* Boolean value whether the `intl` extension exists on the system.
48	*
49	* @var bool
50	*/
51	protected $intlSupport = false;
52
53	/**
54	* Stores filenames that have been
55	* loaded so that we don't load them again.
56	*
57	* @var array<non-empty-string, list<non-empty-string>>
58	*/
59	protected $loadedFiles = [];
60
61	/**
62	* @param non-empty-string $locale
63	*/
64	public function __construct(string $locale)
65	{
66	$this->locale = $locale;	427✔
67
68	if (class_exists(MessageFormatter::class)) {	427✔
69	$this->intlSupport = true;	427✔
70	}
71	}
72
73	/**
74	* Sets the current locale to use when performing string lookups.
75	*
76	* @param non-empty-string\|null $locale
77	*
78	* @return $this
79	*/
80	public function setLocale(?string $locale = null)
81	{
82	if ($locale !== null) {	401✔
83	$this->locale = $locale;	6✔
84	}
85
86	return $this;	401✔
87	}
88
89	public function getLocale(): string
90	{
91	return $this->locale;	1,717✔
92	}
93
94	/**
95	* Parses the language string for a file, loads the file, if necessary,
96	* getting the line.
97	*
98	* @param array<array-key, float\|int\|string> $args
99	*
100	* @return list<string>\|string
101	*/
102	public function getLine(string $line, array $args = [])
103	{
104	// 1. Format the line as-is if it does not have a file.
105	if (! str_contains($line, '.')) {	1,737✔
106	return $this->formatMessage($line, $args);	650✔
107	}
108
109	// 2. Get the formatted line using the file and line extracted from $line and the current locale.
110	[$file, $parsedLine] = $this->parseLine($line, $this->locale);	1,723✔
111
112	$output = $this->getTranslationOutput($this->locale, $file, $parsedLine);	1,723✔
113
114	// 3. If not found, try the locale without region (e.g., 'en-US' -> 'en').
115	if ($output === null && str_contains($this->locale, '-')) {	1,723✔
116	[$locale] = explode('-', $this->locale, 2);	5✔
117
118	[$file, $parsedLine] = $this->parseLine($line, $locale);	5✔
119
120	$output = $this->getTranslationOutput($locale, $file, $parsedLine);	5✔
121	}
122
123	// 4. If still not found, try English.
124	if ($output === null) {	1,723✔
125	[$file, $parsedLine] = $this->parseLine($line, 'en');	161✔
126
127	$output = $this->getTranslationOutput('en', $file, $parsedLine);	161✔
128	}
129
130	// 5. Fallback to the original line if no translation was found.
131	$output ??= $line;	1,723✔
132
133	return $this->formatMessage($output, $args);	1,723✔
134	}
135
136	/**
137	* @return list<string>\|string\|null
138	*/
139	protected function getTranslationOutput(string $locale, string $file, string $parsedLine)
140	{
141	$output = $this->language[$locale][$file][$parsedLine] ?? null;	1,723✔
142
143	if ($output !== null) {	1,723✔
144	return $output;	1,571✔
145	}
146
147	// Fallback: try to traverse dot notation
148	$current = $this->language[$locale][$file] ?? null;	222✔
149
150	if (is_array($current)) {	222✔
151	foreach (explode('.', $parsedLine) as $segment) {	222✔
152	$output = $current[$segment] ?? null;	222✔
153
154	if ($output === null) {	222✔
155	break;	162✔
156	}
157
158	if (is_array($output)) {	63✔
159	$current = $output;	61✔
160	}
161	}
162
163	if ($output !== null && ! is_array($output)) {	222✔
164	return $output;	60✔
165	}
166	}
167
168	// Final fallback: try two-level access manually
169	[$first, $rest] = explode('.', $parsedLine, 2) + ['', ''];	162✔
170
171	return $this->language[$locale][$file][$first][$rest] ?? null;	162✔
172	}
173
174	/**
175	* Parses the language string which should include the
176	* filename as the first segment (separated by period).
177	*
178	* @return array{non-empty-string, non-empty-string}
179	*/
180	protected function parseLine(string $line, string $locale): array
181	{
182	[$file, $line] = explode('.', $line, 2);	1,723✔
183
184	if (! isset($this->language[$locale][$file]) \|\| ! array_key_exists($line, $this->language[$locale][$file])) {	1,723✔
185	$this->load($file, $locale);	621✔
186	}
187
188	return [$file, $line];	1,723✔
189	}
190
191	/**
192	* Advanced message formatting.
193	*
194	* @param list<string>\|string $message
195	* @param array<array-key, float\|int\|string> $args
196	*
197	* @return ($message is list<string> ? list<string> : string)
198	*/
199	protected function formatMessage($message, array $args = [])
200	{
201	if (! $this->intlSupport \|\| $args === []) {	1,737✔
202	return $message;	1,428✔
203	}
204
205	if (is_array($message)) {	1,029✔
206	foreach ($message as $index => $value) {	1✔
207	$message[$index] = $this->formatMessage($value, $args);	1✔
208	}
209
210	return $message;	1✔
211	}
212
213	$formatted = MessageFormatter::formatMessage($this->locale, $message, $args);	1,029✔
214
215	if ($formatted === false) {	1,029✔
216	// Format again to get the error message.
217	try {
218	$formatter = new MessageFormatter($this->locale, $message);	1✔
NEW 219	$formatted = $formatter->format($args);	×
NEW 220	$fmtError = sprintf('"%s" (%d)', $formatter->getErrorMessage(), $formatter->getErrorCode());	×
221	} catch (IntlException $e) {	1✔
222	$fmtError = sprintf('"%s" (%d)', $e->getMessage(), $e->getCode());	1✔
223	}
224
225	$argsAsString = sprintf('"%s"', implode('", "', $args));	1✔
226	$urlEncodedArgs = sprintf('"%s"', implode('", "', array_map(rawurlencode(...), $args)));	1✔
227
228	log_message('error', sprintf(	1✔
229	'Invalid message format: $message: "%s", $args: %s (urlencoded: %s), MessageFormatter Error: %s',	1✔
230	$message,	1✔
231	$argsAsString,	1✔
232	$urlEncodedArgs,	1✔
233	$fmtError,	1✔
234	));	1✔
235
236	return $message . "\n【Warning】Also, invalid string(s) was passed to the Language class. See log file for details.";	1✔
237	}
238
239	return $formatted;	1,028✔
240	}
241
242	/**
243	* Loads a language file in the current locale. If $return is true,
244	* will return the file's contents, otherwise will merge with
245	* the existing language lines.
246	*
247	* @return ($return is true ? LoadedStrings : null)
248	*/
249	protected function load(string $file, string $locale, bool $return = false)
250	{
251	if (! array_key_exists($locale, $this->loadedFiles)) {	623✔
252	$this->loadedFiles[$locale] = [];	413✔
253	}
254
255	if (in_array($file, $this->loadedFiles[$locale], true)) {	623✔
256	// Don't load it more than once.
257	return [];	218✔
258	}
259
260	if (! array_key_exists($locale, $this->language)) {	466✔
261	$this->language[$locale] = [];	410✔
262	}
263
264	if (! array_key_exists($file, $this->language[$locale])) {	466✔
265	$this->language[$locale][$file] = [];	463✔
266	}
267
268	$path = "Language/{$locale}/{$file}.php";	466✔
269
270	$lang = $this->requireFile($path);	466✔
271
272	if ($return) {	466✔
273	return $lang;	1✔
274	}
275
276	$this->loadedFiles[$locale][] = $file;	466✔
277
278	// Merge our string
279	$this->language[$locale][$file] = $lang;	466✔
280
281	return null;	466✔
282	}
283
284	/**
285	* A simple method for including files that can be overridden during testing.
286	*
287	* @return LoadedStrings
288	*/
289	protected function requireFile(string $path): array
290	{
291	$files = service('locator')->search($path, 'php', false);	463✔
292	$strings = [];	463✔
293
294	foreach ($files as $file) {	463✔
295	if (is_file($file)) {	438✔
296	// On some OS, we were seeing failures on this command returning boolean instead
297	// of array during testing, so we've removed the require_once for now.
298	$loadedStrings = require $file;	438✔
299
300	if (is_array($loadedStrings)) {	438✔
301	/** @var LoadedStrings $loadedStrings */
302	$strings[] = $loadedStrings;	438✔
303	}
304	}
305	}
306
307	$count = count($strings);	463✔
308
309	if ($count > 1) {	463✔
310	$base = array_shift($strings);	60✔
311
312	$strings = array_replace_recursive($base, ...$strings);	60✔
313	} elseif ($count === 1) {	418✔
314	$strings = $strings[0];	393✔
315	}
316
317	return $strings;	463✔
318	}
319	}

codeigniter4 / CodeIgniter4 / 16696225597

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous