{"id":26430441,"url":"https://github.com/i-doit/api-client-php","last_synced_at":"2025-03-18T05:31:49.663Z","repository":{"id":12986110,"uuid":"73118710","full_name":"i-doit/api-client-php","owner":"i-doit","description":"Easy-to-use, but feature-rich client library for i-doit's JSON-RPC API","archived":false,"fork":false,"pushed_at":"2024-02-09T12:59:18.000Z","size":1232,"stargazers_count":14,"open_issues_count":4,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-04-23T23:15:18.312Z","etag":null,"topics":["api","api-client","cmdb","i-doit"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/i-doit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-07T20:36:59.000Z","updated_at":"2024-06-21T19:05:56.767Z","dependencies_parsed_at":"2024-06-21T19:05:54.912Z","dependency_job_id":"5bc33ee4-6d26-4e2d-912a-6d958decd019","html_url":"https://github.com/i-doit/api-client-php","commit_stats":{"total_commits":408,"total_committers":9,"mean_commits":"45.333333333333336","dds":0.06372549019607843,"last_synced_commit":"8c1fe9222b1cff67c7501dbe60bcf44bead3044a"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-doit%2Fapi-client-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-doit%2Fapi-client-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-doit%2Fapi-client-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-doit%2Fapi-client-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/i-doit","download_url":"https://codeload.github.com/i-doit/api-client-php/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244164897,"owners_count":20409006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","cmdb","i-doit"],"created_at":"2025-03-18T05:31:15.928Z","updated_at":"2025-03-18T05:31:49.641Z","avatar_url":"https://github.com/i-doit.png","language":"PHP","readme":"# i-doit API client library\n\nEasy-to-use, but feature-rich client library for i-doit's JSON-RPC API\n\n[![Latest stable version](https://img.shields.io/packagist/v/idoit/apiclient.svg)](https://packagist.org/packages/idoit/apiclient)\n[![Minimum PHP version](https://img.shields.io/badge/php-%3E%3D%208.0-8892BF.svg)](https://php.net/)\n[![Build status](https://github.com/i-doit/api-client-php/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/i-doit/api-client-php/actions)\n\n**Please note: This project is not an official product by synetics GmbH. synetics GmbH doesn't provide any commercial support.**\n\n## About\n\n[i-doit](https://i-doit.com) is a software application for IT documentation and a CMDB (Configuration Management Database). This application is very useful to collect all your knowledge about the IT infrastructure you are dealing with. i-doit is a Web application and [has an exhausting API](https://kb.i-doit.com/pages/viewpage.action?pageId=37355644) which is very useful to automate your infrastructure.\n\nThis API client library provides a simple, but powerful abstraction layer to send requests to i-doit's API. It is written in pure PHP.\n\n## Features\n\nWhy should you use this API client library? There are some good reasons:\n\n-   Easy to use\n-   There is a PHP function for each API method\n-   Supports batch requests (much faster)\n-   Sends user-defined requests\n-   Uploads files and images\n-   Supports login and logout methods to save sessions\n-   Follows redirects (HTTP 301/302) automatically\n-   Uses optional HTTP or SOCKS5 proxy\n-   Verifies TLS certificate chains\n-   Throws exception on error\n-   Many examples\n-   Well-documented\n-   Easy to install via Composer\n-   Well-tested with tons of integration tests\n\nWhat's new? Take a look at the [changelog](CHANGELOG.md).\n\n## Requirements\n\nMeet these simple requirements before using the client:\n\n-   A running instance of i-doit pro/open, version `30` or higher (older versions may work but are not supported)\n-   i-doit API add-on, version `2.0` or higher (older versions may work but are not supported)\n-   PHP, version `8.0` or higher (`8.2` is recommended)\n-   PHP modules `curl`, `date`, `json`, `openssl` and `zlib`\n\nAs a rule of thumb, always use the latest stable releases to benefit from new features, improvements and bug fixes.\n\n## Installation\n\nIt is recommended to install this client via [Composer](https://getcomposer.org/). Change to your project's root directory and fetch the latest stable version:\n\n~~~ {.bash}\ncomposer require idoit/apiclient\n~~~\n\nInstead of sticking to a specific/minimum version you may switch to the current development branch by using `@DEV`:\n\n~~~ {.bash}\ncomposer require \"idoit/apiclient=@DEV\"\n~~~\n\n## Updates\n\nComposer has the great advantage (besides many others) that you can simply update the API client library by running:\n\n~~~ {.bash}\ncomposer update\n~~~\n\n## Usage\n\nIf you use Composer you should use its own autoloader, too:\n\n~~~ {.php}\nrequire_once 'vendor/autoload.php';\n~~~\n\nThis is it. All other files will be auto-loaded on-the-fly if needed.\n\n## Configuration\n\nThe API client library class requires a configuration:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\n\n$api = new API([\n    API::URL =\u003e 'https://demo.i-doit.com/src/jsonrpc.php',\n    API::PORT =\u003e 443,\n    API::KEY =\u003e 'c1ia5q',\n    API::USERNAME =\u003e 'admin',\n    API::PASSWORD =\u003e 'admin',\n    API::LANGUAGE =\u003e 'en',\n    API::PROXY =\u003e [\n        API::PROXY_ACTIVE =\u003e false,\n        API::PROXY_TYPE =\u003e 'HTTP', // 'HTTP' or 'SOCKS5'\n        API::PROXY_HOST =\u003e 'proxy.example.net',\n        API::PROXY_PORT =\u003e 8080,\n        API::PROXY_USERNAME =\u003e '',\n        API::PROXY_PASSWORD =\u003e ''\n    ],\n    API::BYPASS_SECURE_CONNECTION =\u003e false\n]);\n~~~\n\n-   `API::URL`: URL to i-doit's API, probably the base URL appended by `src/jsonrpc.php`\n-   `API::PORT`: optional port on which the Web server listens; if not set port 80 will be used for HTTP and 443 for HTTPS\n-   `API::KEY`: API key\n-   `API::USERNAME` and `API::PASSWORD`: optional credentials if needed, otherwise `System API` user will be used\n-   `API::LANGUAGE`: requests to and responses from i-doit will be translated to this language (`de` and `en` supported); this is optional; defaults to user's prefered language\n-   `API::PROXY`: use a proxy between client and server\n    -   `API::PROXY_ACTIVE`: if `true` proxy settings will be used\n    -   `API::PROXY_TYPE`: use a HTTP (`API::PROXY_TYPE_HTTP`) or a SOCKS5 (`API::PROXY_TYPE_SOCKS5`) proxy\n    -   `API::PROXY_HOST`: FQDN or IP address to proxy\n    -   `API::PROXY_PORT`: port on which the proxy server listens\n    -   `API::PROXY_USERNAME` and `API::PROXY_PASSWORD`: optional credentials used to authenticate against the proxy\n-   `API::BYPASS_SECURE_CONNECTION`: Set to `true` to disable security-related cURL options; defaults to `false`; do not set this in production!\n\n## Examples\n\nA basic \"Hello, World!\" example is to fetch some basic information about your i-doit instance:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\Idoit;\n\nrequire_once 'vendor/autoload.php';\n\n$api = new API([\n    API::URL =\u003e 'https://demo.i-doit.com/src/jsonrpc.php',\n    API::KEY =\u003e 'c1ia5q',\n    API::USERNAME =\u003e 'admin',\n    API::PASSWORD =\u003e 'admin'\n]);\n\n$request = new Idoit($api);\n$info = $request-\u003ereadVersion();\n\nvar_dump($info);\n~~~\n\nIt is simple like that. For more examples take a look at the next sub sections.\n\n### Login and logout\n\nOne sweet thing about i-doit's API you can (and should) use one user session for your stuff. This saves resources on the server side and allows you to perform a lot more calls in a short time.\n\nThe session handling is done by the API client library. You just need to login. And if you are nice you want to logout after your work is done.\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\n\n$api = new API([/* … */]);\n\n$api-\u003elogin();\n// Do your stuff…\n$api-\u003elogout();\n~~~\n\nIf you are unsure in which condition your session is try `isLoggedIn()`:\n\n~~~ {.php}\n$api-\u003eisLoggedIn(); // Returns true or false\n~~~\n\n### Pre-defined methods\n\nFor almost every case there is a remote procedure you may call to read from or manipulate i-doit's database through its API. Each remote procedure is assigned to a namespace to keep the API clean and smoothly. Furtunately, you do not need to call these remote procedures on your own. The API client library provides for each namespace a class and for each remote procedure a method. Here is a quick overview:\n\n| Namespace                     | Remote Procedure Call (RPC)           | Class in API Client Library   | Method                                                    |\n| ----------------------------- | ------------------------------------- | ----------------------------- | --------------------------------------------------------- |\n| `idoit`                       | `idoit.addons`                        | `Idoit`                       | `getAddOns()`                                             |\n|                               | `idoit.constants`                     |                               | `readConstants()`                                         |\n|                               | `idoit.license`                       |                               | `getLicense()`                                            |\n|                               | `idoit.search`                        |                               | `search()`                                                |\n|                               | `idoit.version`                       |                               | `readVersion()`                                           |\n|                               | `idoit.login`                         | `API`                         | `login()`                                                 |\n|                               | `idoit.logout`                        |                               | `logout()`                                                |\n| `cmdb.object`                 | `cmdb.object.create`                  | `CMDBObject`                  | `create()`                                                |\n|                               | `cmdb.object.read`                    |                               | `read()`                                                  |\n|                               | `cmdb.object.update`                  |                               | `update()`                                                |\n|                               | `cmdb.object.archive`                 |                               | `archive()`                                               |\n|                               | `cmdb.object.delete`                  |                               | `delete()`                                                |\n|                               | `cmdb.object.purge`                   |                               | `purge()`                                                 |\n| `cmdb.objects`                | `cmdb.objects.read`                   | `CMDBObjects`                 | `read()`                                                  |\n| `cmdb.category`               | `cmdb.category.create`                | `CMDBCategory`                | `create()`                                                |\n|                               | `cmdb.category.read`                  |                               | `read()`, `readOneByID()`, `readFirst()`                  |\n|                               | `cmdb.category.update`                |                               | `update()`                                                |\n|                               | `cmdb.category.save`                  |                               | `save()`                                                  |\n|                               | `cmdb.category.archive`               |                               | `archive()`                                               |\n|                               | `cmdb.category.delete`                |                               | `delete()`                                                |\n|                               | `cmdb.category.purge`                 |                               | `purge()`                                                 |\n| `cmdb.category_info`          | `cmdb.category_info.read`             | `CMDBCategoryInfo`            | `read()`                                                  |\n| `cmdb.condition`              | `cmdb.condition.read`                 | `CMDBCondition`               | `read()`                                                  |\n| `cmdb.dialog`                 | `cmdb.dialog.create`                  | `CMDBDialog`                  | `create()`                                                |\n|                               | `cmdb.dialog.read`                    |                               | `read()`                                                  |\n|                               | `cmdb.dialog.delete`                  |                               | `delete()`                                                |\n| `cmdb.impact`                 | `cmdb.impact.read`                    | `CMDBImpact`                  | `readByID()`, `readByConst()`                             |\n| `cmdb.location_tree`          | `cmdb.location_tree.read`             | `CMDBLocationTree`            | `read()`, `readRecursively()`                             |\n| `cmdb.logbook`                | `cmdb.logbook.create`                 | `CMDBLogbook`                 | `create()`                                                |\n|                               | `cmdb.logbook.read`                   |                               | `read()`                                                  |\n| `cmdb.objects_by_relation`    | `cmdb.objects_by_relation.read`       | `CMDBObjectsByRelation`       | `readByID()`, `readByConst()`                             |\n| `cmdb.object_type_categories` | `cmdb.object_type_categories.read`    | `CMDBObjectTypeCategories`    | `readByID()`, `readByConst()`                             |\n| `cmdb.object_type_groups`     | `cmdb.object_type_groups.read`        | `CMDBObjectTypeGroups`        | `read()`                                                  |\n| `cmdb.object_types`           | `cmdb.object_types.read`              | `CMDBObjectTypes`             | `read()`, `readOne()`, `readByTitle()`                    |\n| `cmdb.reports`                | `cmdb.reports.read`                   | `CMDBReports`                 | `read()`, `listReports()`                                 |\n| `cmdb.workstation_components` | `cmdb.workstation_components.read`    | `CMDBWorkstationComponents`   | `read()`, `readByEMail()`, `readByEMails()`               |\n| `checkmk.statictag`           | `checkmk.statictag.create`            | `CheckMKStaticTag`            | `create()`                                                |\n|                               | `checkmk.statictag.read`              |                               | `read()`, `readByID()`, `readByIDs()`, `readByTag()`      |\n|                               | `checkmk.statictag.update`            |                               | `update()`                                                |\n|                               | `checkmk.statictag.delete`            |                               | `delete()`                                                |\n| `checkmk.tags`                | `checkmk.tags.read`                   | `CheckMKTags`                 | `read()`                                                  |\n| `monitoring.livestatus`       | `monitoring.livestatus.create`        | `MonitoringLivestatus`        | `createTCPConnection`, `createUNIXSocketConnection`       |\n|                               | `monitoring.livestatus.read`          |                               | `read()`, `readByID()`, `readByIDs()`, `readByTitle()`    |\n|                               | `monitoring.livestatus.update`        |                               | `update()`                                                |\n|                               | `monitoring.livestatus.delete`        |                               | `deleteByID()`, `deleteByTitle()`                         |\n\nAdditionally, this API client library is shipped with methods as workarounds for remote procedure calls you probably miss. The RPC `cmdb.objects.create` does not exist but you may use `CMDBObjects::create()`. It simulates the missing RPC and gives you an easier and faster way to manipulate your CMDB.\n\nIf it makes sense there are methods to perform batch requests for most RPCs. For example, `CMDBCategory::batchRead()` fetches multiple category entries at once.\n\n### Examples\n\n#### Search in i-doit's database\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\Idoit;\n\n$api = new API([/* … */]);\n\n$idoit = new Idoit($api);\n$result = $idoit-\u003esearch('Server XY');\n\nvar_dump($result);\n~~~\n\nPerform more than one search at once:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\Idoit;\n\n$api = new API([/* … */]);\n\n$idoit = new Idoit($api);\n$result = $idoit-\u003ebatchSearch([\n    'Server XY',\n    'Client A',\n    'John Doe'\n]);\n\nvar_dump($result);\n~~~\n\n#### Create a new object\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObject;\n\n$api = new API([/* … */]);\n\n$object = new CMDBObject($api);\n$objectID = $object-\u003ecreate(\n    'C__OBJTYPE__SERVER',\n    'Server XY'\n);\n\nvar_dump($objectID);\n~~~\n\n#### Read common information about an object\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObject;\n\n$api = new API([/* … */]);\n\n$object = new CMDBObject($api);\n$objectInfo = $object-\u003eread(42);\n\nvar_dump($objectInfo);\n~~~\n\n#### Load all data of an object\n\nThis will fetch everything about an object: common data, assigned categories and category entries as well.\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObject;\n\n$api = new API([/* … */]);\n\n$object = new CMDBObject($api);\n$objectInfo = $object-\u003eload(42);\n\nvar_dump($objectInfo);\n~~~\n\nThe method `load()` triggers round about 4 API calls. So be aware if it is heavily used.\n\n#### Update an existing object\n\nCurrently, you are able to update an object's title:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObject;\n\n$api = new API([/* … */]);\n\n$object = new CMDBObject($api);\n$object-\u003eupdate(\n    42,\n    [\n        'title' =\u003e 'A shiny new object title'\n    ]\n);\n~~~\n\n#### Create or update an object (\"upsert\")\n\nYou you like to get an identifier of an object but you are unsure whether or not it exists, try an upsert. This is an \"update\" and an \"insert\" at the same time. This means, if the object exists you will get its identifier directly. If not the object will be created and then you will get its identifier. Objects must match against type and title. Additional attributes will be stored.\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObject;\n\n$api = new API([/* … */]);\n\n$object = new CMDBObject($api);\n$object-\u003eupsert(\n    'C__OBJTYPE__SERVER',\n    'My little server',\n    [\n        'purpose' =\u003e 'Private stuff'\n    ]\n);\n~~~\n\n#### Fetch an object identifier\n\nFetch an object identifier by object title and (optional) type:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObjects;\n\n$api = new API([/* … */]);\n\n$object = new CMDBObjects($api);\n$objectID = $object-\u003egetID('My little server');\n$objectID = $object-\u003egetID('My little server', 'C__OBJTYPE__SERVER');\n~~~\n\nAn exception error will be thrown if there is either no object or more than one.\n\n#### Change documentation status of an object\n\ni-doit has the concept of archiving your IT documentation. Each object has an status (`normal`, `archived`, marked as `deleted`). And last but not least, an object may be purged from the database.\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObject;\n\n$api = new API([/* … */]);\n\n$object = new CMDBObject($api);\n$objectID = 42;\n// Archive:\n$object-\u003earchive($objectID);\n// Mark as deleted:\n$object-\u003edelete($objectID);\n// Purge from database:\n$object-\u003epurge($objectID);\n~~~\n\n#### Create multiple objects\n\nCreate multiple objects at once:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObjects;\n\n$api = new API([/* … */]);\n\n$cmdbObjects = new CMDBObjects($api);\n\n$objectIDs = $cmdbObjects-\u003ecreate(\n    [\n        ['type' =\u003e 'C__OBJTYPE__SERVER', 'title' =\u003e 'Server No. One'],\n        ['type' =\u003e 'C__OBJTYPE__SERVER', 'title' =\u003e 'Server No. Two'],\n        ['type' =\u003e 'C__OBJTYPE__SERVER', 'title' =\u003e 'Server No. Three']\n    ]\n);\n\nvar_dump($objectIDs);\n~~~\n\n#### Read multiple objects\n\nReading multiple objects at once is provided by several methods. Let's see:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObjects;\n\n$api = new API([/* … */]);\n\n$cmdbObjects = new CMDBObjects($api);\n\n// Fetch every object:\n$objects = $cmdbObjects-\u003eread();\nvar_dump($objects);\n\n// Fetch max. 10 servers and sort them descending by title:\n$objects = $cmdbObjects-\u003eread(['type' =\u003e 'C__OBJTYPE__SERVER'], 10, 0, 'title', CMDBObjects::SORT_DESCENDING);\nvar_dump($objects);\n\n// Get them by their identifiers:\n$objects = $cmdbObjects-\u003ereadByIDs([1, 2, 3]);\nvar_dump($objects);\n\n// Get all servers:\n$objects = $cmdbObjects-\u003ereadByType('C__OBJTYPE__SERVER');\nvar_dump($objects);\n\n// Get archived clients:\n$objects = $cmdbObjects-\u003ereadArchived('C__OBJTYPE__CLIENT');\nvar_dump($objects);\n\n// Get clients marked as deleted:\n$objects = $cmdbObjects-\u003ereadDeleted('C__OBJTYPE__CLIENT');\nvar_dump($objects);\n~~~\n\n#### Update multiple objects\n\nUpdate multiple objects at once:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObjects;\n\n$api = new API([/* … */]);\n\n$cmdbObjects = new CMDBObjects($api);\n\n// Rename objects 1, 2, 3:\n$cmdbObjects-\u003eupdate([\n  ['id' =\u003e 1, 'title' =\u003e 'New name'],\n  ['id' =\u003e 2, 'title' =\u003e 'Another name'],\n  ['id' =\u003e 3, 'title' =\u003e 'Just a name'],\n]);\n~~~\n\n#### Archive/delete/purge multiple objects\n\nArchive objects, mark them as deleted or even purge them from database:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObjects;\n\n$api = new API([/* … */]);\n\n$cmdbObjects = new CMDBObjects($api);\n\n$cmdbObjects\n    -\u003earchive([1, 2, 3])\n    -\u003edelete([1, 2, 3])\n    -\u003epurge([1, 2, 3]);\n~~~\n\n#### Read object by condition\n\nAllowed comparison are '=', '!=', 'like', 'not like', '\u003e', '\u003e=', '\u003c', '\u003c=', '\u003c\u003e'.\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBCondition;\n\n$api = new API([/* … */]);\n$condition = new CMDBCondition($api);\n$result = $condition-\u003eread(\n    [\n        [\n            'property' =\u003e \"C__CATG__ACCOUNTING-order_no\",\n            'comparison' =\u003e \"=\",\n            'value' =\u003e \"ORDER4711\",\n        ]\n    ]\n);\n~~~\n\nYou can use more than one condition and add an operator to them.\nAllowed operators are 'AND' and 'OR'.\n\n~~~ {.php}\n$result = $condition-\u003eread(\n    [\n        [\n            'property' =\u003e \"C__CATG__ACCOUNTING-order_no\",\n            'comparison' =\u003e \"=\",\n            'value' =\u003e \"ORDER4711\",\n        ],\n        [\n            'property' =\u003e \"C__CATG__ACCOUNTING-order_no\",\n            'comparison' =\u003e \"=\",\n            'value' =\u003e \"ORDER0815\",\n            'operator' =\u003e 'OR',\n        ]\n    ]\n);\n~~~\n\nFor more readable code you can use the condition helper class.\n\n~~~ {.php}\nuse Idoit\\APIClient\\Condition;\n\n$conditions = [\n    new Condition(\"C__CATG__ACCOUNTING\", \"order_no\", \"=\", \"ORDER4711\"),\n    new Condition(\"C__CATG__ACCOUNTING\", \"order_no\", \"=\", \"ORDER4711\", Condition::OR),\n];\n$result = $condition-\u003eread($conditions);\n~~~\n\n#### Create category entries with attributes\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBCategory;\n\n$api = new API([/* … */]);\n\n$category = new CMDBCategory($api);\n$entryID = $this-\u003ecategory-\u003esave(\n    42,\n    'C__CATG__IP',\n    [\n        'net' =\u003e 123,\n        'active' =\u003e 1,\n        'primary' =\u003e 0,\n        'net_type' =\u003e 1,\n        'ipv4_assignment' =\u003e 2,\n        'ipv4_address' =\u003e  '10.20.10.100',\n        'description' =\u003e 'API TEST'\n    ]\n);\n\nvar_dump($entryID);\n~~~\n\nAlternatively, use method `CMDBCategory::batchCreate()` for batch requests.\n\n#### Read categories and attributes\n\nRead one or more category entries for one specific object:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBCategory;\n\n$api = new API([/* … */]);\n\n$category = new CMDBCategory($api);\n$result = $category-\u003eread(42, 'C__CATG__IP');\n\nvar_dump($result);\n~~~\n\nRead one specific categoy entry for one specific object:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBCategory;\n\n$api = new API([/* … */]);\n\n$category = new CMDBCategory($api);\n$result = $category-\u003ereadOneByID(42, 'C__CATG__IP', 23);\n\nvar_dump($result);\n~~~\n\nRead just one category entry (easier than `read()` when using single-valued categories):\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBCategory;\n\n$api = new API([/* … */]);\n\n$category = new CMDBCategory($api);\n$result = $category-\u003ereadFirst(42, 'C__CATG__IP');\n\nvar_dump($result);\n~~~\n\nRead data for multiple objects and categories at once:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBCategory;\n\n$api = new API([/* … */]);\n\n$category = new CMDBCategory($api);\n$result = $category-\u003ebatchRead(\n    [23, 42],\n    ['C__CATG__IP', 'C__CATG__MODEL']\n);\n\nvar_dump($result);\n~~~\n\n#### Update categories and attributes\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBCategory;\n\n$api = new API([/* … */]);\n\n$category = new CMDBCategory($api);\n$category-\u003esave(\n    42,\n    'C__CATG__GLOBAL',\n    [\n        'cmdb_status' =\u003e 10\n    ]\n);\n~~~\n\nAlternatively, use method `CMDBCategory::batchUpdate()` for batch requests.\n\n#### Change documentation status of a category and its attributes\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBCategory;\n\n$api = new API([/* … */]);\n\n$category = new CMDBCategory($api);\n// Archive:\n$category-\u003earchive(42, 'C__CATG__CPU', 1);\n// Mark as deleted:\n$category-\u003edelete(42, 'C__CATG__CPU', 2);\n// Purge from database:\n$category-\u003epurge(42, 'C__CATG__CPU', 3);\n~~~\n\n#### Create values in drop-down menus\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBDialog;\n\n$api = new API([/* … */]);\n\n$dialog = new CMDBDialog($api);\n\n$entryID = $dialog-\u003ecreate('C__CATG__MODEL', 'title', 'My model');\nvar_dump($entryID);\n\n$entryIDs = $dialog-\u003ebatchCreate([\n    'C__CATG__MODEL' =\u003e [\n        'manufacturer' =\u003e 'My manufacturer',\n        'title' =\u003e 'My model'\n    ],\n    'C__CATG__GLOBAL' =\u003e [\n        'category' =\u003e [\n            'cat 1',\n            'cat 2',\n            'cat 3'\n        ],\n        'purpose' =\u003e 'API TEST'\n    ]\n]);\nvar_dump($entryIDs);\n~~~\n\n#### Fetch values from drop-down menus\n\nDrop-down menus in i-doit are called \"dialog\" (read-only) or \"dialog+\" (editable).\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBDialog;\n\n$api = new API([/* … */]);\n\n$dialog = new CMDBDialog($api);\n\n$models = $dialog-\u003eread('C__CATG__MODEL', 'title');\nvar_dump($models);\n\n$modelsAndManufacturers = $dialog-\u003ebatchRead([\n    'C__CATG__MODEL' =\u003e [\n        'manufacturer',\n        'title'\n    ]\n]);\nvar_dump($modelsAndManufacturers);\n~~~\n\n#### Build a location tree\n\nRead objects located directly under an object:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBLocationTree;\n\n$api = new API([/* … */]);\n\n$locationTree = new CMDBLocationTree($api);\n$result = $locationTree-\u003eread(1);\n\nvar_dump($result);\n~~~\n\nRead recursively objects located under an object:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBLocationTree;\n\n$api = new API([/* … */]);\n\n$locationTree = new CMDBLocationTree($api);\n$result = $locationTree-\u003ereadRecursively(1);\n\nvar_dump($result);\n~~~\n\n#### Fetch relations between objects\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObjectsByRelation;\n\n$api = new API([/* … */]);\n$relation = new CMDBObjectsByRelation($api);\n\n$result = $relation-\u003eread(\n    10,\n    'C__RELATION_TYPE__PERSON_ASSIGNED_GROUPS'\n);\n\nvar_dump($result);\n~~~\n\n#### Fetch workplace components for a person\n\nA Person may be assigned to a workplace with several components like a PC, a monitor and a telephone. These components can be fetched by the person. You either need the object ID or the email address. Even more than one workplaces are supported.\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBWorkstationComponents;\n\n$api = new API([/* … */]);\n$components = new CMDBWorkstationComponents($api);\n\n$result = $components-\u003eread(111); // Person object with ID 111\nvar_dump($result);\n\n$result = $components-\u003ebatchRead([111, 222]); // Person objects with IDs 111 and 222\nvar_dump($result);\n\n$result = $components-\u003ereadByEMail('alice@example.org'); // Person object with email address\nvar_dump($result);\n\n$result = $components-\u003ereadByEMails(['alice@example.org', 'bob@example.org']); // Person objects with email addresses\nvar_dump($result);\n~~~\n\n#### Reports\n\nList all reports:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBReports;\n\n$api = new API([/* … */]);\n$reports = new CMDBReports($api);\n\n$result = $reports-\u003elistReports();\n\nvar_dump($result);\n~~~\n\nFetch the result of a report:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBReports;\n\n$api = new API([/* … */]);\n$reports = new CMDBReports($api);\n\n$result = $reports-\u003eread(1);\n\nvar_dump($result);\n~~~\n\nFetch the result of one or more reports:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBReports;\n\n$api = new API([/* … */]);\n$reports = new CMDBReports($api);\n\n$result = $reports-\u003ebatchRead([1, 2]);\n\nvar_dump($result);\n~~~\n\n### Fetch next free IP address from subnet\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\Subnet;\n\n$api = new API([/* … */]);\n\n$subnet = new Subnet($api);\n// Load subnet object by its identifier:\n$nextIP = $subnet-\u003eload(123)-\u003enext();\n\necho 'Next IP address: ' . $nextIP . PHP_EOL;\n~~~\n\n### Upload files\n\nThis API client library is able to upload a file, create a new \"File\" object an assigned it to an existing object identified by its ID:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\File;\n\n$api = new API([/* … */]);\n\n$file = new File($api);\n\n// Assign one file to object with identifier 100:\n$file-\u003eadd(100, '/path/to/file', 'my file');\n\n// Assign many files to this object:\n$file-\u003ebatchAdd(\n    100,\n    [\n        'file1.txt' =\u003e 'File 1',\n        'file2.txt' =\u003e 'File 2',\n        'file3.txt' =\u003e 'File 3'\n    ]\n);\n~~~\n\n### Upload images to a gallery\n\nEach object may have an image gallery provided by assigned category \"images\". This is the way to upload image files and assign them to an existing object:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\Image;\n\n$api = new API([/* … */]);\n\n$image = new Image($api);\n\n// Assign one image with a caption to object's gallery with identifier 100:\n$image-\u003eadd(100, '/path/to/flowers.jpg', 'nice picture of flowers');\n\n// Assign many images to this object:\n$file-\u003ebatchAdd(\n    100,\n    [\n        'file1.jpg' =\u003e 'JPEG file',\n        'file2.png' =\u003e 'PNG file',\n        'file3.bmp' =\u003e 'BMP file',\n        'file3.gif' =\u003e 'Animated GIF file'\n    ]\n);\n~~~\n\n### Self-defined request\n\nSometimes it is better to define a request on your own instead of using pre-defined methods provided by this API client library. Here is the way to perform a self-defined request:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\n\n$api = new API([/* … */]);\n\n$result = $api-\u003erequest('idoit.version');\n\nvar_dump($result);\n~~~\n\n`request()` takes the method and optional parameters.\n\n### Self-defined batch request\n\nSimilar to a simple requests you may perform a batch requests with many sub-requests as you need:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\n\n$api = new API([/* … */]);\n\n$result = $api-\u003ebatchRequest([\n    [\n        'method' =\u003e 'idoit.version'\n    ],\n    [\n       'method' =\u003e 'cmdb.object.read',\n       'params' =\u003e ['id' =\u003e 1]\n    ]\n]);\n\nvar_dump($result);\n~~~\n\n### Read information about your CMDB design\n\nFetch information about object types, object types per group, categories assigned to object types, and attributes available in categories:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\CMDBObjectTypes;\nuse Idoit\\APIClient\\CMDBObjectTypeGroups;\nuse Idoit\\APIClient\\CMDBObjectTypeCategories;\nuse Idoit\\APIClient\\CMDBCategoryInfo;\n\n$api = new API([/* … */]);\n\n// Object types:\n$objectTypes = new CMDBObjectTypes($api);\n$allObjectTypes = $objectTypes-\u003eread();\nvar_dump($allObjectTypes);\n$server = $objectTypes-\u003ereadOne('C__OBJTYPE__SERVER');\nvar_dump($server);\n$someObjectTypes = $objectTypes-\u003ebatchRead('C__OBJTYPE__SERVER', 'C__OBJTYPE__CLIENT');\nvar_dump($someObjectTypes);\n$client = $objectTypes-\u003ereadByTitle('LC__CMDB__OBJTYPE__CLIENT');\nvar_dump($client);\n\n// Object types per group:\n$objectTypesPerGroup = new CMDBObjectTypeGroups($api);\n$objectTypes = $objectTypesPerGroup-\u003eread();\nvar_dump($objectTypes);\n\n// Categories assigned to object types:\n$assignedCategory = new CMDBObjectTypeCategories($api);\n$serverCategories = $assignedCategory-\u003ereadByConst('C__OBJTYPE__SERVER');\nvar_dump($serverCategories);\n// Read by identifiers is also possible. And there are methods for batch requests.\n\n// Attributes available in categories:\n$categoryInfo = new CMDBCategoryInfo($api);\n$modelCategory = $categoryInfo-\u003eread('C__CATG__MODEL');\nvar_dump($modelCategory);\n$categories = $categoryInfo-\u003ebatchRead([\n    'C__CATG__MODEL',\n    'C__CATG__FORMFACTOR',\n    'C__CATS__PERSON_MASTER'\n]);\nvar_dump($categories);\n~~~\n\n### Read information about i-doit itself\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\Idoit;\n\n$api = new API([/* … */]);\n$idoit = new Idoit($api);\n\n$version = $idoit-\u003ereadVersion();\n$constants = $idoit-\u003ereadConstants();\n$addOns = $idoit-\u003egetAddOns();\n$license = $idoit-\u003egetLicense();\n\nvar_dump($version, $constants, $addOns, $license);\n~~~\n\n### Re-connect to server\n\nSometimes you need a fresh connection. You may explicitly disconnect from the i-doit server and re-connect to it:\n\n~~~ {.php}\nuse Idoit\\APIClient\\API;\n\n$api = new API([/* … */]);\n\n// Do your stuff…\n$api-\u003edisconnect();\n$api-\u003eisConnected(); // Returns false\n$api-\u003econnect();\n$api-\u003eisConnected(); // Returns true\n~~~\n\n### Debug API calls\n\nFor debugging purposes it is great to fetch some details about your API calls. This script uses some useful methods:\n\n~~~ {.php}\n#!/usr/bin/env php\n\u003c?php\n\nuse Idoit\\APIClient\\API;\nuse Idoit\\APIClient\\Idoit;\n\n$start = time();\n\nrequire_once 'vendor/autoload.php';\n\n$api = new API([/* … */]);\n\n// @todo Insert your code here, for example:\n$request = new Idoit($api);\n$request-\u003ereadVersion();\n\nfwrite(STDERR, 'Last request:' . PHP_EOL);\nfwrite(STDERR, '=============' . PHP_EOL);\nfwrite(STDERR, $api-\u003egetLastRequestHeaders() . PHP_EOL);\nfwrite(STDERR, json_encode($api-\u003egetLastRequestContent(), JSON_PRETTY_PRINT) . PHP_EOL);\nfwrite(STDERR, PHP_EOL);\nfwrite(STDERR, '--------------------------------------------------------------------------------' . PHP_EOL);\nfwrite(STDERR, 'Last response:' . PHP_EOL);\nfwrite(STDERR, '==============' . PHP_EOL);\nfwrite(STDERR, $api-\u003egetLastResponseHeaders() . PHP_EOL);\nfwrite(STDERR, json_encode($api-\u003egetLastResponse(), JSON_PRETTY_PRINT) . PHP_EOL);\nfwrite(STDERR, PHP_EOL);\nfwrite(STDERR, '--------------------------------------------------------------------------------' . PHP_EOL);\nfwrite(STDERR, 'Last connection:' . PHP_EOL);\nfwrite(STDERR, '================' . PHP_EOL);\n$info = $api-\u003egetLastInfo();\nunset($info['request_header']);\nforeach ($info as $key =\u003e $value) {\n    if (is_array($value)) {\n        $value = '…';\n    }\n    fwrite(STDERR, $key . ': ' . $value . PHP_EOL);\n}\nfwrite(STDERR, '--------------------------------------------------------------------------------' . PHP_EOL);\nfwrite(STDERR, 'Amount of requests: ' . $api-\u003ecountRequests() . PHP_EOL);\n$memoryUsage = memory_get_peak_usage(true);\nfwrite(STDERR, sprintf('Memory usage: %s bytes', $memoryUsage) . PHP_EOL);\n$duration = time() - $start;\nfwrite(STDERR, sprintf('Duration: %s seconds', $duration) . PHP_EOL);\n~~~\n\n## Contribute\n\nPlease, report any issues to [our issue tracker](https://github.com/i-doit/api-client-php/issues). Pull requests are very welcomed. If you like to get involved see file [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.\n\n## Projects using this API client library\n\n-   [i-doit CLI Tool](https://github.com/bheisig/i-doit-cli) – \"Access your CMDB on the command line interface\"\n-   [i-doit Check_MK 2 add-on](https://www.i-doit.com/en/i-doit/add-ons/check-mk-add-on-2/) – \"Share information between i-doit and Check_MK\"\n\nSend pull requests to add yours.\n\n## Copyright \u0026 License\n\nCopyright (C) 2022 [synetics GmbH](https://i-doit.com/)\n\nCopyright (C) 2016-2022 [Benjamin Heisig](https://benjamin.heisig.name/)\n\nLicensed under the [GNU Affero GPL version 3 or later (AGPLv3+)](https://gnu.org/licenses/agpl.html). This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi-doit%2Fapi-client-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fi-doit%2Fapi-client-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi-doit%2Fapi-client-php/lists"}