Improve switcher dynamic return types in polylang-phpstan

[Hug0-Drelon]

Summary

Polylang 3.9 refactored the language switcher. The current polylang-phpstan release covers the main public API (pll_the_languages()), but two areas still rely on coarse types.

Context

Since 3.9:

• pll_the_languages( $args ) delegates to WP_Syntex\Polylang\Switcher\Switcher
• PLL_Switcher::the_languages() was removed

polylang-phpstan 2.3 migrated away from PLL_Switcher and now resolves pll_the_languages() return types from $args['raw'] and $args['echo'].

Gaps

1. Dynamic layout instantiation in Switcher::get()

In Polylang source, Switcher::get() resolves the layout class at runtime:

$switcher_class = $this->settings->get_switcher_class();
$html = ( new $switcher_class( $this->settings, $this->links ) )->get();

Today, PHPStan sees $switcher_class as string, so it cannot narrow the instantiated layout class (Nav, Dropdown, Select, …).

Possible improvements

• Add a DynamicMethodReturnTypeExtension for WP_Syntex\Polylang\Switcher\Settings\Settings::get_switcher_class() based on the layout setting
• Or a @phpstan-return conditional on Settings::$layout

Benefit: Better analysis inside Polylang and for code that instantiates switcher layouts directly.

2. Finer typing for pll_the_languages( [ 'raw' => true ] )

The extension currently returns array<string, mixed>.

The runtime array is built in pll_the_languages() from switcher elements and legacy keys (is_rtl, name, flag, current_lang, no_translation, classes, …).

Possible improvements

• Define a @phpstan-type PllLanguageSwitcherRawElement array{...} in stubs or in the extension
• Return array<string, PllLanguageSwitcherRawElement> from the dynamic extension when raw => true is known

Benefit: Safer consumption of raw switcher data in themes and custom integrations.

Acceptance criteria

• Known layout values map to concrete layout classes where possible
• pll_the_languages( [ 'raw' => true ] ) resolves to a documented array shape instead of mixed values
• PHPUnit coverage added under tests/data/
• No regression for existing pll_the_languages() argument inference

Non-goals

• Re-introducing support for PLL_Switcher::the_languages()
• Typing deprecated legacy arguments beyond what PHPStan can infer statically

Related

• Polylang 3.9 switcher refactor (WP_Syntex\Polylang\Switcher\*)
• polylang-phpstan 2.3 migration away from PLL_Switcher