PHPackages                             mbarlow/timezones - 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. [Utility & Helpers](/categories/utility)
4. /
5. mbarlow/timezones

ActiveLibrary[Utility & Helpers](/categories/utility)

mbarlow/timezones
=================

Timezone helpers to convert to and from UTC with Laravel Blade directives

3.0.0(5y ago)65.3k—0%2[1 PRs](https://github.com/mikebarlow/Timezones/pulls)MITPHP

Since Aug 15Pushed 1y ago1 watchersCompare

[ Source](https://github.com/mikebarlow/Timezones)[ Packagist](https://packagist.org/packages/mbarlow/timezones)[ Docs](https://github.com/mikebarlow/Timezones)[ RSS](/packages/mbarlow-timezones/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (2)Versions (9)Used By (0)

Timezones
=========

[](#timezones)

[![Author](https://camo.githubusercontent.com/9d903e7623152bba92e485dae02e0ffe50922554087701bab4ab685ea10150d2/687474703a2f2f696d672e736869656c64732e696f2f62616467652f617574686f722d406d696b656261726c6f772d7265642e7376673f7374796c653d666c61742d737175617265)](https://twitter.com/mikebarlow)[![Latest Version](https://camo.githubusercontent.com/95a117976d4d123e95fe3b5698d1a0da9718de3139eaec982b4932bfd2c531f8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f6d696b656261726c6f772f54696d657a6f6e65732e7376673f7374796c653d666c61742d737175617265)](https://github.com/mikebarlow/Timezones/releases)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/mikebarlow/Timezones/blob/master/LICENSE)[![Build Status](https://camo.githubusercontent.com/c9b9f0ba7b5db1b4060e840163e45fb0687909814ed5454103f09f81eba26e54/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d696b656261726c6f772f54696d657a6f6e65732f7068702e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265)](https://github.com/mikebarlow/Timezones/actions)

Introduction
------------

[](#introduction)

Timezones is a PSR-2 compliant package used for easily converting dates into UTC or into your local timezones. Bundled is also support for Laravel Facades and blade directives to make usage even easier!

Installation
------------

[](#installation)

### Composer

[](#composer)

Simply require the package via composer into your app.

```
composer require mbarlow/timezones 2.*

```

### Setup

[](#setup)

To get started simply instantiate the Timezones object with the `new` keyword in PHP.

```
    $timezones = new \MBarlow\Timezones\Timezones;
```

#### Laravel

[](#laravel)

Bundled with this package is a Laravel Service provider that is setup for auto-discovery.

If you are not using Laravel 5.5 then you can add the following Service Provider to your `config/app.php` config.

```
[
    /*
     * Package Service Providers...
     */
    \MBarlow\Timezones\TimezonesServiceProvider::class,
];
```

The service provider will bind the Timezones Object to the container allowing you to type hint in the object.

```
use MBarlow\Timezones\Timezones;
class MyController
{
    public function myControllerAction(Timezones $timezones)
    {
        //
    }
}
```

Usage
-----

[](#usage)

To use, first instantiate the object or typehint the object into your method.

### convertToUTC

[](#converttoutc)

```
    $timezones = new \MBarlow\Timezones\Timezones;

    $dateTime = '2020-08-14 12:23:00';
    $tz = 'America/New_York';
    $format = 'Y-m-d H:i:s';

    $timezones->convertToUTC($dateTime, $tz, $format);
```

```
use MBarlow\Timezones\Timezones;
class MyController
{
    public function myControllerAction(Timezones $timezones)
    {
        $dateTime = '2020-08-14 12:23:00';
        $tz = 'America/New_York';
        $format = 'Y-m-d H:i:s';

        $timezones->convertToUTC($dateTime, $tz, $format);
    }
}
```

This method should be used when parsing an user inputted date to convert it to UTC ready for storing in your database.

`$dateTime`is a required field and can either be an instance of `\DateTime` that was created with the correct local timezone or it can be a string which will be passed into an instance of `\DateTime`.

If `$dateTime` is an instance of `\DateTime` then `$tz` is not required and should default to `null`. If `$dateTime` is passed through as a string then `$tz` should either be an instance of `\DateTimeZone` or a string describing a [valid timezone](http://php.net/manual/en/timezones.php).

`$format` is an optional field that defaults to standard MySQL datetime format of `YYYY-MM-DD HH:MM:SS`.

### convertToLocal

[](#converttolocal)

```
    $timezones = new \MBarlow\Timezones\Timezones;

    $dateTime = '2020-08-14 12:23:00';
    $tz = 'America/New_York';
    $format = 'jS F Y H:i';

    $timezones->convertToLocal($dateTime, $tz, $format);
```

```
use MBarlow\Timezones\Timezones;
class MyController
{
    public function myControllerAction(Timezones $timezones)
    {
        $dateTime = '2020-08-14 12:23:00';
        $tz = 'America/New_York';
        $format = 'jS F Y H:i';

        $timezones->convertToLocal($dateTime, $tz, $format);
    }
}
```

This method should be used in your "views or in your API endpoints" to transform a UTC date stored within your database into the local timezone for the user viewing the page or requesting the data.

`$dateTime` is a required field and can either be an instance of `\DateTime` that was created with the correct UTC timezone or it can be a string which will be passed into an instance of `\DateTime`.

`$tz` is a required field and can either be an instance of `\DateTimeZone` or a string describing a [valid timezone](http://php.net/manual/en/timezones.php) and should be the timezone of the end user.

`$format` is an optional field that defaults to standard MySQL datetime format of `YYYY-MM-DD HH:MM:SS`.

### timezoneList

[](#timezonelist)

This method can be used for API endpoints or within your templates to generate an array of formatted timezones. The generated array will return an associative array with the timezone as the key and a nice label with offset as the value.

```
  $timezones = new \MBarlow\Timezones\Timezones;

  print_r($timezones->timezoneList());
  /*
    Array
    (
        [Pacific/Midway] => (UTC -11:00) Midway
        [Pacific/Niue] => (UTC -11:00) Niue
        [Pacific/Pago_Pago] => (UTC -11:00) Pago Pago
        [Pacific/Honolulu] => (UTC -10:00) Honolulu
        [Pacific/Rarotonga] => (UTC -10:00) Rarotonga
        [Pacific/Tahiti] => (UTC -10:00) Tahiti
        [Pacific/Marquesas] => (UTC -09:30) Marquesas
        [America/Adak] => (UTC -09:00) Adak
        [Pacific/Gambier] => (UTC -09:00) Gambier
        [America/Anchorage] => (UTC -08:00) Anchorage
        [America/Juneau] => (UTC -08:00) Juneau
        [America/Metlakatla] => (UTC -08:00) Metlakatla
        [America/Nome] => (UTC -08:00) Nome
        [Pacific/Pitcairn] => (UTC -08:00) Pitcairn
        [America/Sitka] => (UTC -08:00) Sitka

         ....
     )
   */
```

```
$timezones = new \MBarlow\Timezones\Timezones;
$list = $timezones->timezoneList();

echo '';
foreach ($list as $timezone => $label) {
    echo '' . $label .  '';
}
echo '';
```

Laravel Extras
--------------

[](#laravel-extras)

If you have installed the package into a Laravel application a few extra goodies are available.

### Facade

[](#facade)

Should you prefer to use a Facade, one has been bundled and made available with the Service Provider. The facade is available at `\\Timezones'.

Both methods described in the "Usage" section above are available.

```
\Timezones::convertToUTC();
\Timezones::convertToLocal();

```

### Blade Directive

[](#blade-directive)

A blade directive will also be registered by the Service Provider. This only supports the `convertToLocal` method and is designed for use within your blade templates to convert a UTC datetime into the end users time and display on the page in the correct format.

```
@displayDate($dateTime, $tz, $format)

```

All parameters match those defined for the `convertToLocal` method however all fields are required when using the blade directive.

Testing
-------

[](#testing)

If you wish to run the tests, clone out the repository

```
    git clone git@github.com:mikebarlow/Timezones.git
```

Change to the root of the repository and run composer install with the dev dependencies

```
    cd Timezones
    composer install
```

A script is defined in the `composer.json` to run both the code sniffer and the unit tests

```
    composer run test
```

Or run them individually as required

```
    ./vendor/bin/phpunit

    ./vendor/bin/phpcs --standard=PSR2 --ignore=src/Facade/* src
```

Changelog
---------

[](#changelog)

You can view the changelog [HERE](https://github.com/mikebarlow/Timezones/blob/master/CHANGELOG.md)

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/mikebarlow/Timezones/blob/master/CONTRIBUTING.md) for details.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](https://github.com/mikebarlow/Timezones/blob/master/LICENSE) for more information.

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance31

Infrequent updates — may be unmaintained

Popularity27

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 100% 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 ~333 days

Total

5

Last Release

1861d ago

Major Versions

1.0.1 → 2.0.02020-08-14

2.1.0 → 3.0.02021-04-13

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/43972359?v=4)[snsmurf](/maintainers/snsmurf)[@snsmurf](https://github.com/snsmurf)

---

Top Contributors

[![mikebarlow](https://avatars.githubusercontent.com/u/293049?v=4)](https://github.com/mikebarlow "mikebarlow (33 commits)")

---

Tags

datesdatetimelaraveltimezonesutclaravelhelpersdatetimeconversiontimezoneutc

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/mbarlow-timezones/health.svg)

```
[![Health](https://phpackages.com/badges/mbarlow-timezones/health.svg)](https://phpackages.com/packages/mbarlow-timezones)
```

###  Alternatives

[whitecube/laravel-timezones

Store UTC dates in the database and work with custom timezones in the application.

106106.2k](/packages/whitecube-laravel-timezones)[tapp/filament-timezone-field

Filament timezone field.

55276.6k4](/packages/tapp-filament-timezone-field)[phannaly/php-datetime-khmer

The PHP library for convert datetime to Khmer

1510.3k](/packages/phannaly-php-datetime-khmer)[transprime-research/piper

PHP Pipe method execution with values from chained method executions

174.6k2](/packages/transprime-research-piper)[joy2362/php-time-zone

A simple package that provide list of all timezone that php support

162.0k](/packages/joy2362-php-time-zone)[p3ym4n/jdate

Date converter from Jalali to Georgian and vice versa. It has Carbon instance inside and it's Laravel friendly.

101.8k2](/packages/p3ym4n-jdate)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)