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 应用程序中，则有一些额外的功能可用。

外观

如果您更喜欢使用外观，则已捆绑并提供了一个，通过服务提供者可用。外观位于 `\Timezones`。

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

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

Blade 指令

服务提供者也会注册一个刀片指令。这仅支持 convertToLocal 方法，并设计用于在您的刀片模板中使用，将UTC日期时间转换为最终用户的时区时间，并在页面上以正确的格式显示。

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

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

测试

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

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

切换到仓库的根目录，并使用 composer install 命令安装开发依赖项

    cd Timezones
    composer install

在 composer.json 中定义了一个脚本来同时运行代码检查器和单元测试

    composer run test

或者根据需要单独运行它们

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

更新日志

您可以通过此处查看更新日志

贡献

请参阅CONTRIBUTING以获取详细信息。

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

mbarlow / timezones

维护者

详细信息