thephpleague / fractal

Output complex, flexible, AJAX/RESTful data structures.

Fractal

Fractal provides a presentation and transformation layer for complex data output, the like found in RESTful APIs, and works really well with JSON. Think of this as a view layer for your JSON/YAML/etc.

When building an API it is common for people to just grab stuff from the database and pass it to json_encode(). This might be passable for "trivial" APIs but if they are in use by the public, or used by mobile applications then this will quickly lead to inconsistent output.

Goals

• Create a protective shield between source data and output, so schema changes do not affect users
• Systematic type-casting of data, to avoid foreach()ing through and (bool)ing everything
• Include (a.k.a embedding, nesting or side-loading) relationships for complex data structures
• Work with standards like HAL and JSON-API but also allow custom serialization
• Support the pagination of data results, for small and large data sets alike
• Generally ease the subtle complexities of outputting data in a non-trivial API

This package is compliant with PSR-1, PSR-2 and PSR-4. If you notice compliance oversights, please send a patch via pull request.

Install

Via Composer

$ composer require league/fractal

Requirements

The following versions of PHP are supported by this version:

>= PHP 7.4

Documentation

Fractal has full documentation, powered by Jekyll.

Contribute to this documentation in the gh-pages branch.

Todo

• add HAL serializers

Testing

$ phpunit

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Maintainers

• Korvin Szanto
• Matt Trask

Credits

• Graham Daniels
• Andrew Willis
• Phil Sturgeon
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

fractal's Issues

Single items returned inside arrays

I know the tests are made up to expect this specific format but I cannot understand the reasoning behind it, nor can I find it back on the jsonapi.org website why it's made like this.

For example, in this test, you expect the following response:

{
    "book": [
        {
            "title": "Foo",
            "year": 1991
        }
    ],
    "linked": {
        "author": [
            {
                "name": "Dave"
            }
        ]
    }
}

Why is it like this? I would expect it to return the following when using Item:

{
    "book": {
        "title": "Foo",
        "year": 1991
    },
    "linked": {
        "author": {
            "name": "Dave"
        }
    }
}

all transformer reutns as json sits inside data

the json created looks like this:

 {"data":[{"id":8,"content":"text1"},{"id":1,"content":"text2"}]}

if I would like to have this:

 {"code": 404, "data":[{"id":8,"content":"text1"},{"id":1,"content":"text2"}]}

how can I do that??

Transform back

I was wondering, isn't this a very one-way transformation?
Let's say my repo is using snake_case and with fractal I'm outputting as camelCase.

Now the client wants to create a new instance and for all he knows, we're using camelCase throughout our api. So he'll post with camelCase definitions.

Does fractal then provide a way to transform back to snake_case?

Remove fixed dependency on scope

Currently there is a no way to override new Scope on line#76 without extending the class which I'd prefer not to do.

I need to set my own scope dependency so that I can alter toJson() and it's output.

How I can build a transformer for recursive structure like trees?

Hi Phil!

I'm trying to generate a transformer for a nested set builded with baum (https://github.com/etrepat/baum) but I'm not able to do it.

My transformer looks like this:

class ContentTransformer extends Fractal\TransformerAbstract
{
    public function transform($node)
    {
        if(isset($node['children'])){
            return [
                'id' => (int) $node->id,
                'name' => $node->name,
                'children' => $this->collection($node->children, new ContentTransformer())
            ];
        }else{
            return [
                'id' => (int) $node->id,
                'name' => $node->name
            ];
        }
    }

} 

But I only get the elements of the first level:

{
   data:[
      {
         id:2,
         name:"Chapter 1",
         children:{

         }
      },
      {
         id:7,
         name:"Chapter 2",
         children:{

         }
      }
   ]
}

I'm using this transformer with the results of toHierarchy() method of baum. Which generates a tree in which children are the property of an item to store sub-nodes.

So what is the correct way to do this?

Thanks

Data filtering in application layer

This may NOT be part of the idea of Fractal, but at least worth a discussion.

Filtering data in application layer is almost always a bad idea, it should be done at the data source layer, but there are always exceptions.

So a transformer probably should be able to filter out data from the result. I mean a whole entity (row, document, etc) could be just left out.

[Proposal] TransformableInterface

Would be handy to have a TransformableInterface which would have the following method signature.

interface TransformableInterface {

    public function transformer();

}

The transformer method would return the Transformer for the given object. This would be handy for Eloquent models that could implement this interface and return a Transformer.

class User extends Eloquent implements TransformableInterface {

    public function transformer()
    {
        return new UserTransformer;
    }

}

My requirement for this is the API package I've been working on. I'm integrating Fractal and it'd be great if I could check if a model implements this interface and retrieve the models transformer.

When I include hasOne relationships I get a response array instead of object

Hi!

I don't know if I realize a bad implementation but I have the following problem:

I have a model Place with a HasOne relationship (menu). I call something like this
/api/places/1?include=menu

and in my model Place I have a relation:

    public function menu()
    {
        return $this->hasOne('PlaceMenu', 'place_id');
    }

When the place have menu I get this:

{
    data: {
        id: 3,
        name: "Name 1",
        created_at: "2014-08-06 18:44:35",
        updated_at: "2014-08-06 18:44:35",
        menu: {
            data: {
                id: 1,
                name: "Menu 1"
            }
        }
    }
}

But when the Place hasn't menu:

{
    data: {
        id: 3,
        name: "Name 1",
        created_at: "2014-08-06 18:44:35",
        updated_at: "2014-08-06 18:44:35",
        menu: {
            data: [ ]
        }
    }
}

My iOS developer ask me why I return an array when this is empty and an a object when has data.
Can you say me why, or if it's a bad implementation.

The response should be as this?

{
    data: {
        id: 3,
        name: "Name 1",
        created_at: "2014-08-06 18:44:35",
        updated_at: "2014-08-06 18:44:35",
        menu: {
            data: {}
        }
    }
}

Thanks Phil!

Symfony \ Component \ Debug \ Exception \ FatalErrorException Can't inherit abstract function League\Fractal\Pagination\PaginatorInterface::count() (previously declared abstract in Countable)

When using the Paginator on a Fractal collection, I get the following eror:

Symfony \ Component \ Debug \ Exception \ FatalErrorException
Can't inherit abstract function League\Fractal\Pagination\PaginatorInterface::count() (previously declared abstract in Countable)

On my server I run PHP 5.3.3. On my local machine I run PHP 5.4.21, no problem there. Commenting out line 24 in League/Fractal/Pagination/PaginatorInterface.php;

public function count();

prevents the error.

Available embeds (now includes) removed from new Serializer

@philsturgeon Is there a particular reason why the list of available includes not found in serializer? I mean, they are not returned by the method Scope :: toArray()

RIP PaginationCollection?

I don't think PaginatedCollection really makes any sense. I was using it to pass a paginator object through the from the controller method and into a generic ApiController::respondSuccess(ResourceInterface $resource) method, which would then detect the exact type and do specific stuff.

I figure I can just add Collection::setPaginator(Paginator $paginator), and if it is there is just get processed and jammed into the response next to "data" as part of the toArray() method.

Then in the future I can make that accept different types of Paginator, if I care (or somebody else PRs it).

@bencorlett @alexbilbie sound reasonable?

Add PHP version requirement to composer.json

What is the minimum PHP version required for this component?

Adding meta data to output?

More a question than an issue I think (hope xD).
But how can I add meta data to the output?

fx. adding a token property like this:

{
    "token": "b94hIJINQlPYIz7sOLRXbuMmsOH9KF60",
    "data": {
        "id": 26,
        "email": "[email protected]",
        "name": "Test User",
        "api_token": null,
        "created_at": "2014-01-24 03:34:58",
        "updated_at": "2014-01-24 03:34:58"
    },
    "embeds": [
        "games"
    ]
}

Just adding something "besides" data and embeds?

Pagination using ArraySerializer

When using the ArraySerializer paginated collections will output the data as per below:

Of course this is due to the fact that with the ArraySerializer it does not add 'data' field and therefore outputs a javascript object with the keys. We could solve this by moving to the DataArraySerializer however we don't like using this as it adds 'data' attributes to everything, including children which is a bit too verbose for us.

One way around it we have found is to keep using the ArraySerializer but just change the code in ArraySerializer to utilize the resourceKey if supplied:

/**
 * Serialize the top level data.
 * 
 * @param  string  $resourceKey
 * @param  array  $data
 * @return array
 */
public function serializeData($resourceKey, array $data)
{
    return $resourceKey === null ? $data : array($resourceKey => $data);
}

We create our own FractalTransformer to utilise this as below:

use Illuminate\Pagination\Paginator as IlluminatePaginator;
use League\Fractal\Resource\Collection as FractalCollection;
use Dingo\Api\Transformer\FractalTransformer as DingoFractalTransformer;

class FractalTransformer extends DingoFractalTransformer
{
    /**
    * Create a Fractal resource instance.
    *
    * @param  mixed  $response
    * @param  \League\Fractal\TransformerAbstract
    * @return \League\Fractal\Resource\Item|\League|Fractal\Resource\Collection
    */
    protected function createResource($response, $transformer)
    {
        if ($response instanceof IlluminatePaginator)
        {

            return new FractalCollection($response, $transformer, 'data');
        }

        return parent::createResource($response, $transformer);
    }
}

Then finally to kick off all things in our config:

'transformer' => function($app)
{
    $fractal = new League\Fractal\Manager;

    $fractal->setSerializer(new League\Fractal\Serializer\ArraySerializer);
    return new OurProject\Extensions\FractalTransformer($fractal);
}

Then we correctly get the right output for paginated resources and collections.

Do you have any suggestions on if this is a good way to go about this and would you consider a pull request to use the resourceKey in the ArraySerializer as per above?

Unit tests

Would it be possible to have a mini guide in the readme for getting the unit tests running? For the life of me I can't get them working for some reason (hot weather!) :-]

Question: Smart Embedding

I have been looking over your todo list, and was wondering what ideas you had on implementing that feature. In your todo list example you have: ?embed=foo:limit(5):order(something,asc)

I have messed around with parsing that string into the requestedScopes, into a format something like the following:

// This is obviously just a prototype
array(
   'foo' => array(
     'limit' => 5,
     'order' => 'asc'
   ),
   'bar' => array(
     'limit' => 10
   )
)

I guess I am just having a hard time figuring out how you would get something like, bar's limit into the paginator (if it exists) for that resource, or when/how you'd get the order direction and apply it to foo.

Hopefully this question makes sense, and hopefully I can actually contribute something to the repo instead of just using it (thanks by the way!)

Use dependency injection instead of facades in controllers

Correct me if I am wrong but facades are hard to UnitTest, as well as mixing model logic in the controllers.

Shouldn't it use dependency injection instead of

$foo = Foo::take(10)->get();

Although I am confident that you will have a reason for not doing this?

[Hateoas] Do you know the Hateoas lib?

Hi!

I quickly read your blog post, and saw that you were about to implement Hateoas features into this lib.

Did you consider the Hateoas library? Or are you aware of it, at least?

Cheers,
William

Infinite embed protection

In one of my projects I have 2 models that are related. Because of where they are used in the API there is a need for them to be able to embed each other.

The issue is that a client could request ?embed=a.b.a.b.a.b.a.b (continuing), causing the server to do tons of processing. This could lead to some type of denial of service attack.

Support for returning a subset of fields on a resource

Perhaps this feature already exists but I am thinking it would be nice to have a recommended way of returning a subset of data for a resource via a transformer.

This can obviously be achieved by providing a separate transformer or implementing this logic in your own transformer but I am wondering if it would be a beneficial feature to add to the abstract transformer.

Basic idea would be something like this:

https://gist.github.com/benglass/e7b2af60451d2a46182b

It would also be nice to be able to cascade the group name to embedded transformers

Use cases for this would be

• Public vs Private APIs
• Versioning for APIs

Obviously this could be achieved by just defining separate transformers but then you would have to duplicate some of the field extraction logic. You could mitigate this by creating a field extractor that is used by the transformers but since that is the main thing the transformers do it seems like that would be overengineering.

Embedding an embed

Hey,

I was wondering if it possible to embed the embeds of something you are already embedding? Sorry to make it sound so confusing. What I mean is, lets say I embed a user to a venue, I then want to get that users image which is an embed on the user.

Is there a way to do this?

Thanks for the great package.

Register transformers once?

Is it possible to register my transformers once for a given model?

To work off of your examples in Build APIs you won't hate we are returning from each controller method as so:

return $this->responseWithItem($place, new PlaceTransformer);

It would be cool if Fractal would already know "hey this is instanceof Place, we have something registered for that", negating the need for me to write new {model}Transformer.

Avoid `data` in included elements?

Is there a way to not have the data key as part of the included elements, while still keeping it for the top level response data?

Class League\Fractal\Manager does not exist

Hello, I get this error when try to upload to my vps and run composer, but in local is working. any idea why? thanks

JsonApiSerializer resourceKey and cursor

I'm getting "The $resourceKey parameter must be provided when using League\Fractal\Serializer\JsonApiSerializer" when combining this with a cursor:

$cursor = new Cursor($currentCursorStr, $newCursorStr, $users->count());

return Response::api()->withCollection($users, new UserTransformer, $cursor);

I see resourceKey in the serializer docs.. is this currently incompatible with dingo/api?

Namespaces in Simple example

I am an idiot and spent 30 minutes looking into composer & PSR-4 autoloaders because of the use League\Fractal; namespace import line at the top.

Most people aren't idiots, but just in case...

I copy & pasted bits of the example, which includes $fractal = new Fractal\Manager();. PhpStorm couldn't find the class, as I hadn't imported it. If this was either new \League\Fractal\Manager or even new Manage then PhpStorm would have offered to automatically fix it.

I hadn't come across importing whole namespaces before (it's doesn't seem to be covered in http://us1.php.net//manual/en/language.namespaces.importing.php either) and always explicitly import individual classes. Being explicit is nice as it shows all your dependencies, but I can see the value in just importing a namespace. Is this covered by any PSRs yet?

Can I make a pull request to either import the individual classes explicitly, or don't use anything and instantiate with new \League\Fractal\Manager?

Transforming incoming data?

Forgive me if I'm missing something, but it's not immediately apparent to me nor does it seem to be mentioned in the docs:

What about recieving data? If I have an object in the database, and for simplicity's sake let's us the example that in the database a column is called "start_date", I transform this to simply be "start" when it's sent to the client. Now, when I recieve data back, it will obviously just be a "start" property, which isn't actually in the database.

Do transformers support inverting their own operations?

JsonApiSerializer::item is returning a collection

I'm not sure whether this is correct, or I'm doing something wrong. But the following is returning a collection of data:

$serializer->item('error', [
    'message' => '403 Forbidden'
]);

[
    'error' => [
        0 => ['message' => '403 Forbidden']
    ]
]

Where as with an item, I would have thought it should return:

[
    'error' => [
        'message' => '403 Forbidden'
    ]
]

Looking at the source I can't understand why $data is wrapped in array(...) for an item.

Notes:

• League\Fractal\Serializer\DataArraySerializer works fine
• Single items shouldn't do this: http://jsonapi.org/format/#document-structure-individual-resource-representations

Use Manager::parseIncludes with TrasformerAbstract

Maybe this feature already exists, but I can not figure out how to use it.
I would like to use available includes in the TransformerAbstract.

For example, i have CampaignController.php with:

/**
 * Display a listing of the resource.
 *
 * @return Response
 */
public function index()
{
  $campaigns = Campaign::all();
  return $this->respondWithCollection($campaigns, new CampaignTransformer);
}

/**
 * Display the specified resource.
 *
 * @param  int  $id
 * @return Response
 */
public function show($id)
{
    $campaign = Campaign::find($id);

    if(! $campaign)
    {
        return $this->errorNotFound('Resource Not Found');     
    }

    return $this->respondWithItem($campaign, new CampaignTransformer);     
}

and my CampaignTransformer is the follow:

protected $availableIncludes = [
    'client'
];


public function includeClient(Campaign $campaign)
{
    $client = $campaign->client;

    return $this->item($client, new ClientTransformer);
}

.......

So i don't understand, in this case, how to use Manager::parseIncludes.

P.S.: In previous version i used embeds and it works great.

Adding prev to cursors

Hi Phil!
Will it make sense in your opinion to add a "prev" parameter to the cursor so the output can be like this?

"cursor": {
    "current": "MTA=",
    "prev": "LTEw",
    "next": "MTA=",
    "count": 10
}

I made some slight changes to the CursorInterface, Cursor, Scope and Collection classes because I needed the functionality for a personal project.

If you want I can make a pull request to let you review it.

recursive includes issue

Here i have three transformers

PostTransformer => include comments

CommentTransformer => include user

user

simple perseInclude works fine. Example:
commentTransformer IncludeUser works.
PostTransformer IncludeComments works.

But 'comments.user' not working when try to perseIncludes. It throws error saying PostTransformer IncludeComments.user not defined.

What im doing wrong here?

Omitting availableIncludes breaks defaultIncludes

I updated, and was looking straight into lucifers eyes by doing so. Using include instead of embed now works. BUT, In some of my transformers I had specified the $defaultIncludes array and omitted the $availableIncludes array. It worked before updating, but now the defaultIncludes aren't included in the output. But i found that if i added the $availableIncludes = []; in the transformer it worked.

Am I missing something here?

use League\Fractal\TransformerAbstract;

class GoalTransformer extends TransformerAbstract {

    protected $defaultIncludes = ['user'];

    // why is this needed?
    protected $availableIncludes = [];

    /**
     * Transform a Goal entity into a generic array.
     *
     * @param  \Orly\Goal $goal
     * @return array
     */
    public function transform(Goal $goal)
    {
        return [
            'id'       => (int) $goal->id,
            'match_id' => (int) $goal->match_id,
            'minute'   => (int) $goal->minute
        ];
    }

    /**
     * Include User for Goalscorer
     *
     * @param  \Orly\Goal $goal
     * @return array
     */
    public function includeUser(Goal $goal)
    {
        $user = $goal->user;

        return $this->item($user, new UserTransformer);
    }

}

PaginatedCollection Usage example

Could you provide an example of the usage of PaginatedCollection?

I got

// $collection is an eloquent collection
$paginator = Paginator::make($collection, $collection->count(), $itemsPerPage);
$resource = new PaginatedCollection($paginator, $transformer);

return App::make('fractal')->createData($resource);

and it throws

Argument 1 passed to Illuminate\Pagination\Environment::make() must be of the type array, object given

if I change to

$items = $collection->toArray();
$paginator = Paginator::make($items, $collection->count(), $itemsPerPage);
$resource = new PaginatedCollection($paginator, $transformer);

return App::make('fractal')->createData($resource);

it throws

Argument 1 passed to Proo\Users\EloquentUserTransformer::transform() must implement interface Proo\Users\UserInterface, array given

Its an Illuminate Paginator so it should work (?!)

Different output structures

What are you thoughts on making the output structure configurable somehow?

My use case is, we're building a new App that is uses Ember Data which expects a specific output format (without hacking about with it). Basically the embeds are at the top level, explained here.

It would be nice to be able to use this library with different output structures. I actually started writing something similar for our App but this library is much better, great work!

__toString

Is it a stupid idea to implement __toString so

$string1 = (string) \App::make('fractal')->createData($resource);
$string2 = \App::make('fractal')->createData($resource)->toJson();

$string1 === $sting2 // true

ArraySerializer and resourceKey

If no resourceKey is supplied when using the ArraySerializer this will output an empty key as like in the json below:

I believe this line needs to become:

/**
 * Serialize a collection
 * 
 * @param  string  $resourceKey
 * @param  array  $data
 * @return array
 **/
public function collection($resourceKey, array $data)
{
    return $resourceKey === null ? $data : array($resourceKey => $data);
}

How to return data with the paginator

I am struggling to work out how you would return data when using the paginator.

For example I am doing this

$data = $this->some_repo->callPaginator();
$foo = $data->getCollection();

$resource = new Collection($foo, new FooTransformer);
$resource->setPaginator(new IlluminatePaginatorAdapter($data));

If I was to try and $resource->setPaginator(new IlluminatePaginatorAdapter($data)); I get the following error:

The Response content must be a string or object implementing __toString(), "object" given.

So what is the correct way to return data from a paginator?

Thanks

Allow flexible binding of scope output to configurable elements

I'm really loving this library, but I am having to currently rewrite the scope output to the structure my API needs. For instance, you output the Item properties into a data element, but my API expects the properties in the root JSON object (following HAL standards) of each Item (including in Collections). Likewise, embedded data needs to go into an _embedded element in the HAL spec, vs. embed.

I'm wondering if it might be possible to allow each scope to output the data, embed and pagination elements in a more flexible way. I think just allowing a way to extend the Scope::toArray() method would be sufficient, though I have not yet considered if that is the best approach.

I assume if you are planning to support the HAL draft standard, or any of the various other HATEOAS media source specifications, the same issue will be encountered. Thoughts?

Linked data does not merge correctly

The includes with empty collections do not merge correctly in my opinion.

output:

 {"parent":[{"id":1},{"id":3},{"id":2}],"linked":{"childs":[{"id":10},{"id":20},{"id":30},[]]}}

expected

{"parent":[{"id":1},{"id":3},{"id":2}],"linked":{"childs":[{"id":10},{"id":20},{"id":30}]}}

Example code:

https://gist.github.com/jildertmiedema/7a65b9f26f1c29fc2b0f

Update documentation for 0.8.0

I was using happily the 0.7.0 and now that setRequestedScope is not available anymore and that new features (metas, etc) have been added, could you please update the documentation in order to make those more easily accessible?

Is the data should always return in 'data' index?

Hi Phil,

What I have right now is the result always in the 'data' index, like:

{
    "data": {
        "id": 96,
        "name": "test1",
        "abbreviation": "zxcv"
    }
}

What if I want a custom index other than 'data' as the result value?
Or, what if I don't want the 'data' index?

Changing the https://github.com/thephpleague/fractal/blob/master/src/Scope.php#L112 to :

$output = $this->runAppropriateTransformer();

should do it, right? or any idea?

Thanks

Unique JsonApiSerializer return objects

From JSON API:

Along these lines, if a primary document is linked to another primary or linked document, it should not be duplicated within the "linked" object.

However my "linked" array has duplicate objects because it is referenced by multiple primary objects.

Is there currently a way around this, or should I pursue?

Coveralls Token in phpunit.xml.dst

Hey Phil,

You have your projects coveralls.io token in the phpunit.xml.dist, do you think that should be removed? And kept in a phpunit.xml that is ignored by a gitignore?

Realized when I forked it was sending coveralls jobs to your token and possibly bringing down the projects code coverage percentage.

Provide TransformerInterface, implement in TransformerAbstract

Right now the code requires that a transformer extends TransformerAbstract. You could provider a TransformerInterface which would be implemented in TransformerAbstract as an alternative.

That way if you had a BaseTransformer in your application which had some kind of shared logic you could extend that (you wouldnt have to extend TransformerAbstract). It would also enable users to implement that interface on any class and use it as a transformer.

Pagination links keep embeds

Hey Phil,

Have been using Fractal for our API, it's simply awesome !

Before I start spending time in coding, wanted to get your opinion on this.

Right now if we put ?embed=contacts in the URL, the links returned on the JSON response still only produce ?page=2, the embed parameter is missing.

Is it a good idea to keep the embed parameter on the querry string when the pagination links are produced ? Is there any reason you kept that out ?

Cheers

Is there any way to remove the "data" key for collections or item

For example after calling the method "createData" as below

createData($fractalCollection)->toArray();

The returned data has the key "data" and I just want it to return my object or Array plainly.

Thanks in advance and please do let me know if the question is not clear.

Improved Laravel Integration

Would it be possible to automatically resolve transformers from the laravel ioc container?

PHPUNIT fail with Laravel 4.2 because of Illuminate\Pagination\Environment

This unit test fail : https://github.com/thephpleague/fractal/blob/master/test/Pagination/IlluminatePaginationAdapterTest.php in laravel 4.2 because Illuminate\Pagination\Environmentis now renamed Illuminate\Pagination\Factory

I'm not sure how Fractal want to be compatible with both Laravel 4.1 and 4.2 so, if someone can help.

Keys for includes during transformations / getting the parent element

Is it possible to get the current key for an element during its transformation?

If I, for example, want to do some more complex operations or calculations based on the number of total elements in a collection.

Another useful feature would be if the currently transformed element had access to a possible parent element.

I looked through the code but couldn't find anything to help be achieve that. Is there a plan for something like it?

Adding meta data

Looks like there's been some great progress in the develop branch! I'm trying to set some meta data but can't seem to get it working. I'm trying to get my final output to look like this

{
    "meta" : [
        ...
    ],
    "body" : [
        "foo" : "bar",
        "comments" : [
            "meta" : [
                ...
            ],
            "data" : [
                "message" : "durp"
            ]
        ]
    ]
}

This is how I'm using the serializer

$fractal = new Fractal\Manager();
$fractal->setSerializer(new JsonApiSerializer);

$products = Product::all();
$resource = new \League\Fractal\Resource\Collection($products, new ProductTransformer, 'body');
$resource->setMeta(array('token' => 'durp'));
$json = $fractal->createData($resource)->toJson();

So far, all I can get to output is

{
    "body" : [
        "foo" : "bar",
        "comments" : [
            "meta" : [
                ...
            ],
            "data" : [
                "message" : "durp"
            ]
        ]
    ]
}

Any ideas? Great library BTW!