diff --git a/README.md b/README.md index 7b68712..e7fd173 100644 --- a/README.md +++ b/README.md @@ -1,164 +1,165 @@ -# Maintainers needed -Sorry, I have not much time supporting this repo. Also I rarely work with Laravel now, so new maintainers are needed. - -# Localized Carbon - -for **L4** use **1.4** branch -for **L5.4** use **2.2** -for **>=L5.5** use **2.3** - -See also [localized documentation](docs) - -+ [Introduction](#intro) -+ [Installation](#installation) -+ [Usage](#usage) -+ [Supported languages](#languages) -+ [Extending](#extending) -+ [Contributing](#contributing) - - -## Introduction - -Localized Carbon is an extension of a popular Carbon package, designed specially for Laravel framework. By localization I mean its `diffForHumans` function, which returns a human-readable string of time interval. This package also supports genitive months by introducing the "%f" key in `formatLocalized` method. - - - -## Installation - -Add the following requirement to your `composer.json`: `"laravelrus/localized-carbon": "1.*"` and then run `composer update`. - -Next, add package's Service Provider to `app/config/app.php` in `providers` section: - -``` -'Laravelrus\LocalizedCarbon\LocalizedCarbonServiceProvider', -``` - -After that you may want to add some Aliases (`aliases` section of the same config): - -``` -'LocalizedCarbon' => Laravelrus\LocalizedCarbon\LocalizedCarbon::class, -'DiffFormatter' => Laravelrus\LocalizedCarbon\DiffFactoryFacade::class, -``` - -Note that `DiffFormatter` will only be used for extending default localizations. See [extending Localized Carbon](#extending). - -If you want to use the power of `LocalizedCarbon` the same way as you did with original `Carbon` in your models, you may want to use supplied trait for this in your models: - -``` -use \Laravelrus\LocalizedCarbon\Traits\LocalizedEloquentTrait; -``` - -In this case `LocalizedCarbon` will be used for all dates in your Eloquent model instead of original `Carbon`. - -Note that this method is actual for PHP versions 5.4 and higher. - -If you are still using PHP 5.3.7 you can substitute Laravel's Eloquent class by `Laravelrus\LocalizedCarbon\Models\Eloquent` supplied with this package. To do this you can either inherit this class directly, or make an alias to it instead of originial Eloquent in `app\config\app.php`. - - - -## Usage - -This package provides a `LocalizedCarbon` class which inherits original Carbon, so its usage is absolutely the same as original Carbon's. - -But imagine you have a `Comment` model for example, which has default timestamp fields (`created_at` and `updated_at`). You want to display, how much time has gone since its `created_at` in a human-readable format. One way to achieve may be such (in your Blade template): - -``` -{{ LocalizedCarbon::instance($comment->created_at)->diffForHumans() }} -``` - -In this case the class will output something like "5 minutes ago". Note that for just an English version of the string original Carbon would be enough. This `LocalizedCarbon` is used to display the message in the current application language. For example, for Russian language it will display "5 минут назад". - -But also, you may substitute Laravel's Eloquent model, so the timestamps would be converted to `LocalizedCarbon` instead of original `Carbon`. So the usage could be as if your were using original Carbon: - -``` -{{ $comment->created_at->diffForHumans() }} -``` - -As in original Carbon, `diffForHumans` functions has an optional first argument (which is another Carbon instance). It specified the time to which difference should be calculated. By default (a missing or `null` value) current time is used. - -Also `LocalizedCarbon` adds an optional second argument, in which you may specify the desired language, or directly a `formatter` class which is used to format the difference-string (see [extending Localized Carbon](#extending)). By default current application language is used. Also you may specify a Closure in the second parameter which will do formatting. For its signature refer to [extending Localized Carbon](#extending) section. - - -## Supported languages - -Current version of Localized Carbon ships with these localizations: - -+ English (en) (full) -+ Russian (ru) (full) -+ Ukrainian (uk) (full) -+ Dutch (nl) (no genitive) -+ Spanish (es) (full) -+ Portuguese (pt) (no genitive) -+ French (fr) (no genitive) -+ Bulgarian (bg) (no genitive) -+ Slovakian (sk) (no genitive) -+ Turkish (tr) (no genitive) -+ Arabic (ar) (no genitive) -+ Japanese (ja) (full) -+ Bengali (bn) (full) -+ Persian (fa) (full) - - -But it is extendable, so you may write and use your own localization without altering the contents of the package. See [extending Localized Carbon](#extending). - - - - -## Extending Localized Carbon - -If needed localization is not shipped with this package, you may write your own and extend Localized Carbon with it, not even touching the vendor folder itself. - -There are a couple of ways to extend Localized Carbon. - -First, you may write your own `DiffFormatter` class for this, implementing `Laravelrus\LocalizedCarbon\DiffFormatters\DiffFormatterInterface`. This interface forces the class to have a single `format` method which looks like this: - -``` -public function format($isNow, $isFuture, $delta, $unit); -``` - -`$isNow` is a boolean, which is `true` when the time difference is calculated relevant to current time. -`$isFuture` is boolean, which is `true` if the DateTime object is in the future relevant to comparable time. -`$delta` is an integer, equals to number of units of difference. -`$unit` is a time-"unit". It can be either: `second`, `minute`, `hour`, `day`, `week`, `month` or `year`. - -So, your `format` method should return a string based on this arguments. As an example see an existing DiffFormatters in `vendor\laravelrus\localized-carbon\src\Laravelrus\LocalizedCarbon\DiffFormatters` directory. You can also reference a lang-files, using `Lang::choice` as it is done in Russian localization for example. - -When your class is ready, you must register it within the Localized Carbon. For this you must call `DiffFormatter::extend` method from within any file which is loaded by the framework. For example, you can do it somewhere in `app/start/global.php`. - -The `extend` method expects two parameters: first is the language you want to be supported (most often it would be `App::getLocale()` if you want just to use application's language). Next is the instance of your formatter, OR just a name of the class if it can be autoloaded. Consider these examples: - -``` -$formatter = new Acme\DiffFormatters\FrDiffFormatter; -DiffFormatter::extend('fr', $formatter); - -// OR - -DiffFormatter::extend('fr', 'Acme\\DiffFormatters\\FrDiffFormatter'); -``` - -In the latter case the formatter will be autoloaded when it is needed using IoC. Also note that formatter is loaded only once during application life-cycle due to optimization considerations. - -The second way to extend is to pass a Closure as the second parameter. It must have the same signature as the `format` method of `DiffFormatterInterface` interface. For example: - -``` -DiffFormatter::extend('fr', function($isNow, $isFuture, $delta, $unit) { - return 'Some formatter diff string!'; -}); -``` - -Also, there is a possibility to add an alias for an existing language. For example, Localized Carbon is shipped with Ukranian localization, which is recognized by `uk` language key. But what if your application uses `ua` or `ukr` language, which still means it is Ukranian? In this case you may add an alias for `uk` language in this way: - -``` -DiffFormatter::alias('ukr', 'uk'); -``` - - -## Contributing - -If you've written a formatter for the language which is not supported by current version of Localized Carbon out of the box - feel free to make a pull request with it in the current version branch (1.3), but be sure to adjust your formatter for been used by the package. - -The formatter should lie in `src/Laravelrus/LocalizedCarbon/DiffFormatters` directory, following a simple naming convention: the class name should start with the desired language in lower-case, but the first letter in upper-case. The rest part of the name should be "DiffFormatter". The file name should correspond to the class name. - -For example, the formatter for `fr` language would lie in `src/Laravelrus/LocalizedCarbon/DiffFormatters/FrDiffFormatter.php`, and the class name would be `FrDiffFormatter`. - -Also I need the help of the community to complete the list of genitives for all supported languages. If you know a language and it uses genitives in dates, feel free to contribute. See an example of Russian or Ukranian `lang\XX\months.php` files. +# Maintainers needed +Sorry, I have not much time supporting this repo. Also I rarely work with Laravel now, so new maintainers are needed. + +# Localized Carbon + +for **L4** use **1.4** branch +for **L5.4** use **2.2** +for **>=L5.5** use **2.3** + +See also [localized documentation](docs) + ++ [Introduction](#intro) ++ [Installation](#installation) ++ [Usage](#usage) ++ [Supported languages](#languages) ++ [Extending](#extending) ++ [Contributing](#contributing) + + +## Introduction + +Localized Carbon is an extension of a popular Carbon package, designed specially for Laravel framework. By localization I mean its `diffForHumans` function, which returns a human-readable string of time interval. This package also supports genitive months by introducing the "%f" key in `formatLocalized` method. + + + +## Installation + +Add the following requirement to your `composer.json`: `"laravelrus/localized-carbon": "1.*"` and then run `composer update`. + +Next, add package's Service Provider to `app/config/app.php` in `providers` section: + +``` +'Laravelrus\LocalizedCarbon\LocalizedCarbonServiceProvider', +``` + +After that you may want to add some Aliases (`aliases` section of the same config): + +``` +'LocalizedCarbon' => Laravelrus\LocalizedCarbon\LocalizedCarbon::class, +'DiffFormatter' => Laravelrus\LocalizedCarbon\DiffFactoryFacade::class, +``` + +Note that `DiffFormatter` will only be used for extending default localizations. See [extending Localized Carbon](#extending). + +If you want to use the power of `LocalizedCarbon` the same way as you did with original `Carbon` in your models, you may want to use supplied trait for this in your models: + +``` +use \Laravelrus\LocalizedCarbon\Traits\LocalizedEloquentTrait; +``` + +In this case `LocalizedCarbon` will be used for all dates in your Eloquent model instead of original `Carbon`. + +Note that this method is actual for PHP versions 5.4 and higher. + +If you are still using PHP 5.3.7 you can substitute Laravel's Eloquent class by `Laravelrus\LocalizedCarbon\Models\Eloquent` supplied with this package. To do this you can either inherit this class directly, or make an alias to it instead of originial Eloquent in `app\config\app.php`. + + + +## Usage + +This package provides a `LocalizedCarbon` class which inherits original Carbon, so its usage is absolutely the same as original Carbon's. + +But imagine you have a `Comment` model for example, which has default timestamp fields (`created_at` and `updated_at`). You want to display, how much time has gone since its `created_at` in a human-readable format. One way to achieve may be such (in your Blade template): + +``` +{{ LocalizedCarbon::instance($comment->created_at)->diffForHumans() }} +``` + +In this case the class will output something like "5 minutes ago". Note that for just an English version of the string original Carbon would be enough. This `LocalizedCarbon` is used to display the message in the current application language. For example, for Russian language it will display "5 минут назад". + +But also, you may substitute Laravel's Eloquent model, so the timestamps would be converted to `LocalizedCarbon` instead of original `Carbon`. So the usage could be as if your were using original Carbon: + +``` +{{ $comment->created_at->diffForHumans() }} +``` + +As in original Carbon, `diffForHumans` functions has an optional first argument (which is another Carbon instance). It specified the time to which difference should be calculated. By default (a missing or `null` value) current time is used. + +Also `LocalizedCarbon` adds an optional second argument, in which you may specify the desired language, or directly a `formatter` class which is used to format the difference-string (see [extending Localized Carbon](#extending)). By default current application language is used. Also you may specify a Closure in the second parameter which will do formatting. For its signature refer to [extending Localized Carbon](#extending) section. + + +## Supported languages + +Current version of Localized Carbon ships with these localizations: + ++ English (en) (full) ++ Russian (ru) (full) ++ Ukrainian (uk) (full) ++ Dutch (nl) (no genitive) ++ Spanish (es) (full) ++ Portuguese (pt) (no genitive) ++ French (fr) (no genitive) ++ Bulgarian (bg) (no genitive) ++ Slovakian (sk) (no genitive) ++ Turkish (tr) (no genitive) ++ Arabic (ar) (no genitive) ++ Japanese (ja) (full) ++ Bengali (bn) (full) ++ Pashto (Pa) (full) ++ Persian (fa) (full) + + +But it is extendable, so you may write and use your own localization without altering the contents of the package. See [extending Localized Carbon](#extending). + + + + +## Extending Localized Carbon + +If needed localization is not shipped with this package, you may write your own and extend Localized Carbon with it, not even touching the vendor folder itself. + +There are a couple of ways to extend Localized Carbon. + +First, you may write your own `DiffFormatter` class for this, implementing `Laravelrus\LocalizedCarbon\DiffFormatters\DiffFormatterInterface`. This interface forces the class to have a single `format` method which looks like this: + +``` +public function format($isNow, $isFuture, $delta, $unit); +``` + +`$isNow` is a boolean, which is `true` when the time difference is calculated relevant to current time. +`$isFuture` is boolean, which is `true` if the DateTime object is in the future relevant to comparable time. +`$delta` is an integer, equals to number of units of difference. +`$unit` is a time-"unit". It can be either: `second`, `minute`, `hour`, `day`, `week`, `month` or `year`. + +So, your `format` method should return a string based on this arguments. As an example see an existing DiffFormatters in `vendor\laravelrus\localized-carbon\src\Laravelrus\LocalizedCarbon\DiffFormatters` directory. You can also reference a lang-files, using `Lang::choice` as it is done in Russian localization for example. + +When your class is ready, you must register it within the Localized Carbon. For this you must call `DiffFormatter::extend` method from within any file which is loaded by the framework. For example, you can do it somewhere in `app/start/global.php`. + +The `extend` method expects two parameters: first is the language you want to be supported (most often it would be `App::getLocale()` if you want just to use application's language). Next is the instance of your formatter, OR just a name of the class if it can be autoloaded. Consider these examples: + +``` +$formatter = new Acme\DiffFormatters\FrDiffFormatter; +DiffFormatter::extend('fr', $formatter); + +// OR + +DiffFormatter::extend('fr', 'Acme\\DiffFormatters\\FrDiffFormatter'); +``` + +In the latter case the formatter will be autoloaded when it is needed using IoC. Also note that formatter is loaded only once during application life-cycle due to optimization considerations. + +The second way to extend is to pass a Closure as the second parameter. It must have the same signature as the `format` method of `DiffFormatterInterface` interface. For example: + +``` +DiffFormatter::extend('fr', function($isNow, $isFuture, $delta, $unit) { + return 'Some formatter diff string!'; +}); +``` + +Also, there is a possibility to add an alias for an existing language. For example, Localized Carbon is shipped with Ukranian localization, which is recognized by `uk` language key. But what if your application uses `ua` or `ukr` language, which still means it is Ukranian? In this case you may add an alias for `uk` language in this way: + +``` +DiffFormatter::alias('ukr', 'uk'); +``` + + +## Contributing + +If you've written a formatter for the language which is not supported by current version of Localized Carbon out of the box - feel free to make a pull request with it in the current version branch (1.3), but be sure to adjust your formatter for been used by the package. + +The formatter should lie in `src/Laravelrus/LocalizedCarbon/DiffFormatters` directory, following a simple naming convention: the class name should start with the desired language in lower-case, but the first letter in upper-case. The rest part of the name should be "DiffFormatter". The file name should correspond to the class name. + +For example, the formatter for `fr` language would lie in `src/Laravelrus/LocalizedCarbon/DiffFormatters/FrDiffFormatter.php`, and the class name would be `FrDiffFormatter`. + +Also I need the help of the community to complete the list of genitives for all supported languages. If you know a language and it uses genitives in dates, feel free to contribute. See an example of Russian or Ukranian `lang\XX\months.php` files. diff --git a/src/Laravelrus/LocalizedCarbon/DiffFormatters/FaDiffFormatter.php b/src/Laravelrus/LocalizedCarbon/DiffFormatters/FaDiffFormatter.php new file mode 100644 index 0000000..8beb701 --- /dev/null +++ b/src/Laravelrus/LocalizedCarbon/DiffFormatters/FaDiffFormatter.php @@ -0,0 +1,20 @@ +tz); - } - - $isFuture = $this->gt($other); - - $delta = $other->diffInSeconds($this); - - // 4.35 weeks per year. 365 days in a year, 12 months, 7 days in a week: - // 365/12/7 = 4.345238095238095 4.35 is good enough for big time calculations! - $divs = array( - 'second' => self::SECONDS_PER_MINUTE, - 'minute' => self::MINUTES_PER_HOUR, - 'hour' => self::HOURS_PER_DAY, - 'day' => self::DAYS_PER_WEEK, - 'week' => 4.35, - 'month' => self::MONTHS_PER_YEAR - ); - - $unit = 'year'; - - foreach ($divs as $divUnit => $divValue) { - if ($delta < $divValue) { - $unit = $divUnit; - break; - } - - $delta = floor($delta / $divValue); - } - - if ($delta == 0) { - $delta = 1; - } - - // Format and return - $result = null; - if ($formatter instanceof DiffFormatterInterface) { - $result = $formatter->format($isNow, $isFuture, $delta, $unit); - } elseif ($formatter instanceof \Closure) { - $result = $formatter($isNow, $isFuture, $delta, $unit); - } - - return $result; - } - - public function formatLocalized($format = self::COOKIE) { - if (strpos($format, '%f') !== false) { - $langKey = strtolower(parent::format("F")); - $replace = \Lang::get("localized-carbon::months." . $langKey); - $result = str_replace('%f', $replace, $format); - } else { - $result = $format; - } - - $result = parent::formatLocalized($result); - - return $result; - } -} +tz); + } + + $isFuture = $this->gt($other); + + $delta = $other->diffInSeconds($this); + + // 4.35 weeks per year. 365 days in a year, 12 months, 7 days in a week: + // 365/12/7 = 4.345238095238095 4.35 is good enough for big time calculations! + $divs = array( + 'second' => self::SECONDS_PER_MINUTE, + 'minute' => self::MINUTES_PER_HOUR, + 'hour' => self::HOURS_PER_DAY, + 'day' => self::DAYS_PER_WEEK, + 'week' => 4.35, + 'month' => self::MONTHS_PER_YEAR + ); + + $unit = 'year'; + + foreach ($divs as $divUnit => $divValue) { + if ($delta < $divValue) { + $unit = $divUnit; + break; + } + + $delta = floor($delta / $divValue); + } + + if ($delta == 0) { + $delta = 1; + } + + // Format and return + $result = null; + if ($formatter instanceof DiffFormatterInterface) { + $result = $formatter->format($isNow, $isFuture, $delta, $unit); + } elseif ($formatter instanceof \Closure) { + $result = $formatter($isNow, $isFuture, $delta, $unit); + } + + return $result; + } + + public function formatLocalized($format = self::COOKIE) { + if (strpos($format, '%f') !== false) { + $langKey = strtolower(parent::format("F")); + $replace = \Lang::get("localized-carbon::months." . $langKey); + $result = str_replace('%f', $replace, $format); + } else { + $result = $format; + } + + $result = parent::formatLocalized($result); + + return $result; + } +} diff --git a/src/lang/fa/units.php b/src/lang/fa/units.php index 1f2c332..998413f 100644 --- a/src/lang/fa/units.php +++ b/src/lang/fa/units.php @@ -1,10 +1,11 @@ "ثانیه", - "minute" => "دقیقه", - "hour" => "ساعت", - "day" => "روز", - "week" => "هفته", - "month" => "ماه", - "year" => "سال", + "minute" => "[0,10] دقیقه|[11,Inf] دقیقه", + "hour" => "[0,10] ساعت|[11,Inf] ساعت", + "day" => "[0,10] روز|[11,Inf] روز", + "week" => "[0,10] هفته|[11,Inf] هفته", + "month" => "[0,10] ماه|[11,Inf] ماه", + "year" => "[0,10] سال|[11,Inf] سال", ); diff --git a/src/lang/pa/units.php b/src/lang/pa/units.php new file mode 100644 index 0000000..73c2932 --- /dev/null +++ b/src/lang/pa/units.php @@ -0,0 +1,11 @@ + "ثانیه", + "minute" => "[0,10] دقیقه|[11,Inf] دقیقو", + "hour" => "[0,10] ساعت|[11,Inf] ساعته", + "day" => "[0,10] ورځ|[11,Inf] ورځي", + "week" => "[0,10] اونۍ|[11,Inf] اونۍ", + "month" => "[0,10] میاشت|[11,Inf] میاشتي", + "year" => "[0,10] کال|[11,Inf] کاله", +);