Author: caefer Date: 2010-04-26 15:54:17 +0200 (Mon, 26 Apr 2010) New Revision: 29259
Added: plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/project/web/uploads/testrecord/caefer.jpg Removed: plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/project/web/uploads/testrecord/daphne.jpg Modified: plugins/sfImageTransformExtraPlugin/trunk/README plugins/sfImageTransformExtraPlugin/trunk/TODO plugins/sfImageTransformExtraPlugin/trunk/package.xml.tmpl plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/model/TestObject.php plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/model/doctrine/TestRecord.php plugins/sfImageTransformExtraPlugin/trunk/test/unit/lib/source/sfImageSourceFileTest.php Log: everything ready for th final release Modified: plugins/sfImageTransformExtraPlugin/trunk/README =================================================================== --- plugins/sfImageTransformExtraPlugin/trunk/README 2010-04-26 13:00:09 UTC (rev 29258) +++ plugins/sfImageTransformExtraPlugin/trunk/README 2010-04-26 13:54:17 UTC (rev 29259) @@ -1,4 +1,4 @@ -^# Image manipulation made even easier - sfImageTransformExtraPlugin +Image manipulation made even easier - sfImageTransformExtraPlugin  @@ -8,13 +8,14 @@ For example let's say a user avatar is always ``80x80 PNG`` while a homepage top image is always ``320x140 JPG`` with round corners. -As it is far too costly to prepare all these different formats by hand there are automated ways to generate them from source images uploaded by a user. One of the best tools for this in the symfony world is the [sfImageTransformPlugin](http://www.symfony-project.org/plugins/sfImageTransformPlugin) which enables you to perform many sophisticated transformations on your images such as resizing, color manipulation, overlays and much much more. +As it is far too costly to prepare all these different formats by hand there are automated ways to generate them from source images uploaded by a user. One of the best tools for this in the symfony world is [sfImageTransformPlugin](http://www.symfony-project.org/plugins/sfImageTransformPlugin) which enables you to perform many sophisticated transformations on your images such as resizing, color manipulation, overlays and much much more. It is not only easy to use but easy to extend as well. Writing your own transformation is a bliss. -Using such an automatism means you have to write code and perform all necessary transformation - usually on upload, no matter if the generated files are ever requested. It also means that design changes that also change the formats lead to change of business logic rather than just templates. +Using such an automatism means you have to write code and perform all necessary transformation - usually on upload, no matter if the generated files are ever requested. It also means that design changes that change the formats as well lead to a change of business logic rather than just templates. -This is where sfImageTransformExtraPlugin springs to action as it provides a way to configure formats with multiple transformations. -In your templates you only refer to the format by name which results in an SEO friendly image URL. The image itself will be generated on first request and (in production environments) written to the filesystem. +This is where sfImageTransformExtraPlugin springs into action as it provides a way to configure formats with multiple transformations. +In your templates you only refer to the format by name which results in an SEO friendly image URL (a URL that you have full control over). The image itself will be generated on first request and (in production environments) written to the filesystem. + Here are some of the key features: * Configure image transformation for your thumbnail formats @@ -198,7 +199,7 @@  -Apache automatically informs the browser that the image has not been modified by sending a ``304`` status. +Apache automatically informs the browser that the image has not been modified by sending a ``304`` status (depending on your Apache configuration, however the described behaviour is the default). As you can see the time needed to deliver a generated image after the second request is drastically reduced. (The times will vary on different installations.) @@ -240,7 +241,7 @@ ... Automatic mime detection is absolutely necessary! -Of course you can point the ``font_fir`` to your own location containing True Type Fonts. +Of course you can point the ``font_dir`` to your own location containing True Type Fonts. Clear the cache to enable the autoloading to find the new classes: @@ -248,6 +249,13 @@ > Note: The plugin requires sfImageTransformPlugin to be installed as well. > The dependencies described there apply as well so please follow the > [README](http://www.symfony-project.org/plugins/sfImageTransformPlugin?tab=plugin_readme > "sfImageTransformPlugin README"). +The default routes of the plugin expect all thumbails to be called from the relative URL ``/thumbnails/..``. So you have to make sure, that this folder (``SF_ROOT_DIR/web/thumbnails``) exists and is writable to the web server. + + $ mkdir SF_ROOT_DIR/web/thumbnails + $ chmod 777 SF_ROOT_DIR/web/thumbnails + +The ``/thumbnails`` path is specified in your routes. If you make changes to the routes you have to make sure that the equivalent path exists and is writable. + Next you have to configure your routes. ## Configuration for local image sources identified by filename @@ -257,7 +265,7 @@ Create a route like the following in your applications ``routing.yml``. // /apps/yourapplication/config/routing.yml - sf_image: + sf_image: class: sfImageTransformRoute url: /thumbnails/:format/:filepath.:sf_format param: { module: sfImageTransformator, action: index } @@ -308,11 +316,20 @@ <?php echo image_tag(url_for('sf_image_doctrine', array('format' => 'pixelate', 'sf_subject' => $record))); - // resulting in: http://localhost/thumbnails/News/pixelate/01/00/00/mytest-1.jpg - ?> + // resulting in: http://localhost/thumbnails/News/pixelate/01/00/00/mytest-1.jpg + ?> ``$record`` in this example is either a Doctrine or Propel record. +The ``:path`` attribute is provided by the sfImageTransformExtraPlugins own route class ``sfImageTransformRoute``. It will take the ``id`` attribute and form a three level deep path from it. + + // examples + 1 => 01/00/00 + 37410 = 10/74/03 + .. + +This path can ensure that you won't store more than 100 files per directory which is necessary to avoid imperformance from the filesystem. + ## Configuration for remote image sources to be read over HTTP If you plan to build a content delivery network (CDN) and run sfImageTransformExtraPlugin as a webservice your image sources will not be available locally but instead over HTTP. @@ -346,36 +363,112 @@ ### Invalidating generated images -trigger event -run task +Sometimes you want to remove already generated images from your filesystem i.e. if the original source image was changed. -see also twiggering invalidation when using sfImageTransformExtraPlugin as a web service further down in this document. +For this there is a symfony task which takes two mandatory arguments. + $ ./symfony help transforms:remove + Usage: + symfony transforms:remove application route + + Aliases: remove-thumbnails + + Arguments: + application The application name + route The sf_image route that generated the image(s) you want to remove + + Description: + Removes thumbnails generated by sfImageTransformExtraPlugin. + +Let's take a route from the previous examples. + + // /apps/yourapplication/config/routing.yml + sf_image: + class: sfImageTransformRoute + url: /thumbnails/:format/:filepath.:sf_format + param: { module: sfImageTransformator, action: index } + requirements: + format: '[\w_-]+' + filepath: '[\w/]+' + sf_format: 'gif|png|jpg' + sf_method: [ get ] + options: + image_source: File + +Assuming that this route is active for your frontend application you can now do the following to remove all images generated by that route. + + $ ./symfony transforms:remove frontend sf_image_file + Do you really want to delete all generated images? + y + >> files- Generated images removed. + +To be more specific you can provide all attributes available for the route. + +To remove only images for this route that used the ``default`` format: + + $ ./symfony transforms:remove frontend sf_image_file --format=default + >> files- Generated images removed. + +To remove only images for this route that are of type ``jpg``: + + $ ./symfony transforms:remove frontend sf_image_file --sf_format=jpg + >> files- Generated images removed. + +Of course you can combine all available attributes. In this case to remove all ``jpg`` images that were generated using the ``default`` format (for example if you changed the mimetype of that particular format). + + $ ./symfony transforms:remove frontend sf_image_file --format=default --sf_format=jpg + >> files- Generated images removed. + + ## Advanced usage: ### How can I use static resources like fonts, alpha masks and overlay images? -### How can I run sfImageTransformExtraPlugin as a web service? +To use your own Treu Type Fonts you have to configure sfImageTransformPlugin in your ``app.yml``. -To run sfImageTransformExtraPlugin as a web service you create a new symfony installation and install the plugin as described in the previous chapter. + // /apps/yourapplication/config/app.yml + all: + sfImageTransformPlugin: + mime_type: + auto_detect: true + library: gd_mime_type # gd_mime_type (GD), Fileinfo (PECL), MIME_Type (PEAR) + font_dir: /path/to/your/fonts-dir -You then have to create a configuration file called ``thumbnailing.yml`` in your applications config directory with the following contents: +If a transformation expects an sfImage object as a mask or overlay or other resource there is a mechanism in place forming that object for you. +All you have to do is to specify the relative path to your resource image. Let's look at a previous example: - all: - source_image: - class: sfImageSourceHTTP - param: - url_schema: http://yourhost/%type/%id/%attribute + star6: + ... + transformations: + ... + - { adapter: GD, transformation: overlay, param: { overlay: overlays/star_frame.png, position: center }} + - { adapter: GD, transformation: alphaMask, param: { mask: masks/star_mask.gif }} -As the invalidation of the generated images can not be triggered with an event you will have to create a new route that can be called as a trigger. +``sfImageTransformManager`` will automatically convert any filepath/filename with one of the following extensions (``jpg``, ``jpeg``, ``gif``, ``png``) to an instance of sfImage. +The relative filepath will be looked up at the following locations: ``/path/to/your/project/data/resources/`` or (for the default formats) ``/path/to/your/project/plugins/sfImageTransformExtraPlugin/data/example-resources``. -EXAMPLE +So for the above example the files will be looked up in the following order: +1. ``/path/to/your/project/data/resources/overlays/star_frame.png`` + ``/path/to/your/project/data/resources/masks/star_mask.gif`` +2. ``/path/to/your/project/plugins/sfImageTransformExtraPlugin/data/example-resources/overlays/star_frame.png`` + ``/path/to/your/project/plugins/sfImageTransformExtraPlugin/data/example-resources/masks/star_mask.gif`` + + +### How can I run sfImageTransformExtraPlugin as a web service? + +To run sfImageTransformExtraPlugin as a web service you create a new symfony installation and install the plugin as described in the previous chapter. + +Further you will have to use your own route for remote image sources via HTTP (see above). + +Remember to provide the format and all attributes required to locate the remote image source in the routes URL. + If you serve your generated images from a web service installation you have to prefix the URL with the domain of your service. - <?php echo image_tag('http://your.webservice.url'.url_for(...), array()); ?> + <?php echo image_tag('http://your.webservice.url'.url_for('sf_image_remote', ...), array()); ?> + ### How can I use a custom image source? It doesn't matter where your source images are stored and how you need to receive the filepath/URL you can easily implement a solution by following two easy steps: @@ -407,18 +500,15 @@ If the image source files are stored on the local filesystem accessible to the webserver your need to implement ``sfImageSourceLocal``. For all other locations please use ``sfImageSourceRemote`` as PHP functions like ``stat()`` only work with local files and therefor need to be faked . class sfImageSourceSpecial extends sfImageSourceRemote implements sfImageSourceInterface - { - ... - } + { + ... + } -### How can I configure a transformation that needs an instance of sfImage for a parameter? +That is all you have to do. -Some transformations like ``sfTransformOverlayGD`` require you to pass an instance of sfImage as one of the parameters. In case of ``sfTransformOverlayGD`` this would be the image to be used as an overlay/watermark. +Please make sure that the base URL (in the above example ``/thumbnails``) exists and is writable. -As you can not configure objects in a YAML file you can just specify the filepath to the appropriate image prefixed by ``sfImage:``. - ..EXAMPLE - ### How can I run the tests? $ cd /path/to/sfImageTransformExtraPlugin @@ -427,4 +517,5 @@ ### How can I generate the API documentation? $ cd /path/to/sfImageTransformExtraPlugin - $ phpdoc ... + $ phpdoc -o HTML:frames:DOM/phphtmllib -d . -t /path/to/where/you/want/the/apidocs/to/be/generated + Modified: plugins/sfImageTransformExtraPlugin/trunk/TODO =================================================================== --- plugins/sfImageTransformExtraPlugin/trunk/TODO 2010-04-26 13:00:09 UTC (rev 29258) +++ plugins/sfImageTransformExtraPlugin/trunk/TODO 2010-04-26 13:54:17 UTC (rev 29259) @@ -1,6 +1,3 @@ -todos for 0.9.10 - * refactor yml to read sfImage: sources properly - todos for 1.0.0 * update and complete README * review all static resources in plugin Modified: plugins/sfImageTransformExtraPlugin/trunk/package.xml.tmpl =================================================================== --- plugins/sfImageTransformExtraPlugin/trunk/package.xml.tmpl 2010-04-26 13:00:09 UTC (rev 29258) +++ plugins/sfImageTransformExtraPlugin/trunk/package.xml.tmpl 2010-04-26 13:54:17 UTC (rev 29259) @@ -51,6 +51,25 @@ <changelog> <release> <version> + <release>1.0.0</release> + <api>1.0.0</api> + </version> + <stability> + <release>stable</release> + <api>stable</api> + </stability> + <license uri="http://www.symfony-project.org/license";>MIT license</license> + <date>2010-04-26</date> + <license>MIT</license> + <notes> + * caefer: bugfix: removed forgotten var_dump()s.. + * caefer: optimised the extension matching and file info code + * caefer: reviewed, corrected and completed README + * caefer: reviewed and updated some of the default resources used within this plugin + </notes> + </release> + <release> + <version> <release>0.9.9</release> <api>0.9.9</api> </version> Modified: plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/model/TestObject.php =================================================================== --- plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/model/TestObject.php 2010-04-26 13:00:09 UTC (rev 29258) +++ plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/model/TestObject.php 2010-04-26 13:54:17 UTC (rev 29259) @@ -30,6 +30,6 @@ public function getFile() { - return 'daphne.jpg'; + return 'caefer.jpg'; } } Modified: plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/model/doctrine/TestRecord.php =================================================================== --- plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/model/doctrine/TestRecord.php 2010-04-26 13:00:09 UTC (rev 29258) +++ plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/model/doctrine/TestRecord.php 2010-04-26 13:54:17 UTC (rev 29259) @@ -30,6 +30,6 @@ public function getFile() { - return 'daphne.jpg'; + return 'caefer.jpg'; } } Copied: plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/project/web/uploads/testrecord/caefer.jpg (from rev 29256, plugins/sfImageTransformExtraPlugin/trunk/data/caefer.jpg) =================================================================== (Binary files differ) Deleted: plugins/sfImageTransformExtraPlugin/trunk/test/fixtures/project/web/uploads/testrecord/daphne.jpg =================================================================== (Binary files differ) Modified: plugins/sfImageTransformExtraPlugin/trunk/test/unit/lib/source/sfImageSourceFileTest.php =================================================================== --- plugins/sfImageTransformExtraPlugin/trunk/test/unit/lib/source/sfImageSourceFileTest.php 2010-04-26 13:00:09 UTC (rev 29258) +++ plugins/sfImageTransformExtraPlugin/trunk/test/unit/lib/source/sfImageSourceFileTest.php 2010-04-26 13:54:17 UTC (rev 29259) @@ -27,7 +27,7 @@ { private $testSourceUri = null; private $testParameters = array( - 'filepath' => 'testrecord/daphne.jpg' + 'filepath' => 'testrecord/caefer.jpg' ); public function testStream_close() @@ -96,12 +96,12 @@ */ public function testFailedBuildURIfromParameters() { - $this->assertEquals('sfImageSource://file/testrecord/daphne.jpg', sfImageSourceFile::buildURIfromParameters(array())); + $this->assertEquals('sfImageSource://file/testrecord/caefer.jpg', sfImageSourceFile::buildURIfromParameters(array())); } public function testBuildURIfromParameters() { - $this->assertEquals('sfImageSource://file/testrecord/daphne.jpg', sfImageSourceFile::buildURIfromParameters($this->testParameters)); + $this->assertEquals('sfImageSource://file/testrecord/caefer.jpg', sfImageSourceFile::buildURIfromParameters($this->testParameters)); } protected function setUp() -- You received this message because you are subscribed to the Google Groups "symfony SVN" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/symfony-svn?hl=en.
