Download the PHP package seankndy/fluent-sonar-api without Composer

fluent-sonar-api

This is a Sonar Software (https://sonar.software) v2 GraphQL PHP API client with a fluent interface. It aims to make your common fetch queries and mutations simple and somewhat Laravel Eloquent-like.

The key benefits of using this library is the fluent interface for a nice DX and the returned resources are real PHP objects allowing static analyzers to assist in preventing bugs and your IDE can do code completions.

Installation

You can install the package via composer:

Queries

Queries are done by calling the top level object name as a method and then chaining your filters, sorts, and relations to load. The method name should be in camel-case and plural, for example to query network sites then the method name would be networkSites(). Basic Accounts example:

Objects returned from Sonar's API need to be mapped to real PHP objects that the library refers to as Resources. Several core Sonar objects are included in this library in the \SeanKndy\SonarApi\Resources namespace and you may create your own object resources by extending \SeanKndy\SonarApi\Resources\BaseResource.

Relations are not queried by default and you must use the with() method to state which relations you want to load (as done above). If you want to filter or sort the related resources you can do so with a closure:

In the above example, tickets will be sorted ascending by the created_at field.

If you want to supply your own resource class, you can do so by passing a fourth argument to Client's constructor:

Now when calling inventoryItems() on the Client object a query builder using App\Support\SonarApi\Resources\InventoryItem will be used instead of the built-in InventoryItem class.

where() and whereHas()

When writing queries you can filter them using the where methods. where() and orWhere() create Sonar search filter objects. There are limitations to grouping search logic due to how the search filters work in Sonar's API. It is probably simplest to just show various call structures supported and the resulting search logic they produce:

where() and orWhere() have the same arguments: field, operator, search_value. You can pass only 2 arguments and it is assumed the second argument is the search_value and the operator is '='.

whereHas(), orWhereHas(), whereNotHas() and orWhereNotHas() are also supported and these produce Sonar's ReverseRelationFilters. They filter the current object based on the xfiltering of a related object. Example showing a way to get only accounts that have related Addresses with a city of Chicago:

The second argument passed to whereHas() is a closure that receives a \SeanKndy\SonarApi\Queries\Search\Search object which is a where()-able object to build searches.

The second argument is optional and if not passed then the filter will be for the presence of any objects on the relation.

orWhereHas() allows you to specify an ORed relation filter. For example, let's get any account that has an address in Chicago OR the account has any invoices present at all:

Lastly, you can use whereNotHas() and orWhereNotHas() to filter on the absence of a relation such as if you wanted to get all accounts that have NO tickets:

These not-has methods do not support a second search closure argument.

Not that any of the where-has type methods do not require that the relation be loaded by with() for them to be effective.

Pagination

Pagination is supported via Laravel/Illuminate's LengthAwarePaginator:

The underlying pagination is done on Sonar's side using Sonar's Paginator in GraphQL.

Creating Resource Objects

Here is an example of how you can create your own resource objects (note that the Company object is already included in the library):

All properties must be public and type hinted. Sonar uses snake-casing on all fields and so camel-cased properties and relations are automatically converted to snake-case.

A has-one relationship should be specified with the resource object such as public AccountStatus $accountStatus; where AccountStatus is another resource. If there is a has-many relation then you type hint using a phpdoc @var statement above the property declaration as in the $accounts property above. Note that you must type hint with the full namespace path when doing @var hints.

Mutations

Mutations are executed using the MutationQueryBuilder which is returned by calling mutations() on the client object. Simply pass in the variables/argument as an associative array to the mutation name method call. Variables that are required should have an exclamation (!) after the variable name like id! in the below example.

There are two ways to build typed input data:

1) Entirely in-line using arrays and closures 2) Write mutation input classes that extend SeanKndy\SonarApi\Mutations\Inputs\BaseInput.

Here is an example of using the in-line approach for the type-based input input:

Here is an example of the same mutation, but using a class-based approach to the input:

The return() method indicates what resource should be returned by the mutation. Again, view Sonar's documentation to view each mutation's return type.

You may have noticed that id is an instance of \SeanKndy\SonarApi\Types\Int64Bit. This is a wrapper type object which mocks the data type within Sonar's GraphQL schema and is required for this mutation. See Sonar's API documentation (https://api.sonar.software) to view any mutation's specifications.

The class-based approach has the benefit of throwing exceptions if the field doesn't exist or the field value given does not match the type specified. These can be created easily by extending SeanKndy\SonarApi\Mutations\Inputs\BaseInput:

Notice that the properties are all protected not public. This is a requirement and if you extend BaseInput and declare public properties an exception will be thrown upon object instantiation. The reason they're protected is because BaseInput controls setting the values of each property so it knows which properties to actually include in the mutation. For example, say you want to update the ticket's subject field and nothing else. You can do this by either:

or

BaseInput uses PHP's __set() method to set the protected property on your behalf here and also keep track of which properties have been set so it knows which to include in the mutation sent to Sonar. If it didn't do this then it would send all the fields in the mutation and update fields that you never wanted updated to null/empty values.

Arrays of Types

If you need to specify an array of types, you can do the following:

SuccessResponse's

In the last example above we used a SeanKndy\SonarApi\Resources\SuccessResponse for the mutation return resource. You'll see this response type on several mutations in Sonar that they use when there is no other appropriate response. This is just to make you aware that this resource type is built-in for your use.

File Operations

File operations in Sonar (upload and download) are supported. Example of working with a file contained in Sonar:

Example of uploading a file to Sonar: