Polyfill Time Laravel Package

Getting Started

symfony/polyfill-time is a PHP polyfill for the Time extension, not a Laravel package. It has no service provider, config file, migrations, or Blade components. v1.42.0 adds a polyfill for Time\Duration, so the package is only useful directly if your code wants to use Time\Duration while remaining compatible with runtimes that do not have the native ext-time extension.

Minimal steps:

1. Check whether it is already installed as a transitive dependency:

   composer show symfony/polyfill-time
   

2. If you intend to use Time\Duration directly, require it explicitly:

   composer require symfony/polyfill-time
   

3. Look first at:
   • vendor/symfony/polyfill-time/README.md
   • vendor/symfony/polyfill-time/Time/Duration.php
   • the package’s composer.json autoload section
4. Inspect the available Time\Duration API before writing code, because the polyfill mirrors a native extension API and may expose more or fewer helpers than expected:

   $r = new ReflectionClass(Time\Duration::class);
   foreach ($r->getMethods() as $method) {
       echo $method->getName(), PHP_EOL;
   }
   

A good first use case is a small domain value object around a duration that you later convert to seconds for Laravel APIs:

use Time\Duration;

// Inspect the class first; then use its factory/accessor methods.
// Example shape only:
$duration = Duration::fromSeconds(30);

// At the Laravel boundary, convert to an int for cache TTLs, queue delays, etc.
$seconds = $duration->toSeconds();

If you are not targeting ext-time compatibility or building a package that uses Time\Duration, you probably do not need to interact with this package directly. Laravel applications normally use Carbon/CarbonInterval for this kind of work.

Implementation Patterns

Treat it as a compatibility layer, not a framework feature. The package is loaded through Composer’s autoload.files mechanism. There is nothing to register in config/app.php or a service provider. In a Laravel app, the main integration point is simply use Time\Duration; in your own classes.

Use it at domain boundaries. A practical pattern is to keep Time\Duration inside domain/value-object code and convert to primitive seconds or milliseconds before passing values into Laravel APIs:

final class RetryBackoff
{
    public function __construct(private Duration $duration) {}

    public function seconds(): int
    {
        return $this->duration->toSeconds();
    }
}

Then in a queued job:

public function backoff(): array
{
    return [$this->backoff->seconds()];
}

Use it when building reusable packages. If you maintain a package that wants to expose Time\Duration-based APIs but cannot assume ext-time is installed, requiring symfony/polyfill-time is the intended pattern. In a Laravel application, prefer your existing Carbon conventions unless you specifically need Time\Duration semantics.

Keep conversions explicit. Laravel APIs commonly expect int seconds, DateTimeInterface, or Carbon instances. Do not pass a Time\Duration object into APIs that expect an integer TTL or delay. Write small adapter methods such as toSeconds(), toMilliseconds(), or toCarbonInterval() where appropriate.

Test with and without the native extension. If your code uses Time\Duration, add CI coverage for both cases:

• normal PHP runtime where the polyfill is active
• runtime with ext-time installed, where the native class may be used instead

This catches accidental reliance on polyfill-only behavior.

Avoid mixing duration abstractions casually. Time\Duration, CarbonInterval, and raw integer seconds have different semantics and APIs. Pick one representation per layer and convert at the edges.

Gotchas and Tips

The polyfill only defines classes when the native extension is absent. If ext-time is installed, the native Time\Duration may be used instead of the polyfill. In most cases this is the desired behavior, but subtle API or behavior differences between the polyfill and the native extension can surface. Test against both if Time\Duration is important to your application.

This release is partial. v1.42.0 specifically adds Time\Duration; it does not mean the entire Time extension namespace is polyfilled. Do not assume Time\Instant, clocks, time zones, or other extension classes are available just because this package is installed. Check class_exists() or inspect the package source.

There is no Laravel package discovery. If Time\Duration is not found, run:

composer dump-autoload

and verify the package is actually installed:

composer show symfony/polyfill-time
php -r "var_dump(class_exists('Time\\Duration'));"

Symfony polyfills share version numbers. v1.42.0 is part of the coordinated Symfony polyfill release line. Running composer update can update many polyfill packages at once. Review the lock file diff if you are pinning tightly or debugging dependency changes.

Do not look for config or extension points. There is no configuration file, no container binding, and no Laravel-specific extension point. Customization happens entirely through your own wrapper/value-object code.

Beware production/runtime differences. A polyfill can make code work on a machine without ext-time, but production may have the extension enabled. Conversely, production may lack it while local development has it. Keep the CI matrix aligned with your deployment targets.

Performance is usually fine, but not identical. For typical Laravel request/job usage, the polyfill overhead is negligible. In hot loops or high-volume duration arithmetic, the native extension may be faster. Benchmark only if duration handling is on a critical path.

No breaking changes are indicated in this release. The changelog only announces the addition of the Time\Duration polyfill. Existing behavior should remain unchanged, but if you begin depending on the new class, constrain the package version appropriately and test against the PHP versions you support.