{"id":13579303,"url":"https://github.com/mautic/api-library","last_synced_at":"2025-05-14T16:12:23.946Z","repository":{"id":25879604,"uuid":"29319882","full_name":"mautic/api-library","owner":"mautic","description":"Mautic API Library","archived":false,"fork":false,"pushed_at":"2025-04-15T15:37:45.000Z","size":1143,"stargazers_count":187,"open_issues_count":51,"forks_count":127,"subscribers_count":39,"default_branch":"main","last_synced_at":"2025-04-29T23:35:27.888Z","etag":null,"topics":["hacktoberfest","mautic","mautic-api","php","php-library"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"nest/nest-simulator","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mautic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-01-15T21:48:57.000Z","updated_at":"2025-04-17T10:59:18.000Z","dependencies_parsed_at":"2025-04-22T02:23:19.795Z","dependency_job_id":"9caaf39d-b67b-4a75-9f53-cd475c9d114c","html_url":"https://github.com/mautic/api-library","commit_stats":{"total_commits":523,"total_committers":49,"mean_commits":"10.673469387755102","dds":0.6692160611854685,"last_synced_commit":"ca46933ff2c3e66bb840bb6666f962fda93e36ab"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mautic%2Fapi-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mautic%2Fapi-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mautic%2Fapi-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mautic%2Fapi-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mautic","download_url":"https://codeload.github.com/mautic/api-library/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253292163,"owners_count":21885040,"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":["hacktoberfest","mautic","mautic-api","php","php-library"],"created_at":"2024-08-01T15:01:38.210Z","updated_at":"2025-05-14T16:12:23.908Z","avatar_url":"https://github.com/mautic.png","language":"PHP","funding_links":[],"categories":["PHP","Official Repositories"],"sub_categories":[],"readme":"[![codecov](https://codecov.io/gh/mautic/api-library/branch/master/graph/badge.svg)](https://codecov.io/gh/mautic/api-library) [![Latest Stable Version](https://poser.pugx.org/mautic/api-library/v)](//packagist.org/packages/mautic/api-library) [![Total Downloads](https://poser.pugx.org/mautic/api-library/downloads)](//packagist.org/packages/mautic/api-library) [![Latest Unstable Version](https://poser.pugx.org/mautic/api-library/v/unstable)](//packagist.org/packages/mautic/api-library) [![License](https://poser.pugx.org/mautic/api-library/license)](//packagist.org/packages/mautic/api-library)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\n# Using the Mautic API Library\n\n## Requirements\n* PHP 8.0 or newer\n\n## Installing the API Library\nYou can install the API Library with the following command:\n\n```bash\ncomposer require mautic/api-library\n```\n\nN.B. Make sure you have installed a PSR-18 HTTP Client before you install this package or install one at the same time e.g. `composer require mautic/api-library guzzlehttp/guzzle:^7.3`.\n\n### HTTP Client\n\nWe are decoupled from any HTTP messaging client with the help of [PSR-18 HTTP Client](https://www.php-fig.org/psr/psr-18/). This requires an extra package providing [psr/http-client-implementation](https://packagist.org/providers/psr/http-client-implementation). To use Guzzle 7, for example, simply require `guzzlehttp/guzzle`:\n\n``` bash\ncomposer require guzzlehttp/guzzle:^7.3\n```\n\nThe installed HTTP Client is auto-discovered using [php-http/discovery](https://packagist.org/providers/php-http/discovery), but you can also provide your own HTTP Client if you like.\n\n```php\n\u003c?php\n\n// Bootup the Composer autoloader\ninclude __DIR__ . '/vendor/autoload.php';  \n\nuse GuzzleHttp\\Client;\nuse Mautic\\Auth\\ApiAuth;\n\n// Initiate an HTTP Client\n$httpClient = new Client([\n    'timeout'  =\u003e 10,\n]);\n\n// Initiate the auth object\n$initAuth = new ApiAuth($httpClient);\n$auth     = $initAuth-\u003enewAuth($settings);\n// etc.\n```\n\n## Mautic Setup\nThe API must be enabled in Mautic. Within Mautic, go to the Configuration page (located in the Settings menu) and under API Settings enable\nMautic's API. If you intend to use Basic Authentication, ensure you enable it. You can also choose which OAuth protocol to use here.  After saving the configuration, go to the API Credentials page (located in the Settings menu) and create a new client.  Enter the callback/redirect URI that the request will be sent from.  Click Apply, then copy the Client ID and Client Secret to the application that will be using the API.\n\n## Authorization\n\n### Obtaining an access token\nThe first step is to obtain authorization.  Mautic supports OAuth 1.0a and OAuth 2, however it is up to the administrator\nto decide which is enabled.  Thus it is best to have a configuration option within your project for the administrator\nto choose what method should be used by your code.\n\n```php\n\u003c?php\n\n// Bootup the Composer autoloader\ninclude __DIR__ . '/vendor/autoload.php';  \n\nuse Mautic\\Auth\\ApiAuth;\n\nsession_start();\n\n$publicKey = '';\n$secretKey = '';\n$callback  = '';\n\n// ApiAuth-\u003enewAuth() will accept an array of Auth settings\n$settings = [\n    'baseUrl'          =\u003e '',       // Base URL of the Mautic instance\n    'version'          =\u003e 'OAuth2', // Version of the OAuth can be OAuth2 or OAuth1a. OAuth2 is the default value.\n    'clientKey'        =\u003e '',       // Client/Consumer key from Mautic\n    'clientSecret'     =\u003e '',       // Client/Consumer secret key from Mautic\n    'callback'         =\u003e '',       // Redirect URI/Callback URI for this script\n];\n\n/*\n// If you already have the access token, et al, pass them in as well to prevent the need for reauthorization\n$settings['accessToken']        = $accessToken;\n$settings['accessTokenSecret']  = $accessTokenSecret; //for OAuth1.0a\n$settings['accessTokenExpires'] = $accessTokenExpires; //UNIX timestamp\n$settings['refreshToken']       = $refreshToken;\n*/\n\n// Initiate the auth object\n$initAuth = new ApiAuth();\n$auth     = $initAuth-\u003enewAuth($settings);\n\n// Initiate process for obtaining an access token; this will redirect the user to the $authorizationUrl and/or\n// set the access_tokens when the user is redirected back after granting authorization\n\n// If the access token is expired, and a refresh token is set above, then a new access token will be requested\n\ntry {\n    if ($auth-\u003evalidateAccessToken()) {\n\n        // Obtain the access token returned; call accessTokenUpdated() to catch if the token was updated via a\n        // refresh token\n\n        // $accessTokenData will have the following keys:\n        // For OAuth1.0a: access_token, access_token_secret, expires\n        // For OAuth2: access_token, expires, token_type, refresh_token\n\n        if ($auth-\u003eaccessTokenUpdated()) {\n            $accessTokenData = $auth-\u003egetAccessTokenData();\n\n            //store access token data however you want\n        }\n    }\n} catch (Exception $e) {\n    // Do Error handling\n}\n```\n\n### Using Basic Authentication Instead\nInstead of messing around with OAuth, you may simply elect to use BasicAuth instead.\n\nHere is the BasicAuth version of the code above.\n\n```php\n\u003c?php\n\n// Bootup the Composer autoloader\ninclude __DIR__ . '/vendor/autoload.php';  \n\nuse Mautic\\Auth\\ApiAuth;\n\nsession_start();\n\n// ApiAuth-\u003enewAuth() will accept an array of Auth settings\n$settings = [\n    'userName'   =\u003e '',             // Create a new user       \n    'password'   =\u003e '',             // Make it a secure password\n];\n\n// Initiate the auth object specifying to use BasicAuth\n$initAuth = new ApiAuth();\n$auth     = $initAuth-\u003enewAuth($settings, 'BasicAuth');\n\n// Nothing else to do ... It's ready to use.\n// Just pass the auth object to the API context you are creating.\n```\n\n**Note:** If the credentials are incorrect an error response will be returned.\n\n```php\n [\n    'errors' =\u003e [\n        [\n            'code'    =\u003e 403,\n            'message' =\u003e 'access_denied: OAuth2 authentication required',\n            'type'    =\u003e 'access_denied',\n        ],\n    ],\n ];\n\n```\n\n## API Requests\nNow that you have an access token and the auth object, you can make API requests.  The API is broken down into contexts.\n\n### Get a context object\n\n```php\n\u003c?php\n\nuse Mautic\\MauticApi;\n\n// Create an api context by passing in the desired context (Contacts, Forms, Pages, etc), the $auth object from above\n// and the base URL to the Mautic server (i.e. http://my-mautic-server.com/api/)\n\n$api        = new MauticApi();\n$contactApi = $api-\u003enewApi('contacts', $auth, $apiUrl);\n```\n\nSupported contexts are currently:\n\nSee the [developer documentation](https://developer.mautic.org).\n\n### Retrieving items\nAll of the above contexts support the following functions for retrieving items:\n\n```php\n\u003c?php\n\n$response = $contactApi-\u003eget($id);\n$contact  = $response[$contactApi-\u003eitemName()];\n\n// getList accepts optional parameters for filtering, limiting, and ordering\n$response      = $contactApi-\u003egetList($filter, $start, $limit, $orderBy, $orderByDir);\n$totalContacts = $response['total'];\n$contact       = $response[$contactApi-\u003elistName()];\n```\n\n### Creating an item\n\n```php\n\u003c?php\n\n$fields = $contactApi-\u003egetFieldList();\n\n$data = array();\n\nforeach ($fields as $field) {\n    $data[$field['alias']] = $_POST[$field['alias']];\n}\n\n// Set the IP address the contact originated from if it is different than that of the server making the request\n$data['ipAddress'] = $ipAddress;\n\n// Create the contact\n$response = $contactApi-\u003ecreate($data);\n$contact  = $response[$contactApi-\u003eitemName()];\n```\n\n### Editing an item\n\n\n```php\n\u003c?php\n\n$updatedData = [\n    'firstname' =\u003e 'Updated Name'\n];\n\n$response = $contactApi-\u003eedit($contactId, $updatedData);\n$contact  = $response[$contactApi-\u003eitemName()];\n\n// If you want to create a new contact in the case that $contactId no longer exists\n// $response will be populated with the new contact item\n$response = $contactApi-\u003eedit($contactId, $updatedData, true);\n$contact  = $response[$contactApi-\u003eitemName()];\n```\n\n### Deleting an item\n\n```php\n\u003c?php\n\n$response = $contactApi-\u003edelete($contactId);\n$contact  = $response[$contactApi-\u003eitemName()];\n```\n\n### Error handling\n\n```php\n\u003c?php\n\n// $response returned by an API call should be checked for errors\n$response = $contactApi-\u003edelete($contactId);\n\nif (isset($response['errors'])) {\n    foreach ($response['errors'] as $error) {\n        echo $error['code'] . \": \" . $error['message'];\n    }\n}\n```\n\n## Contributing\n\n### Setting up your environment (automatically)\nIn order to get started quickly, we recommend that you use [DDEV](https://ddev.readthedocs.io/en/stable/) which sets things up automatically for you. It clones [https://github.com/mautic/mautic](mautic/mautic), sets up a local instance for you, and connects the API library tests to that instance.\n\nTo get started, run `ddev start`! Our first-run experience will guide you through the setup.\n\n### Setting up your environment (manually)\nIf you want to set up your local environment manually, ensure that you copy `/tests/local.config.php.dist` to `/tests/local.config.php`, and fill in the required settings. We recommend using the Basic Authentication method to get up and running quickly.\n\n### Unit tests\n\nConfigure the unit tests config before running the unit tests. The tests fire real API requests to a Mautic instance. \n\n1. Ensure you have set up your local environment using the steps above.\n2. Run `composer test` to run the tests.\n\nModify this command to run a specific test: `composer test -- --filter testCreateGetAndDelete tests/Api/NotesTest.php`\n\nModify this command to run all tests in one class: `composer test -- --filter test tests/Api/NotesTest.php`\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://webmecanik.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/462477?v=4?s=100\" width=\"100px;\" alt=\"Zdeno Kuzmany\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eZdeno Kuzmany\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/mautic/api-library/commits?author=kuzmany\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/dlopez-akalam\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/6641589?v=4?s=100\" width=\"100px;\" alt=\"dlopez-akalam\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003edlopez-akalam\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/mautic/api-library/commits?author=dlopez-akalam\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/mollux\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/3983285?v=4?s=100\" width=\"100px;\" alt=\"mollux\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003emollux\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/mautic/api-library/commits?author=mollux\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/LadySolveig\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/64533137?v=4?s=100\" width=\"100px;\" alt=\"Martina  Scholz\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMartina  Scholz\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/mautic/api-library/commits?author=LadySolveig\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://johnlinhart.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1235442?v=4?s=100\" width=\"100px;\" alt=\"John Linhart\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJohn Linhart\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/mautic/api-library/pulls?q=is%3Apr+reviewed-by%3Aescopecz\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/Rocksheep\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1311371?v=4?s=100\" width=\"100px;\" alt=\"Marinus van Velzen\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMarinus van Velzen\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/mautic/api-library/commits?author=Rocksheep\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://pierre.ammeloot.fr\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/4603318?v=4?s=100\" width=\"100px;\" alt=\"Pierre Ammeloot\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ePierre Ammeloot\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#userTesting-PierreAmmeloot\" title=\"User Testing\"\u003e📓\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://matbcvo.github.io\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1006437?v=4?s=100\" width=\"100px;\" alt=\"Martin Vooremäe\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMartin Vooremäe\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/mautic/api-library/commits?author=matbcvo\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/mautic/api-library/commits?author=matbcvo\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmautic%2Fapi-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmautic%2Fapi-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmautic%2Fapi-library/lists"}