README

简介

Timezones 是一个符合 PSR-2 规范的包，用于轻松将日期转换为 UTC 或本地时区。还包括对 Laravel Facades 和 blade 指令的支持，以便更轻松地使用！

安装

Composer

只需通过 composer 将包添加到您的应用中。

composer require mbarlow/timezones 2.*

设置

要开始，只需使用 PHP 的 new 关键字实例化 Timezones 对象。

    $timezones = new \MBarlow\Timezones\Timezones;

Laravel

此包附带一个 Laravel 服务提供器，已设置自动发现。

如果您不在使用 Laravel 5.5，则可以将以下服务提供器添加到您的 config/app.php 配置文件中。

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

服务提供器将 Timezones 对象绑定到容器中，允许您在对象中进行类型提示。

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

用法

要使用，首先实例化对象或将对象类型提示到您的函数中。

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);
    }
}

此方法应在解析用户输入的日期并将其转换为数据库存储的 UTC 之前使用。

$dateTime 是必填字段，可以是使用正确本地时区创建的 \DateTime 实例，也可以是传递给 \DateTime 实例的字符串。

如果 $dateTime 是 \DateTime 实例，则 $tz 不是必需的，默认为 null。如果通过字符串传递 $dateTime，则 $tz 应为 \DateTimeZone 实例或描述有效时区的字符串。

$format 是可选字段，默认为标准 MySQL 日期时间格式 YYYY-MM-DD HH:MM:SS。

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);
    }
}

此方法应在您的“视图或 API 端点”中使用，以将数据库中存储的 UTC 日期转换为查看页面或请求数据的用户的本地时区。

$dateTime 是必填字段，可以是使用正确 UTC 时区创建的 \DateTime 实例，也可以是传递给 \DateTime 实例的字符串。

$tz 是必填字段，可以是 \DateTimeZone 实例或描述有效时区的字符串，并且应该是最终用户的时区。

$format 是可选字段，默认为标准 MySQL 日期时间格式 YYYY-MM-DD HH:MM:SS。

timezoneList

此方法可用于API端点或您的模板中，以生成一个格式化的时区数组。生成的数组将返回一个关联数组，以时区作为键，以包含偏移的漂亮标签作为值。

  $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 '<select="timezone">';
foreach ($list as $timezone => $label) {
    echo '<option value="' . $timezone . '">' . $label .  '</option>';
}
echo '</select>';

Laravel 扩展

如果您已将包安装到 Laravel 应用中，则有一些额外的功能可用。

外观

如果您希望使用外观，已包含一个外观，并通过 Service Provider 提供使用。外观在 `\Timezones` 中可用。

上面“用法”部分中描述的两种方法都可用。

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

Blade 指令

Service Provider 还将注册一个 blade 指令。这仅支持 convertToLocal 方法，并设计用于在您的 blade 模板中使用，将 UTC 日期时间转换为最终用户的时区，并在页面上以正确的格式显示。

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

所有参数都与 convertToLocal 方法中定义的参数匹配，但是当使用 blade 指令时，所有字段都是必需的。

测试

如果您想运行测试，请克隆出存储库

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

切换到存储库的根目录，并使用 composer install 运行 dev 依赖项

    cd Timezones
    composer install

在 composer.json 中定义了一个脚本来运行代码规范器和单元测试

    composer run test

或根据需要单独运行它们

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

变更日志

您可以在此处查看变更日志

贡献

有关详细信息，请参阅CONTRIBUTING

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件