{"id":15296319,"url":"https://github.com/kontent-ai/delivery-sdk-php","last_synced_at":"2025-04-03T02:09:35.465Z","repository":{"id":23694893,"uuid":"98887429","full_name":"kontent-ai/delivery-sdk-php","owner":"kontent-ai","description":"Kontent.ai Delivery SDK for PHP","archived":false,"fork":false,"pushed_at":"2024-07-04T11:01:35.000Z","size":1545,"stargazers_count":46,"open_issues_count":13,"forks_count":15,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-24T06:50:27.562Z","etag":null,"topics":["composer","delivery-api","hacktoberfest","headless-cms","kontent-ai","kontent-ai-sample","packagist","php","php7"],"latest_commit_sha":null,"homepage":"https://kontent.ai","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kontent-ai.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-31T12:40:11.000Z","updated_at":"2024-07-04T11:01:04.000Z","dependencies_parsed_at":"2024-10-30T04:23:09.859Z","dependency_job_id":null,"html_url":"https://github.com/kontent-ai/delivery-sdk-php","commit_stats":{"total_commits":290,"total_committers":21,"mean_commits":13.80952380952381,"dds":0.5827586206896551,"last_synced_commit":"3ef9230f22404965f6a690f163513ce94102ce81"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fdelivery-sdk-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fdelivery-sdk-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fdelivery-sdk-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fdelivery-sdk-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kontent-ai","download_url":"https://codeload.github.com/kontent-ai/delivery-sdk-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246922247,"owners_count":20855345,"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":["composer","delivery-api","hacktoberfest","headless-cms","kontent-ai","kontent-ai-sample","packagist","php","php7"],"created_at":"2024-09-30T18:10:02.990Z","updated_at":"2025-04-03T02:09:35.444Z","avatar_url":"https://github.com/kontent-ai.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kontent.ai Delivery SDK for PHP\n\n[![Build \u0026 Test \u0026 Report](https://github.com/kontent-ai/delivery-sdk-php/actions/workflows/integrate.yml/badge.svg)](https://github.com/kontent-ai/delivery-sdk-php/actions/workflows/integrate.yml)\n[![Packagist](https://img.shields.io/packagist/v/kontent-ai/delivery-sdk-php.svg)](https://packagist.org/packages/kontent-ai/delivery-sdk-php)\n[![codecov](https://codecov.io/gh/kontent-ai/delivery-sdk-php/branch/master/graph/badge.svg)](https://codecov.io/gh/kontent-ai/delivery-sdk-php)\n[![Stack Overflow](https://img.shields.io/badge/Stack%20Overflow-ASK%20NOW-FE7A16.svg?logo=stackoverflow\u0026logoColor=white)](https://stackoverflow.com/tags/kontent-ai)\n[![Discord](https://img.shields.io/discord/821885171984891914?color=%237289DA\u0026label=Kontent.ai%20Discord\u0026logo=discord)](https://discord.gg/SKCxwPtevJ)\n\n## Summary\n\nThe Kontent.ai Delivery PHP SDK is a client library used for retrieving content from Kontent.ai. The best way to use the SDK is to consume it in the form of a [Packagist package](https://packagist.org/packages/kontent-ai/delivery-sdk-php). The library currently supports only PHP 8 and above.\n\n## Sample site\n\nCheck out a sample site running on Laravel utilizing this SDK here: [https://github.com/kontent-ai/sample-app-php](https://github.com/kontent-ai/sample-app-php)\n\n## Installation\n\nThe best way to install the client is through a dependency manager called [Composer](https://getcomposer.org/):\n\n```sh\ncomposer require kontent-ai/delivery-sdk-php\n```\n\nor adjusting your `composer.json` file:\n\n```sh\n{\n    \"require\": {\n        \"kontent-ai/delivery-sdk-php\": \"^6.0.0\"\n    }\n}\n```\n\n### Autoloading\n\nWriting object-oriented applications requires one PHP source file per class definition. One of the biggest annoyances is having to write a long list of needed includes at the beginning of each script (one for each class).\n\nSince the SDK uses [Composer](https://getcomposer.org/) dependency manager and specifies autoload information, Composer generates a [vendor/autoload.php](https://getcomposer.org/doc/01-basic-usage.md#autoloading) file. You can simply include this file and start using the namespaces that those libraries offer without any extra work:\n\n```sh\nrequire __DIR__ . '/vendor/autoload.php';\n```\n  \n## Using the DeliveryClient\n\nThe `DeliveryClient` class is the main class of the SDK. Using this class, you can retrieve content from your Kontent.ai projects.\n\nTo create an instance of the class, you need to provide a [project ID](https://kontent.ai/learn/tutorials/develop-apps/get-content/get-content-items#a-1-find-your-project-id).\n\n```php\nuse Kontent\\Ai\\Delivery\\DeliveryClient;\n\n// Initializes an instance of the DeliveryClient client\n$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');\n```\n\nThere are some other optional parameters that you can use during the `DeliveryClient` instantiation.\n\n* `$previewApiKey` – sets the Delivery Preview API key. The client will automatically start using the preview endpoint for querying. See [previewing unpublished content](#previewing-unpublished-content).\n* `$securedProductionApiKey` – sets the production Delivery API key (do not combine it with the Delivery Preview API key)\n* `$waitForLoadingNewContent` – makes the client instance wait while fetching updated content, useful when acting upon [webhook calls](https://kontent.ai/learn/tutorials/develop-apps/integrate/webhooks#a-get-the-latest-content).\n* `$debugRequests` – switches the HTTP client to debug mode\n* `$retryAttempts` – number of times the client will retry to connect to the Kontent.ai API on failures per request\n\nOnce you create a `DeliveryClient`, you can start querying your project repository by calling methods on the client instance. See [Basic querying](#basic-querying) for details.\n\n## Basic querying\n\nOnce you have a `DeliveryClient` instance, you can start querying your project repository by calling methods on the instance.\n\n```php\n// Retrieves a single content item\n$item = $client-\u003egetItem('about_us');\n\n// Retrieves a list of all content items\n$items = $client-\u003egetItems();\n```\n\n### Filtering retrieved data\n\nThe SDK supports full scale of the API querying and filtering capabilities as described in the [API reference](https://kontent.ai/learn/reference/delivery-api#tag/Filtering-content).\n\n```php\nuse Kontent\\Ai\\Delivery\\QueryParams;\n\n// Retrieves a list of the specified elements from the first 10 content items of\n// the 'brewer' content type, ordered by the 'product_name' element value\n$response = $client-\u003egetItems((new QueryParams())\n  -\u003eequals('system.type', 'brewer')\n  -\u003eelements(array('image', 'price', 'product_status','processing'))\n  -\u003elimit(10)\n  -\u003eorderAsc('elements.product_name'));\n```\n\n### Getting localized items\n\nThe language selection is just a matter of specifying one additional filtering parameter to the query.\n\n```php\nuse Kontent\\Ai\\Delivery\\QueryParams;\n\n// Retrieves a list of the specified elements from the first 10 content items of\n// the 'brewer' content type, ordered by the 'product_name' element value\n$response = $client-\u003egetItems((new QueryParams())\n  -\u003elanguage('es-ES')\n  -\u003eequals('system.type', 'brewer')\n  -\u003eelements(array('image', 'price', 'product_status','processing'))\n  -\u003elimit(10)\n  -\u003eorderAsc('elements.product_name'));\n```\n\n### Working with taxonomies\n\nTo retrieve information about your taxonomies, you can use the `getTaxonomy` and `getTaxonomies` methods. Additionally, you can specify query [parameters](https://kontent.ai/learn/reference/delivery-api#operation/list-taxonomy-groups).\n\n```php\nuse Kontent\\Ai\\Delivery\\QueryParams;\n\n// Retrieves a list of the specified taxonomy groups.\n$response = $client-\u003egetTaxonomies((new QueryParams())\n  -\u003elimit(3);\n\n// Retrieves a specific taxonomy group.\n$response = $client-\u003egetTaxonomy('persona');\n```\n\n## Previewing unpublished content\n\nTo retrieve unpublished content, you need to create a `DeliveryClient` with both Project ID and Preview API key. Each Kontent.ai project has its own Preview API key.\n\n```php\n// Note: Within a single project, we recommend that you work with only\n// either the production or preview Delivery API, not both.\n$client = new DeliveryClient('YOUR_PROJECT_ID', 'YOUR_PREVIEW_API_KEY');\n```\n\nFor more details, see [Previewing unpublished content using the Delivery API](https://kontent.ai/learn/tutorials/develop-apps/build-strong-foundation/set-up-preview#a-get-the-latest-version-of-everything).\n\n## Response structure\n\nFor full description of single and multiple content item JSON response formats, see our [API reference](https://kontent.ai/learn/reference/delivery-api#operation/list-content-items).\n\n### Single content item response\n\nWhen retrieving a single content item, you get an instance of the `ContentItem` class. This class contains a 'system' property (with metadata about the content item, such as code name, display name, type, collection, or sitemap location) and respective content item's elements projected as [camelCase](https://en.wikipedia.org/wiki/Camel_case) properties.\n\n![Single item](./assets/single-item-response.png)\n\n### Multiple content items response\n\nWhen retrieving a list of content items, you get an instance of the `ContentItemsResponse`. This class represents the JSON response from the Delivery API endpoint and contains:\n\n* `Pagination` property with information about the following:\n  * `Skip`: requested number of content items to skip\n  * `Limit`: requested page size\n  * `Count`: the total number of retrieved content items\n  * `NextPageUrl`: the URL of the next page\n* An array of the requested [content items](#single-content-item-response)\n\n### Properties and their types\n\n* All properties are named in the [camelCase](https://en.wikipedia.org/wiki/Camel_case) style.\n* If a property contains a collection of objects, it's typed as an array which is indexed by:\n  * codenames, if the contained entities have a code name\n  * numbers, if they don't have code names. We use zero-based indexing.\n* If a property references linked items (property is of the linked item type), the references are replaced with the respective [content items](#single-content-item-response) themselves.\n* If a property is of asset, multiple choice option, or taxonomy group type, it's resolved to respective well-known models from the `Kontent\\Ai\\Delivery\\Models\\Items` namespace.\n* All timestamps are typed as `\\DateTime`.\n* All numbers are typed as `float`.\n\n### Mapping custom models\n\nIt's possible to instruct the SDK to fill and return your own predefined models. To do that you have to implement:\n\n* `TypeMapperInterface` (required) - to provide mapping of Kontent.ai content types to your models\n* `PropertyMapperInterface` (optional) - to change the default behavior of property mapping (the default property translation works like this: 'content_type' -\u003e 'contentType')\n* `ValueConverterInterface` (optional) - to change the way content element types are mapped to PHP types\n* `ContentLinkUrlResolverInterface` (optional) - to change the way the links in Rich text elements are resolved see [Resolving links to content items](./wiki/Resolving-links-to-content-items.md).\n* `InlineLinkedItemsResolverInterface` (optional) - to change the way content items in Rich text elements are resolved see [Resolving content items and components in Rich text](./wiki/Resolving-content-items-and-components-in-Rich-text.md).\n\nThe default implementation of all the interfaces can be found in a class called [`DefaultMapper`](./src/Kontent/Ai/Delivery/DefaultMapper.php).\n\nExample:\n\n```php\nclass TetsMapper extends DefaultMapper\n{\n    public function getTypeClass($typeName)\n    {\n        switch ($typeName) {\n            case 'home':\n                return \\Kontent\\Ai\\Tests\\E2E\\HomeModel::class;\n            case 'article':\n                return \\Kontent\\Ai\\Tests\\E2E\\ArticleModel::class;\n        }\n\n        return parent::getTypeClass($typeName);\n    }\n}\n...\n\npublic function testMethod()\n{\n    $client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');\n    $client-\u003etypeMapper = new TetsMapper();\n    $item = $client-\u003egetItem('on_roasts');\n    $this-\u003eassertInstanceOf(\\Kontent\\Ai\\Tests\\E2E\\ArticleModel::class, $item); // Passes\n}\n\n```\n\nThe `ArticleModel` can then look like this (and contain only the properties you need to work with):\n\n```php\nclass ArticleModel\n{\n    public $system = null;\n    public $title = null;\n    public $urlPattern = null;\n}\n```\n\n## Feedback \u0026 Contributing\n\nCheck out the [contributing](./CONTRIBUTING.md) page to see the best places to file issues, start discussions, and begin contributing.\n\n1. Clone the repository\n2. Run `composer install` to install dependencies\n3. Run `phpunit` to verify that everything works as expected\n\n### Developing on Windows\n\nHave a look at our cool [tutorial](./wiki/Developing-PHP-in-Visual-Studio-Code-for-Dummies.md) on developing PHP on Windows with Visual Studio Code!\n\n### Developing on Linux\n\nDo you prefer penguins? Check out our [tutorials](./wiki/Configuring-PHP-Storm-on-Linux.md) on developing PHP on Linux with PhpStorm!\n\n### Wall of Fame\n\nWe would like to express our thanks to the following people who contributed and made the project possible:\n\n* [Stephen Rushing](https://github.com/stephenr85/) - [eSiteful](http://www.esiteful.com/home) - [ORIGINAL WORK](https://github.com/stephenr85/KenticoCloud.Deliver.PHP)\n\nWould you like to become a hero too? Pick an [issue](https://github.com/kontent-ai/delivery-sdk-php/issues) and send us a pull request!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fdelivery-sdk-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkontent-ai%2Fdelivery-sdk-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fdelivery-sdk-php/lists"}