README

如何使用

增强你的模型以生成任何图像的不同版本（例如缩略图/水印等）。生成的图像将保存在独立的子文件夹中，以便于未来的请求。你只需在Image上定义一些操作。文件管理和缓存将由你处理。你可以使用任何本地或远程文件系统！

安装

此包依赖于Intervention包来操作图像。

首先你应该安装Intervention：[阅读说明](http://image.intervention.io)。别忘了发布它的配置文件，我们将在那里放置一些选项！

接下来，你可以使用以下命令安装此包：

composer require "igaster/laravel-image-versions"

如何使用

此包装饰任何包含图像表示的Eloquent模型。要实现它，请按照以下步骤操作

1. 设置你的模型

你的模型应该使用ImageVersionsTrait。例如

class Photo extends Eloquent {
   use \igaster\imageVersions\ImageVersionsTrait;
   //...
}

你的模型唯一的要求是定义relativePath()方法，该方法将返回文件路径（相对于public文件夹）。例如，如果你将你的图像放置在Photos文件夹中，并将裸文件名存储在filename属性中，则你的实现可以是

class Photo extends Eloquent {

    public function relativePath(){        // No starting or trailing slashes
        return 'Photos\'.$this->filename;  // example output: "Photos\image1.jpg" 
    }

}

PS：如果你使用Amazon S3（或任何其他flysystem磁盘），则此方法应返回从磁盘根目录到你的文件的路径。

2. 创建你的转换类

你可以为单个图像创建任意数量的版本。要定义一个版本，你需要创建一个扩展AbstractTransformation的转换类，并实现apply()方法。你将收到一个Intervention\Image\Image对象，你可以在其中执行任何操作。

转换类的简例

use Intervention\Image\Image;

class v200x200 extends \igaster\imageVersions\AbstractTransformation{

    public function apply(Image $image){
        // Perform here any operations on the $image object, eg:
        $image->crop(200, 200);
    }

}

Intervention包提供了一套丰富的API来编辑你的图像。请参阅他们的文档以获取所有可用方法的列表

3. 请求图像版本

非常简单！在你的Eloquent模型上调用version()方法。（以下示例假设Photo类是一个存储图像文件名的Eloquent模型）

$photo = Photo::find(1)                      // Photo can be any Eloquent model in your application
$thumb = $photo->version(v200x200::class);   // Get the `v200x200' version of your $photo

以下是将要发生的事情

• 你的原始图像将从磁盘加载
• 它将被传递给v200x200转换类（将调用apply()方法）
• 新的图像将使用相同的名称保存在以你的转换名称命名的子文件夹中（这里为v200x200）
• 下次你请求相同图像的相同版本时，你将收到已保存的版本！按请求+缓存构建！

在收到的$thumb对象上，你可以检索有关图像新版本的信息

$thumb->url() // the url to your image (eg /Photos/v200x200/filename.jpg)
$thumb->relativePath() // path relative to public  (eg Photos/v200x200/filename.jpg)
$thumb->absolutePath() // absolute path (valid only on local filesystem). You can perform file operations on it

如果你想强制重新构建新图像，即使它之前已被缓存，你也可以调用rebuildVersion()而不是version()

传递参数

在请求图像版本时，你可以传递任意数量的参数

$cropped = $photo->version(vCrop::class, 200, 300);

你将在你的转换类的apply()方法中收到这些值作为额外的参数

public function apply(Image $image, $width, $height){
    $image->cropImage($width, $height, 0, 0);
}

请注意，只有在新的图像不存在时才会执行转换。如果之前已经调用过，则将返回存储的图像而不是创建一个新的。

使用 Flysystem 磁盘（例如 Amazon S3）

您可以将本地文件系统与任何远程文件系统（例如 Amazon S3）交换。

• 首先在您的 'filesystems.php' 配置文件中定义您的文件系统磁盘
• 现在将这些选项复制到 'image.php' 配置文件中（它是由 Intervention 包提供的）

'versions' => [

    /*
    |  Set the disk that you want to use. Can be any disk defined in 'filesystems.php' 
    |  Leave null to default to your public folder.
    */

    'disk' => 's3',

    /*
    |  You can set here the endpoind of you filesystem. This will be used to get a url() for your
    |  images. Leave null if you are saving localy
    */

    'root_url' => 'my_bucket.s3-website-eu-west-1.amazonaws.com',
]

使用别名

您可以在 image.php 配置文件中定义 Transformation 类的默认命名空间

'versions' => [

    /*
    |  This is the namespace of your Transformation classes. If you define this then
    |  you can either use the full transformation's class name, or the short class name
    |  when you are calling the version() method. Default: null
    */

    'namespace' => Namespace\Of\Transformations\Classes,
]

现在您可以选择使用 Transformation 类的简短名称作为别名，而不是完整的命名空间类名。例如

$photo = Photo::find(1);

// The following are equivalent:
$thumb = $photo->version(Namespace\Of\Transformations\Classes\v200x200::class);
$thumb = $photo->version('v200x200');

当您在 Blade 文件中使用图像版本时，这非常有用。

保存生命周期

在保存新图像之前和之后，将从您的 Transformation 类中触发两个回调。如果您的类需要额外的功能，您可以实现这些方法

class v200x200 extends \igaster\imageVersions\AbstractTransformation{

	/**
     * This callback is executed before the image is saved. You can override this
     * if you want to prepere the image for saving (eg set file format etc). 
     * 
     * @param  \Intervention\Image\Image $image
     * @return null
     */	
    public function onSaving(\Intervention\Image\Image $image){
        $image->encode('jpg', 75);  
    }

	/**
     * This callback is executed when the image is sucessfuly saved.
     * It receives the decorated (Version) Eloquent model that encapsulates the Image. 
     * You can perform any post-save actions here (eg update your db / fire events etc) 
     * 
     * @param  Version $version (Your original Eloquent model decorated)
     * @return null
     */	
    public function onSaved(Version $image){
    	/* examples:
			$image->id;              // Access your original Eloquent model's attributes/methods
            $image->url();           // created image's url
            $image->relativePath();  // created image's relative path
            $image->absolutePath();  // created image's absolute (valid only on local filesystem)
		*/
    }

}

查看 AbstractTransformation 以了解默认情况下如何处理图像保存。注意，您不应自行将图像写入文件（writeImage('...')），因为这已经为您处理好了。

自定义回调

您可以在应用转换之前定义任意数量的回调函数。要从 Eloquent 模型中设置您的回调，请在调用 version() 方法之前调用 beforeTransformation()

$thumb = $photo->beforeTransformation(function(\Intervention\Image\Image $image){
    $image->crop(200, 200, 0, 0);
})->version(vGrayscale::class);

如果想要执行一些预处理，这很有用。您可以链式调用任意数量的 beforeTransformation()

另外，您还可以将您自己的参数传递给回调

$thumb = $photo->beforeTransformation(function(\Intervention\Image\Image $image, $width, $height){
    $image->crop($width, $height, 0, 0);
}, 200, 200)->version(vGrayscale::class);  // Now the crop size is not hardcoded!

装饰器模式：您仍然拥有您的模型！

此外，version() 函数的返回值（Version 实例）是包装您的原始 Photo 模型的 装饰器。这意味着您可以对原始模型执行任何操作。

// Decorator pattern applied.
// You can call any method of your Photo Eloquent model. Example:

$thumb->user_id;					// Get, Set an Eloquent attribute
$thumb->update(['key' => 'value']);	// Call any Eloquent's methods
$thumb->myMehod();					// Call methods that you have defined in the Photo class
$thumb->object;                     // Instance of the original Photo object 

有关使用的装饰器的更多信息，请参阅 igaster/eloquent-decorator