diff --git a/README.md b/README.md index 74d0ea0..02a8dff 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,14 @@ A wrapper to enumerate PHP 5.4+, 7+ timezones in a simplified way for use in var This is done with Laravel 5.x in mind, but may work elsewhere. YMMV elsewhere. ### Basics -- Creates timezone arrays based on PHP's supported timezones with optional grouping by region +- Creates timezone arrays based on PHP's supported timezones with optional grouping by region +- Lists are sorted by offset from high (+14:00) to low (-11:00) - Optionally group the arrays (multi-dim associated array) by region + + sorting is the same, but only inside each region - For either case, return those as: + php arrays for whatever use your heart desires - + HTMLjessedp/timezones select list + + HTML select list +- 2 utility functions for converting to/from UTC ## Installation @@ -19,7 +22,7 @@ You can install this package using [Composer](https://getcomposer.org). ```php ... "require": { - ... + ... "jessedp/php-timezones": "0.1" }, ``` @@ -30,7 +33,7 @@ You can install this package using [Composer](https://getcomposer.org). $ composer update ``` -- Finally, after the update completes, add the service provider. Open `config/app.php` and add a new item to the **providers**' array: +- Finally, after the update completes, add the service provider. Open `config/app.php` and add a new item to the **providers** array: ```php ... @@ -42,7 +45,7 @@ $ composer update ## Usage -###### 1. Render a timezone listbox +#### 1. Render a timezone HTML Select list The method `Timezones::create()` has three parameters: ```php @@ -51,11 +54,11 @@ Timezones::create($name, $selected, $opts); - $name **required** - the *name* of the select element - $selected - sets the selected value of list box, assuming the a value with the option exists - $opts an array of options as key=>value: - + attr => array of key=>value pairs to be included in the select element (ie, 'id', 'class') + + attr => *array* of key=>value pairs to be included in the select element (ie, 'id', 'class', etc.) + with_regions => *boolean* whether or not to use option groups for the regions/continents (defaults to false) + regions => array (of strings) specifying the region(s) to include -Basic Example: +###### Basic Example: ```php Timezones::create('timezone'); ``` @@ -71,23 +74,24 @@ Returns a string similar to: [ - 'id' => 'my_id', - 'class' => 'form-control' - ] +Timezones::create('timezone', null, + ['attr'=>[ + 'id' => 'my_id', + 'class' => 'form-control' + ] ]); ``` @@ -103,9 +107,9 @@ Which gives us: ... -Example: +###### "Regions/Grouping" Example: -Say you want the option groups but only a few regions... +Say you want the option groups but only a couple regions... ```php Timezones::create('timezone',null, @@ -134,9 +138,8 @@ This will return a string similar to the following: -``` -###### 2. Render a timezone array +#### 2. Render a timezone array You can also render timezone list as an array. To do so, just use the `Timezones::toArray()` method. @@ -145,6 +148,19 @@ Example in Laravel: $timezone_list = Timezones::toArray(); ``` +#### 3. Utility methods +The package includes two methods that make it easy to deal with displaying and storing timezones, `convertFromUTC()` and `convertToUTC()`: + +Each function accepts two required parameters and a third optional parameter dealing with the format of the returned timestamp. + + Timezones::convertFromUTC($timestamp, $timezone, $format); + Timezones::convertToUTC($timestamp, $timezone, $format); + +The first parameter accepts a timestamp, the second accepts the name of the timezone that you are converting to/from. The option values associated with the timezones included in the select form builder can be plugged into here as is. Alternatively, you can use any of [PHP's supported timezones](http://php.net/manual/en/timezones.php). + +The third parameter is optional, and default is set to `'Y-m-d H:i:s'`, which is how Laravel natively stores datetimes into the database (the `created_at` and `updated_at` columns). If you're using this for display purposes, you may find including `'(e)'` in the format string which displays the timezone. + + # Thanks to... This is based off some lovely work by: