Started branch 1.3 - model substitution

README.md

@@ -17,14 +17,22 @@ Localized Carbon is an extension of a popular Carbon package, designed specially
 <a name="usage"></a>
 ## Usage
 
-Imagine you have a `Comment` model which has default timestamp fields. You want to display, how much time has gone since its `create_at` in a human-readable format. You can achieve it this way in your Blade template:
+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.
@@ -48,18 +56,24 @@ Add the following requirement to your `composer.json`: `"laravelrus/localized-ca
 Next, add package's Service Provider to `app/config/app.php` in `providers` section:
 
 ```
-    'Laravelrus\LocalizedCarbon\LocalizedCarbonServiceProvider',
+'Laravelrus\LocalizedCarbon\LocalizedCarbonServiceProvider',
 ```
 
 After that you may want to add some Aliases (`aliases` section of the same config):
 
 ```
-        'LocalizedCarbon'   => 'Laravelrus\LocalizedCarbon\LocalizedCarbon',
-        'DiffFormatter'     => 'Laravelrus\LocalizedCarbon\DiffFactoryFacade',
+'LocalizedCarbon'   => 'Laravelrus\LocalizedCarbon\LocalizedCarbon',
+'DiffFormatter'     => 'Laravelrus\LocalizedCarbon\DiffFactoryFacade',
 ```
 
 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 substitute Laravel's Eloquent model by changing the alias for `Eloquent` (assuming that your models extend this class):
+
+```
+'Eloquent'        => 'Laravelrus\LocalizedCarbon\Models\Eloquent',
+```
+
 <a name="extending"></a>
 ## Extending Localized Carbon
 

docs/README-ru.md

@@ -15,14 +15,22 @@
 <a name="usage"></a>
 ## Использование
 
-Представте, что у вас есть модель `Comment` (комментарий), в которой имеются временные поля по умолчанию (`created_at` и `updated_at`). И вам требуется вывести информацию о том, сколько времени прошло с момента создания комментария (поле `created_at`), в удобочитаемом формате. Это можно сделать следующим образом в Blade-шаблоне:
+Этот пакет предоставляет класс `LocalizedCarbon`, который наследует оригинальный `Carbon`, поэтому его использование ничем не отличается от оригинального Carbon'а.
+
+Но представте, что у вас есть модель `Comment` (комментарий), в которой имеются временные поля по умолчанию (`created_at` и `updated_at`). И вам требуется вывести информацию о том, сколько времени прошло с момента создания комментария (поле `created_at`), в удобочитаемом формате. Это можно сделать несколькими способами, например так (в Blade-шаблоне):
 
 ```
 {{ LocalizedCarbon::instance($comment->created_at)->diffForHumans() }}
 ```
 
 В этом случае класс выведет что-то вроде "5 минут назад" для русского языка.
 
+Но есть и другой способ. Вы можете подменить имеющийся в Laravel класс Eloquent\Model при помощи поставляемого с пакетом классаа модели, чтобы временные поля, наподобие `created_at` и т.д., конвертировались в `LocalizedCarbon`, вместо `Carbon`. Таким образом, использование `LocalizedCarbon` ничем не будет отличаться от привычного:
+
+```
+{{ $comment->created_at->diffForHumans() }}
+```
+
 Как и в исходном Carbon'е, метод `diffForHumans` имеет первый необязательный аргумент (который является другим экземпляром класса `Carbon`). Он указывает время, относительно которого вычислять разницу. По умолчанию (если этот параметр не задан, или равен `null`) используется текущее время.
 
 В методе классе `LocalizedCarbon` имеется и второе необязательный аргумент, в котором вы можете указать желаемый язык, или напрямую класс-форматтер, используемый для формирования строки-разницы между временами (см. [расширение](#extending)). По умолчанию будет использоваться текущий язык приложения. Также, в качестве второго аргумента можно передавать замыкание, которое будет форматировать строку. Параметры этого замыкания аналогичные метода `format` интерфейса `DiffFormatterInterface` (см. раздел [Расширение Localzied Carbon](#extending)).
@@ -58,6 +66,12 @@
 
 Стоит отметить, что класс `DiffFormatter` будет использоваться только для расширения пакета дополнительными локализациями. См. [расширение пакета](#extending).
 
+Если вы хотите использовать `LocalizedCarbon` привычным способом, то можете подменить класс Eloquent-модели путем изменения соответствующего алиаса `Eloquent` в конфиге:
+
+```
+'Eloquent'        => 'Laravelrus\LocalizedCarbon\Models\Eloquent',
+```
+
 <a name="extending"></a>
 ## Расширение пакета
 

src/Laravelrus/LocalizedCarbon/Models/Eloquent.php

@@ -0,0 +1,44 @@
+<?php namespace Laravelrus\LocalizedCarbon\Models;
+
+
+use Illuminate\Database\Eloquent\Model;
+use Laravelrus\LocalizedCarbon\LocalizedCarbon;
+
+class Eloquent extends Model {
+    /**
+     * Return a timestamp as DateTime object.
+     *
+     * @param  mixed  $value
+     * @return \Laravelrus\LocalizedCarbon\LocalizedCarbon
+     */
+    protected function asDateTime($value)
+    {
+        // If this value is an integer, we will assume it is a UNIX timestamp's value
+        // and format a Carbon object from this timestamp. This allows flexibility
+        // when defining your date fields as they might be UNIX timestamps here.
+        if (is_numeric($value))
+        {
+            return LocalizedCarbon::createFromTimestamp($value);
+        }
+
+        // If the value is in simply year, month, day format, we will instantiate the
+        // Carbon instances from that format. Again, this provides for simple date
+        // fields on the database, while still supporting Carbonized conversion.
+        elseif (preg_match('/^(\d{4})-(\d{2})-(\d{2})$/', $value))
+        {
+            return LocalizedCarbon::createFromFormat('Y-m-d', $value)->startOfDay();
+        }
+
+        // Finally, we will just assume this date is in the format used by default on
+        // the database connection and use that format to create the Carbon object
+        // that is returned back out to the developers after we convert it here.
+        elseif ( ! $value instanceof \DateTime)
+        {
+            $format = $this->getDateFormat();
+
+            return LocalizedCarbon::createFromFormat($format, $value);
+        }
+
+        return LocalizedCarbon::instance($value);
+    }
+}