Refactor transformers and add a Transformable trait

README.md

@@ -1,8 +1,11 @@
-# Laravel Transformers
+# Zaltana Transformers
 
-[![Build Status](https://travis-ci.org/Apiness/laravel-transformers.svg?branch=master)](https://travis-ci.org/Apiness/laravel-transformers)
+[![Build Status](https://travis-ci.org/marfurt/zaltana-transformers.svg?branch=master)](https://travis-ci.org/marfurt/zaltana-transformers)
+
+> **Note:** This package is part of the _Zaltana components_, a serie of small packages made to provide useful features to Laravel projects.
+
+This package provides a presentation layer for transforming data output when building an API.
 
-This package is a presentation layer for transforming data output when building an API.
 
 ## Requirements
 
@@ -12,33 +15,33 @@ This package is a presentation layer for transforming data output when building
 
 ## Installation
 
-Pull this package in through Composer, by updating the `composer.json` as follows:
+Pull this package in through [Composer](https://getcomposer.org), by updating the `composer.json` file as follows:
 
-```
+```json
 {
 	"repositories": [
 		{
 			"type": "vcs",
-			"url": "https://github.com/Apiness/laravel-transformers"
+			"url": "https://github.com/marfurt/zaltana-transformers"
 		}
 	],
 	"require": {
-        "apiness/laravel-transformers": "~1.0"
+        "zaltana/transformers": "~1.0"
     }
 }
 ```
 
+
 ## Usage
 
-Override the abstract `Transformer` class to create a custom transformer on your entity:
+Override the abstract `Transformer` class to create a custom transformer for your entity:
 
 ```php
-use Apiness\Transformers\Transformer;
-use Illuminate\Database\Eloquent\Model;
+use Zaltana\Transformers\Transformer;
 
-class ModelTransformer extends Transformer {
+class MyModelTransformer extends Transformer {
 
-	protected function transformModel(Model $model)
+	protected function transform($model)
 	{
 		return [
 			'title'     => $model->title,
@@ -48,22 +51,69 @@ class ModelTransformer extends Transformer {
 }
 ```
 
-For transforming the model, you need to call the `process` method:
+For transforming a model object, you need to instantiate your transformer and to call the `process` method on it.
+If you want to transform your model relationships as well, you need to inject their corresponding transformers into your model transformer.
 
 ```php
-$transformer = new ModelTransformer(
-	[
-		'nested_model' => new NestedModelTransformer()
-	]
-);
+$transformer = new MyModelTransformer([
+	'myRelationship' => new RelationshipTransformer()
+]);
 
-$result = $transformer->process($this->mockedModel);
+$data = $transformer->process($myModelObject);
 ```
 
-##License
+You can also transform a collection of objects instead of a single object.
 
-This library is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT).
+```php
+// Transforming array of objects
+$objectsInArray = [ $myModelObject ];
+$data = $transformer->process($objectsInArray);
+
+// Transforming a Laravel Collection of objects
+$objectsInCollection = collect([ $myModelObject ]);
+$data = $transformer->process($objectsInCollection);
+```
+
+### Making Models Transformable
+
+You can also use the `Transformable` trait on your model.
+
+```php
+use Zaltana\Transformers\Transformable;
+
+class MyModel extends Model {
+
+	use Transformable;
+
+}
+```
+
+Then you can transform you objects as follows:
 
+```php
+$transformer = new MyModelTransformer();
+
+$data = $myModelObject->transform($transformer);
+```
 
+If you only use one transformer on your model, you can define a transformer via the `$transformer` property.
+
+```php
+$myModelObject->transformer = new MyModelTransformer();
+
+$data = $myModelObject->transform();
+```
 
+If you don't define any transformer on your model and call `transform()`, it will dynamically look for a default transformer named `ModelClassNameTransformer` in the same namespace.
+If no transformer is found, a TransformerException exception is thrown.
 
+```php
+$object = new MyModel();
+
+$data = $object->transform(); // Will try to use MyModelTransformer
+```
+
+
+##License
+
+This library is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT).

composer.json

@@ -1,12 +1,16 @@
 {
-    "name": "apiness/laravel-transformers",
+    "name": "zaltana/transformers",
     "description": "A presentation layer for transforming data output when building an API.",
     "type": "Library",
     "license": "MIT",
     "authors": [
         {
-            "name": "Apiness",
-            "email": "info@apiness.ch"
+            "name": "Nicolas Marfurt",
+            "email": "nmarfurt@gmail.com"
+        },
+        {
+            "name": "Nicolas Brosy",
+            "email": "nicolas.brosy@gmail.com"
         }
     ],
     "require": {
@@ -20,12 +24,12 @@
     },
     "autoload": {
         "psr-4": {
-            "Apiness\\Transformers\\": "src/"
+            "Zaltana\\Transformers\\": "src/"
         }
     },
     "autoload-dev": {
         "psr-4" : {
-            "Apiness\\Transformers\\Tests\\" : "tests/"
+            "Tests\\" : "tests/"
         }
     }
 }