PHPackages boronczyk/localization-middleware - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Localization & i18n](/categories/localization) 4. / 5. boronczyk/localization-middleware ActiveLibrary[Localization & i18n](/categories/localization) boronczyk/localization-middleware ================================= PSR-15 middleware to assist primarily with language-based content negotiation and various other localization tasks. 2.0.2(1y ago)2665.3k↑28.6%9MITPHPPHP >=7.2CI failing Since Jun 2Pushed 1y ago3 watchersCompare [ Source](https://github.com/tboronczyk/localization-middleware)[ Packagist](https://packagist.org/packages/boronczyk/localization-middleware)[ Docs](https://github.com/tboronczyk/localization-middleware)[ RSS](/packages/boronczyk-localization-middleware/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (7)Dependencies (4)Versions (11)Used By (0) Localization Middleware ======================= [](#localization-middleware) [![tboronczyk](https://camo.githubusercontent.com/6a7ff2b838b0ad68e2068b35034d3d48edb7196ade0d996c0e1589dc59d6b4d5/68747470733a2f2f636972636c6563692e636f6d2f67682f74626f726f6e637a796b2f6c6f63616c697a6174696f6e2d6d6964646c65776172652e7376673f7374796c653d736869656c64)](https://circleci.com/gh/tboronczyk/localization-middleware)[![codecov](https://camo.githubusercontent.com/3dadef980f1cf8d9a148f766e0cf8fc4c60ff9776e999bc9999ae21f687cbee1/68747470733a2f2f636f6465636f762e696f2f67682f74626f726f6e637a796b2f6c6f63616c697a6174696f6e2d6d6964646c65776172652f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/tboronczyk/localization-middleware)[![FOSSA Status](https://camo.githubusercontent.com/a2fe4e4235e46fd96f5d2080e6246baa76ca2cd5bee2d72c785ddc2b574067b9/68747470733a2f2f6170702e666f7373612e696f2f6170692f70726f6a656374732f67697425324268747470732533412532462532466769746875622e636f6d25324674626f726f6e637a796b2532466c6f63616c697a6174696f6e2d6d6964646c65776172652e7376673f747970653d736869656c64)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Ftboronczyk%2Flocalization-middleware?ref=badge_shield) Middleware to assist primarily with language-based content negotiation and various other localization tasks. It determines the appropriate locale based on the client’s request and sets an attribute on the request object making the value available to the rest of your application. Its callback hook offers a convenient way to initialize other libraries or execute code based on the locale value. **Version 2 conforms to [PSR-15](https://www.php-fig.org/psr/psr-15/). Use version ^1.4 if you require the so-called “Double Pass” approach using `__invoke()`.** Installation ------------ [](#installation) Localization Middleware is installable via [Composer](https://getcomposer.org). ``` composer require boronczyk/localization-middleware ``` Basic Example ------------- [](#basic-example) Here is a basic usage example: ``` use Boronczyk\LocalizationMiddleware; // register the middleware with your PSR-15 compliant framework $availableLocales = ['en_US', 'fr_CA', 'es_MX', 'eo']; $defaultLocale = 'en_US'; $app->add(new LocalizationMiddleware($availableLocales, $defaultLocale)); // reference the locale in your route callback $app->get('/', function ($req, $resp, $args) { $attrs = $req->getAttributes(); $locale = $attrs['locale']; return $resp->write("The locale is $locale."); }); ``` More Advanced Example --------------------- [](#more-advanced-example) Here is a more advanced usage example: ``` use Boronczyk\LocalizationMiddleware; // instanciate the middleware $availableLocales = ['en_US', 'fr_CA', 'es_MX', 'eo']; $defaultLocale = 'en_US'; $middleware = new LocalizationMiddleware($availableLocales, $defaultLocale); // specify the order in which inputs are searched for the locale $middleware->setSearchOrder([ LocalizationMiddleware::FROM_CALLBACK, LocalizationMiddleware::FROM_URI_PATH, LocalizationMiddleware::FROM_URI_PARAM, LocalizationMiddleware::FROM_COOKIE, LocalizationMiddleware::FROM_HEADER ]); // attempt to identify the locale using a callback $middleware->setSearchCallback( function (Request $req) use (Container $c): string { $db = $c->get('GeoIp2Database'); switch ($db->country($req->getAttribute('ip_address')) { case 'CA': return 'fr_CA'; case 'US': return 'en_US'; case 'MX': return 'es_MX'; default: return ''; } } ); // execute logic once the locale has been identified $middleware->setLocaleCallback(function (string $locale) { putenv("LANG=$locale"); setlocale(LC_ALL, $locale); bindtextdomain('messages', 'Locale'); bind_textdomain_codeset('messages', 'UTF-8'); textdomain('messages'); }); // change the name of the uri parameter identifying the locale $middleware->setUriParamName('hl'); // register the middleware with your PSR-15 compliant framework $app->add($middleware); // reference the locale in your route callback $app->get('/', function ($req, $resp, $args) { $attrs = $req->getAttributes(); $locale = $attrs['locale']; $text = sprintf(_('The locale is %s.'), $locale); return $resp->write($text); }); ``` Configurable Behavior --------------------- [](#configurable-behavior) The middleware component’s behavior is configurable though the following methods: - `setAvailableLocales(array $locales)` Sets the list of available locales after an instance has already been created. ``` $middleware->setAvailableLocales(['en_US', 'fr_CA', 'pt_BR']); ``` - `setDefaultLocale(string $locale)` Sets the default locale to return after an instance has already been created. ``` $middleware->setDefaultLocale('fr_CA'); ``` - `setSearchOrder(array $order)` Sets the order in which inputs are searched for a suitable locale. ``` $middleware->setSearchOrder([ LocalizationMiddleware::FROM_URI_PATH, LocalizationMiddleware::FROM_URI_PARAM, LocalizationMiddleware::FROM_COOKIE, LocalizationMiddleware::FROM_HEADER ]); ``` Adding or removing locale sources from the order modifies the search domain. ``` // only search cookies and the Accept-Language header $middleware->setSearchOrder([ LocalizationMiddleware::FROM_COOKIE, LocalizationMiddleware::FROM_HEADER ]); ``` The available locale source constants are: - `LocalizationMiddleware::FROM_URI_PATH` Search for the locale in the URI path. The first directory value in the request path is considered the locale, for example `https://example.com/en_US/foo`. - `LocalizationMiddleware::FROM_URI_PARAM` Search for the locale in the URI parameter (the default parameter name is `locale`). - `LocalizationMiddleware::FROM_COOKIE` Search for the locale in cookies (the default cookie name is `locale`). *Note: Using this will set a locale cookie for subsequent requests.* - `LocalizationMiddleware::FROM_HEADER` Search for the locale in the HTTP `Accept-Language` header. Header searches make a best-effort search for locales, languages, and possible quality modifiers. - `LocalizationMiddleware::FROM_CALLBACK` Search for the locale using a custom callback function. The callback function is set with `setSearchCallback()`. The default order is: `FROM_URI_PATH`, `FROM_URI_PARAM`, `FROM_COOKIE`, `FROM_HEADER`. *Note that `FROM_CALLBACK` is **not** included by default.* - `setSearchCallback(callable $func)` Sets a callback that is invoked when searching for the locale, offering the developer a chance to inject a locale of their choosing into the search. The callable’s signature is: `function (Request $req): string`. ``` $middleware->setSearchCallback( function (Request $req) use (Container $c): string { $db = $c->get('GeoIp2Database'); switch ($db->country($req->getAttribute('ip_address')) { case 'CA': return 'fr_CA'; case 'US': return 'en_US'; case 'MX': return 'es_MX'; default: return ''; } } ); ``` - `setReqAttrName(string $name)` Sets the name for the attribute attached to the request. The default name is `locale`. ``` $middleware->setReqAttrName('lang'); $app->get('/', function ($req, $resp, $args) { $attrs = $req->getAttributes(); $lang = $attrs['lang']; }); ``` - `setUriParamName(string $name)` Sets the name for a URI parameter to specify the locale. The default name is `locale`. ``` $middleware->setUriParamName('lang'); https://example.com/mypage?lang=es_MX ``` - `setCookieName(string $name)` Sets the name of the cookie to store the determined locale. The default name is `locale`. ``` $middleware->setCookieName('lang'); ``` - `setCookiePath(string $path)` Sets the path of the cookie for which it will be returned by the client. The default path is `/`. ``` $middleware->setCookiePath("/dir"); ``` - `setCookieExpire(int $secs)` Sets the duration of the locale cookie. The default value is 30 days. ``` $middleware->setCookieExpire(3600); // 1 hour ``` - `setLocaleCallback(callable $func)` Sets a callback that is invoked after the middleware identifies the locale, offering the developer a chance to conveniently initialize other libraries or execute other code with the value. The callable’s signature is: `function (string $locale)`. ``` $middleware->setLocaleCallback(function (string $locale) { putenv("LANG=$locale"); setlocale(LC_ALL, $locale); bindtextdomain('messages', 'Locale'); bind_textdomain_codeset('messages', 'UTF-8'); textdomain('messages'); }); ``` License ------- [](#license) [![FOSSA Status](https://camo.githubusercontent.com/0bebfde2b82fe759ab117172d8b9e173f401726c453e3dd76721778e414bdc7e/68747470733a2f2f6170702e666f7373612e696f2f6170692f70726f6a656374732f67697425324268747470732533412532462532466769746875622e636f6d25324674626f726f6e637a796b2532466c6f63616c697a6174696f6e2d6d6964646c65776172652e7376673f747970653d6c61726765)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Ftboronczyk%2Flocalization-middleware?ref=badge_large) ### Health Score 44 — FairBetter than 92% of packages Maintenance42 Moderate activity, may be stable Popularity40 Moderate usage in the ecosystem Community16 Small or concentrated contributor base Maturity64 Established project with proven stability Bus Factor1 Top contributor holds 84.9% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~310 days Recently: every ~595 days Total 10 Last Release 480d ago Major Versions 1.4.1 → 2.02020-04-26 PHP version history (4 changes)1.0PHP ^7.0 2.0PHP ^7.2 2.0.1PHP ^7.2 || ^8.0 2.0.2PHP >=7.2 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/696497?v=4)[Timothy Boronczyk](/maintainers/tboronczyk)[@tboronczyk](https://github.com/tboronczyk) --- Top Contributors [![tboronczyk](https://avatars.githubusercontent.com/u/696497?v=4)](https://github.com/tboronczyk "tboronczyk (62 commits)")[![fgagne](https://avatars.githubusercontent.com/u/13245424?v=4)](https://github.com/fgagne "fgagne (8 commits)")[![bakurin](https://avatars.githubusercontent.com/u/3139385?v=4)](https://github.com/bakurin "bakurin (2 commits)")[![fossabot](https://avatars.githubusercontent.com/u/29791463?v=4)](https://github.com/fossabot "fossabot (1 commits)") --- Tags content-negotiationlanguagemiddlewarepsr-15slim-frameworklocalizationslimpsr-15 ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/boronczyk-localization-middleware/health.svg) ``` [![Health](https://phpackages.com/badges/boronczyk-localization-middleware/health.svg)](https://phpackages.com/packages/boronczyk-localization-middleware) ``` ### Alternatives [symfony/intl Provides access to the localization data of the ICU library 2.6k199.8M1.1k](/packages/symfony-intl)[commerceguys/addressing Addressing library powered by CLDR and Google's address data. 95630.2M43](/packages/commerceguys-addressing)[gettext/languages gettext languages with plural rules 7530.3M11](/packages/gettext-languages)[mezzio/mezzio-authentication Authentication middleware for Mezzio and PSR-7 applications 121.6M26](/packages/mezzio-mezzio-authentication)[jasny/auth Authentication, authorization and access control for Slim Framework and other PHP micro-frameworks 11816.4k1](/packages/jasny-auth)[jimtools/jwt-auth PSR-15 JWT Authentication middleware, A replacement for tuupola/slim-jwt-auth 20142.3k3](/packages/jimtools-jwt-auth) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)