# How to use ### 3.0 How to use In the current version of our PHP SDK you can find only a few methods that you can implement in your code but they're so powerful that enable you to do pretty anything with MBurger CMS. The SDK will return an array representing the response. By default methods that returns a list of objects are limited to 25 elements. See below for how to use pagination. This SDK offers a fluent syntax composed of these parts: 1. Class instance 2. Parameters or Modifiers 3. Desired function Below are reported all parameters/modifiers and functions with some examples. For a complete list of all available parameters we remand to the official API documentation . #### 3.1 Instantiate the SDK To instantiate the SDK simply use: ``` $sdk = new MBurger(); ``` or use the compact version (useful for chaining): ``` $response = (new MBurger())->getProject(); ``` #### 3.2 Functions To obtain a project ``` $response = (new MBurger())->getProject(); ``` To obtain a list of blocks ``` $response = (new MBurger())->getBlocks(); ``` To obtain a specific block by id ``` $response = (new MBurger())->getBlock($block_id); ``` To obtain a list of sections ``` $response = (new MBurger())->getSections($block_id); ``` To obtain a specific section by id or slug ``` $response = (new MBurger())->getSection($block_id_or_slug); ``` #### 3.3 Modifiers Below a list of modifiers (or middle methods) useful to personalize the request. **3.3.1 Locale** To request a specific locale use the `locale(string $locale)` modifier. Example: ``` $response = (new MBurger())->locale($locale)->getProject(); ``` If the requested locale is not present an automatic fallback will be done. If you want to force the fallback if the requested locale is not present or is empty use the `forceLocaleFallback()` modifier: ``` $response = (new MBurger())->forceLocaleFallback()->getBlock(); ``` **3.3.2 Pagination** To use pagination in functions that returns a list of items use the modifiers `skip(int $skip)` and `take(int $take)`. Example: ``` $response = (new MBurger())->skip(5)->take(50)->getSections(100); ``` Defaults are 0 and 25. The response will include a meta field containing the info for pagination, like total items and actual index. **3.3.3 Including** To include relations on the response are available a set of convenience methods. This can be useful, for example, for obtaining in one request all the desired sections with the related elements. > NOTE: Not all methods are compatible with all functions. The SDK will throw an `MBurgeInvalidRequestException` exception. Check our API references for more info. > NOTE: loading a lot of relations in one request can have a negative impact on performances. * `include(array $include)`: generic method, you can pass an array of desired relations. * `includeBlocks()`: it will include *blocks*. Available only on `getProject()`. * `includeSections()`: it will include *sections*. Available only on `getBlocks()` and `getBlock()`. * `includeElements()`: it will include *elements*. Available only on `getSections()` and `getSection()`. * `includeStructure()`: it will include *block* structure. Available only on `getProject()`, `getBlocks()` and `getBlock()`. * `includeBeacons()`: it will include beacons. Available only on `getProject()`, `getSections()` and `getSection()`. * `includeContracts()`: it will include *blocks*. Available only on `getProject()`. Example: get first 15 sections of block 100 with the related elements ``` $response = (new MBurger())->take(15)->includeElements()->getSections(100); ``` **3.3.4 Sorting** To apply specific orders is available this method `sortBy(string $value, string $direction = 'asc')`. the first argument specify on which value do the sorting, and the second the direction. Example: ``` $response = (new MBurger())->sortBy('created_at', 'desc')->take(15)->getSections(100); ``` The default sorting in by *id* and ascending. > NOTE: this method is only available on functions that returns a list of items. **3.3.4 Filtering** To filter items are available a set of convenience methods. > NOTE: Not all methods are compatible with all functions. The SDK will throw an `MBurgeInvalidRequestException` exception. Check our API references for more info. > NOTE: these methods are only available on functions that returns a list of items. * `filterByIds(array $ids)`: it filters based an array on id with an exact match. Available only on `getBlocks()` and `getSections()`. * `filterByRelation(int $block_id, int $section_id)`: it filters based on related *sections*. Available only on `getSections()`. * `filterByValue(array $values, string $element_name = null)`: it filters based on array of values. Specifying the second parameter `element_name` the filtering in done only on *elements* the match the name. Available only on `getSections()`. * `filterByTitle(string $title)`: it filters based on title. Available only on `getBlocks()`. * `filterByGeofence(float $latNE, float $latSW, float $lngNE, float $lngSW)`: it filters based on geofence rectangle. Available only on `getSections()`. **3.3.5 Distance** If you have *sections* with elements of type *address* (which automatically contains coordinates) you can obtain your distance from the "*section*" (like a POI) with the method `istance(float $latitude, float $longitude)` by providing your coordinates. Example: ``` $response = (new MBurger())->distance(22.231232, 16.325322)->getSections(100); ``` > NOTE: this method is only available on functions `getSections()`. **3.3.6 Slug** Normally a *section* is retrieved by *id* or *slug*. MBurger tries to infer which method to use based on the type of the parameter: if it's numeric it will use the *id*, if it's a string it will use the *slug*. Is possible to force using the *slug* with the following method `forceSlug()`. Example: ``` $response = (new MBurger())->locale('en')->forceSlug()->getSection('321287'); ``` > NOTE: this method is only available on functions `getSection()`. #### 3.4 Errors MBurger SDK use an exception based error system, in case of error it will throw an exception with a descritive message. #### 3.5 Cache Every function contains a method `cache(int $cache_ttl = 0)` to automatically cache the response. The TTL is in seconds. Example: ``` $response = (new MBurger())->cache(300)->getSections(100); ``` #### 3.6 Transformers There are utility methods useful to transform the response in a more usable format. To transform blocks use `transformBlocks($blocks)`. Example: ``` $blocks = (new MBurger())->getBlocks(); $data = MBurger::transformBlocks($blocks); ``` ###