Mb Wrapper Laravel Package

Getting Started

Install via Composer: composer require zbateson/mb-wrapper. Start by creating a MbWrapper instance—typically configured once per application (e.g., in a service provider) with the default encoding (usually 'UTF-8'):

use ZBateson\MbWrapper\MbWrapper;

$mb = new MbWrapper('UTF-8');
$length = $mb->strlen('-café'); // safely returns 4

For Laravel, bind it as a singleton in AppServiceProvider@register():

$this->app->singleton(\ZBateson\MbWrapper\MbWrapper::class, function ($app) {
    return new MbWrapper(config('app.encoding', 'UTF-8'));
});

First use case: safely truncating user-generated content for display—e.g., mb->substr($text, 0, 50) avoids splitting multibyte characters.

Note for 3.0.1+: The package now strips iconv-style conversion modifiers (e.g., UTF-8//IGNORE) from charset names. Pass clean encodings like 'UTF-8' or 'ISO-8859-1' to avoid unexpected behavior.

Implementation Patterns

• Dependency injection: Inject MbWrapper into services/services handling user input, email subjects, or internationalized content—avoiding global mb_internal_encoding() calls.
• String normalization: Wrap strings early (e.g., in request validation or model setters) to guarantee encoding consistency before processing.
• Testable string helpers: Use MbWrapper in trait classes (e.g., HasNormalizedTitle) to centralize and unit-test string logic:

  public function getSafeTitleAttribute(): string
  {
      return $this->mb->substr($this->title, 0, 100) . '…';
  }
  

• Configuration-driven defaults: Configure the encoding per-environment via config/app.php, enabling fallback handling (e.g., ISO-8859-1 for legacy integrations). Ensure encodings are free of iconv modifiers (e.g., avoid 'UTF-8//IGNORE').
• Method chaining for readability: Combine operations like $mb->strtolower($mb->trim($input)) or prefer chaining via the wrapper’s fluent interface where supported.

Gotchas and Tips

• Constructor encoding is fixed: Once MbWrapper is instantiated, its encoding can’t be changed—ensure it’s set correctly upfront. Re-instantiate if you need dynamic encoding.
• Laravel’s config('app.encoding') defaults to UTF-8—double-check it isn’t overridden elsewhere (e.g., in .env or middleware) and lacks iconv modifiers.
• Encoding normalization in 3.0.1+: The package now strips iconv-style modifiers (e.g., UTF-8//IGNORE → UTF-8). If your app relies on such modifiers, pre-process encodings before passing them to MbWrapper or use native mb_convert_encoding().
• Missing methods: Not all mb_* functions are wrapped—e.g., mb_convert_encoding() isn’t included. Use native mb_convert_encoding() or extend MbWrapper if needed.
• Debugging tips: Log the effective encoding at boot time:

  logger()->info('MbWrapper initialized with encoding: ' . $mb->getEncoding());
  

• Extension point: Extend MbWrapper to add app-specific operations (e.g., safeSlug() using mb_strtolower() and regex), keeping all multibyte calls centralized.
• No auto-encoding conversion: Strings passed in must match the configured encoding. If importing data from external sources, pre-sanitize/convert with mb_convert_encoding() before passing to the wrapper.
• Legacy iconv modifiers: If migrating from older code, replace encodings like 'UTF-8//IGNORE' with 'UTF-8' and handle errors explicitly (e.g., via mb_regex_encoding() or mb_internal_encoding() fallbacks).