Download the PHP package hackerboy/json-api without Composer

Current version: 2.x

Packagist: hackerboy/json-api

Making JSON API implementation (server side) easiest for you

Install

Run examples:

• Example code: /example/index.php
• Guide to set up /examples/index.php to see some examples of uses.

Then config your localhost nginx/apache to access [LOCALHOST_PATH]/examples/index.php

Table of Contents

• How to use? (Making response document)

  • Create your resource schema
  • Configuration and mapping your resources
  • Document methods
  • Implement relationships
  • Set data as relationships
  • toArray() and toJson() methods
  • Easily create elements for your document
    • Create errors
    • Create links
    • Create other elements
  • Document query
    • Examples of document query
• Client-Side usages
  • Flexible document and resources
    • Example of flexible document
    • Parse from string or array

How to use?

Create your resource schema

Mapping your id, type, attributes from your model objects by creating Schema classes. Inside the Schema class, you can retrieve your model object through $this->model. For example, I'm gonna talk in a Laravel project context. Firstly, let's create a resource file: /app/Http/JsonApiResources/UserResource.php

Configuration and mapping your resources

Now we can easily generate a JSON API document object like this:

Document methods

The difference between "set methods" and "add methods" are is: "Set methods" will override the data while "add methods" will append to data.

Available "set" methods from $document object are:

• setData($resourceOrCollection, $type = 'resource') // Default $type = 'resource', in case you need to return data as relationship object, change $type to 'relationship'. Or you can use the setDocumentType() method below
• setDocumentType($type) // $type = "resource" or "relationship".
• setIncluded($resourceOrCollection)
• setErrors($errors) // Array or HackerBoy\JsonApi\Elements\Error object - single error or multiple errors data will both work for this method
• setLinks($links) // Array of link data or HackerBoy\JsonApi\Elements\Links object
• setMeta($meta) // Array of meta data or HackerBoy\JsonApi\Elements\Meta object

Available "get" methods from $document object are:

• getQuery() // Get Query object for finding resources
• getConfig() // Get document config
• getData() // Get document data
• getIncluded() // Get document included data
• getErrors() // Get document errors data
• getMeta() // Get document meta data
• getLinks() // Get document links
• getUrl($path = '') // Get api url
• getResourceInstance($modelObject) // Get resource instance of a model object

Available "add" methods from $document object are:

• addIncluded($resourceOrCollection)
• addErrors($errors) // Array or HackerBoy\JsonApi\Elements\Error object - single error or multiple errors data will both work for this method
• addLinks($links) // Array of link data or HackerBoy\JsonApi\Elements\Links object
• addMeta($meta) // Array of meta data or HackerBoy\JsonApi\Elements\Meta object

Example:

Implement relationships

Simply return an array in getRelationships() method

Set data as relationships

Second param allows you to set data as relationship (for request like: /api/posts/1/relationships/comments)

toArray() and toJson() methods

New methods in v1.1. Available for document, elements and resources

Easily create elements for your document

Suppose that we created a $document object

Create errors

Create links

Create other elements

It'll work the same way, available methods are:

• makeError(),
• makeErrorResource()
• makeLink() (Create link object inside links data: https://jsonapi.org/format/#document-links)
• makeLinks()
• makePagination() (Make special Links object with pagination standard required)
• makeMeta()
• makeRelationship() (Create relationship object inside relationships data: https://jsonapi.org/format/#document-resource-object-relationships)
• makeRelationships()

You can see more examples in /examples/index.php

Document Query

New feature in v2, now you can make query to find resources (HackerBoy\JsonApi\Abstracts\Resource) in a document by using $document->getQuery() method. $document->getQuery() return an instance of Laravel Illuminate\Support\Collection (Check the link for full document of querying methods).

Objects returned by query are \HackerBoy\JsonApi\Abstracts\Resource

Example of document query

Client-Side usages

Flexible document and resources

• Flexible document can be used exactly like normal document, but $config is optional, flexible resource allowed... You can consider it as a "free schema" version of document.
• Flexible document can use the same $config as normal document, then you can use it to work with flexible resource and mapped resource in the same document.
• Flexible document might be helpful for projects with no ORM, build JSON API data quickly without configuration, build JSON API data to POST to another JSON API endpoint...
• Flexible document is not recommended anyway, as it allows to build a document in a free way and may cause unpredicted errors to your API like missing elements, invalid format...etc... So use it carefully and wisely

Example of flexible document

Parse from string or array

Parse from string