Time Formatter Bundle Laravel Package

Getting Started

1. Install the fixed release or newer so Composer metadata is correct:

   composer require nehlsen/time-formatter-bundle:^2.0.1
   

   The 2.0.1 release is a packaging/metadata fix, not a feature release. Pin at least 2.0.1 if earlier installs had package-name or autoload issues.

2. Look first at the installed package’s composer.json, src/, and Symfony service/config files. This is a Symfony bundle, so do not assume Laravel package auto-discovery or a Laravel service provider is present.

3. Identify the formatter service/class and its public formatting method from the installed source. In Laravel, wire it manually in a service provider if you want container injection:

   // App\Providers\AppServiceProvider::register()
   $this->app->singleton(\Nehlsen\TimeFormatter\TimeFormatter::class, function () {
       return new \Nehlsen\TimeFormatter\TimeFormatter();
   });
   

   Confirm the exact FQCN and constructor arguments from the installed version before using this snippet.

4. First use case: format raw durations/seconds into human-readable strings for Blade views, API resources, notifications, or reports. Keep stored values raw in the database and format only at the presentation boundary.

Implementation Patterns

• Wrap the package behind your own application service rather than calling it directly throughout controllers/views. This keeps the Symfony-bundle dependency isolated and makes future replacement easier.

  final class DurationPresenter
  {
      public function __construct(private TimeFormatter $formatter) {}
  
      public function human(int $seconds): string
      {
          return $this->formatter->format($seconds); // verify method name
      }
  }
  

• Use constructor injection in controllers, jobs, API resources, and view composers. Bind the package formatter to an interface if you want to swap implementations or fake it in tests.

• For Blade, expose a small helper, directive, or presenter method instead of relying on any Symfony/Twig extension the bundle may ship. Laravel will not automatically register Twig extensions.

• Format at render time, not at persistence time. Store integers/timestamps/interval data in the database and convert to “2 hours 15 minutes” only when producing user-facing output.

• For APIs, prefer returning both machine-readable and formatted values:

  {
    "duration_seconds": 8100,
    "duration_human": "2 hours 15 minutes"
  }
  

  This avoids forcing clients to parse display strings.

• If the package exposes locale, precision, or unit configuration, centralize those settings in config/ or a dedicated presenter so all formatted output is consistent.

• In queued jobs and notifications, format as late as possible. If the formatting depends on locale/user preferences, pass the locale or resolved string into the job rather than relying on ambient request state.

Gotchas and Tips

• 2.0.1 only fixes the package name in composer.json. There are no documented API or behavior changes, so treat it as a safe patch release, but use ^2.0.1 when installation metadata matters.

• This is a Symfony bundle. Expect to do manual integration in Laravel: service registration, config publishing equivalents, and no automatic Twig/Blade integration. Check the package source for exact service IDs and constructor signatures.

• Composer package-name fixes can surface as confusing install/autoload errors. After upgrading, run:

  composer clear-cache
  composer dump-autoload
  composer show nehlsen/time-formatter-bundle
  

  Verify the installed name and version match what your application requires.

• Be explicit about locale and timezone. Duration formatting can vary by locale, and date/time formatting can vary by timezone; do not rely on PHP defaults in user-facing output.

• Test edge cases: zero duration, negative values, sub-second values, very large durations, singular/plural units, and DST/timezone boundaries if formatting timestamps.

• Debug container resolution with:

  dd(app(TimeFormatter::class));
  

  If that fails, the class is not wired or the FQCN is wrong. Inspect the installed package rather than guessing namespaces.

• Extension point to prefer: decorate or wrap the formatter in your own service. This lets you add caching, locale fallback, custom unit labels, or test doubles without modifying vendor code.