kontent-ai / delivery-sdk-php Goto Github PK
View Code? Open in Web Editor NEWKontent.ai Delivery SDK for PHP
Home Page: https://kontent.ai
License: MIT License
Kontent.ai Delivery SDK for PHP
Home Page: https://kontent.ai
License: MIT License
Input needed. Please leave a comment.
Add support for X-KC-Wait-For-Loading-New-Content header.
Similarly to other SDKs. Eg. TypeScript SDK
The goal is to add support for content components (non-reusable content).
From the SDKs point of view, the components behave the same as regular content items. However, they are supported only in the rich-text elements.
<object type="application/kenticocloud" data-type="component" data-codename="n55afed3a_b4a3_018a_8744_3b06301b1f88"></object>
The only difference is that the value of the data-type
attribute is not item
but component
. (There is no new endpoint for Content components in the Delivery API). The components are being sent as a part of the modular content (linked items) dictionary in the same format as the regular modular content.
Sample implementation: https://github.com/Kentico/delivery-sdk-net/pull/131/files
Make sure rich-text elements containing components get resolved in the same manner as standard content items.
Testing KC project: https://qa-deliver.global.ssl.fastly.net/ab44e0cc-9302-00c3-14ce-1362a118ad2f/items
Internal reference: DC-544
The SDK sends a version tracking header in the following form: X-KC-SDKID: packagist.org;kentico-kontent/delivery-sdk-php;0.9.1
with every request. This was implemented in #43
Currently, the tracking header is hardcoded in the DeliveryClient.php and needs to be updated with every release
The goal of this task is to find a way of updating this version automatically (using a pre/post build action) or loading it from the composer.json somehow (after packagist sets it up during release).
We are open to any other ideas! :-)
As new element type - Custom element - was added to Delivery output, it's needed to add its support to SDKs.
Actually, it's already added to .NET SDK and code generator
Custom element stores its value as simple string. The format of the string is free and determined by the developer who creates element.
In Delivery output custom element has type "custom"
It should be supported in generator as well.
The concrete solution depends on concrete SDK implementation.
Generally, you should add Custom Element into list of supported types with type name "custom" and data type "string".
Also you should add Custom element type into tests.
An example of Delivery output with Custom element
{
"item": {
"system": {
"id": "9acff635-2dc5-4402-ab10-72575d734020",
"name": "ColorPickerElement",
"codename": "colorpickerelement",
"language": "default",
"type": "colorpickertype",
"sitemap_locations": [],
"last_modified": "2019-01-22T09:39:39.3095575Z"
},
"elements": {
"colorpicker": {
"type": "custom",
"name": "ColorPicker",
"value": "#d7e119"
}
}
},
"modular_content": {}
}
https://getcomposer.org/doc/01-basic-usage.md#autoloading
plus, make sure the end-client usage is frictionless when using our documentation
@BryanSoltis may have some useful feedback on the process
Use phpDocumentor
Remaining:
Resources:
In coming weeks, the Delivery API will start supporting authenticated access.
In the first version of this feature, content will be secured using an API key. The developer will be able to turn the authenticated access on and off for the whole project. There will be one authentication key for the project, not multiple ones (for various user roles, for example).
Implement support for submitting the key in the form of the "Authorization" request header. The key should be sent via the Bearer scheme (with a "Bearer "
prefix).
We'll provide more information once they become available. https://kenticocloud.com/roadmap#secured-delivery-api
To improve response times Delivery API might provide stale content. Stale means that there is a more recent version, but it will become available later. This information is important for developers who implement caching because stale content should have a short TTL. Developers can inspect the value of the X-Stale-Content response header. 1 indicates that content is stale. If the header is not present or it has a different value, content is not stale.
Extend response models with information whether content is stale. For consistency it is recommended to use a has stale content bool property with the proper case type.
The taxonomy models should be hierarchical.
From February 1st, 2020 Delivery API will start enforcing rate limits to ensure fair usage by as many clients as possible. These rate limits should be high enough to work for most clients by default. However, in particular cases Delivery API might respond with 429 Too many requests
. These responses will also contain the Retry-After
header indicating how long the client should wait before making a follow-up request.
Implement a retry policy that handles 429 Too many requests
and retries the HTTP call using information from an optional Retry-After
header. It can contain a date after which to retry or the seconds to delay after the response is received. We recommend a retry policy with exponential backoff and a jitter strategy to overcome peaks of similar retries coming from many clients. The retry policy should handle the following status codes:
Please note that both 429 Too many requests
and 503 Service Unavailable
responses might contain an optional Retry-After
header.
Customer reported an issue in the Readme file saying:
The "The language selection is just a matter of specifying one additional filtering parameter to the query." was directly copied and pasted into the taxonomy section without changing.
There is a new endpoint for retrieving taxonomy groups:
Docu: https://developer.kenticocloud.com/v1/reference#list-taxonomy-groups
.NET SDK: kontent-ai/delivery-sdk-net#72
.TS SDK: kontent-ai/delivery-sdk-js#20
Java SDK: kontent-ai/java-packages#21
Use phpDocumentor to generate HTML API reference from php-style comments.
Resources:
README should contain:
The goals is to create some kind of interface or event that a developer can hook into to resolve the inline modular content in rich-text elements.
Similarly to:
DoD:
Similarly to: https://github.com/Kentico/personalization-sdk-net
Allow users to render paging navigation for a list of content items.
When the item listing request URL includes the includeTotalCount
query string parameter, the response contains the total number of content items matching the search criteria. As a result, the client needs only one API call to fetch all information necessary to display a list of content items and the paging navigation.
To return the total number of content items, the includeTotalCount
parameter must have value 1
or true
or no value at all.
The total number of content items is returned in the pagination section
of the response in the total_count
property. Please note that if the user does not ask for the total item count, this property is not present.
Add support for the includeTotalCount
parameter and also provide the total number of content items, if available. Also, please provide a warning in documentation comments that asking for the total number of content items might increase the response time and, therefore, users should use it only when they need it.
For a reference implementation please have a look at https://github.com/Kentico/kontent-delivery-sdk-net/blob/master/Kentico.Kontent.Delivery/QueryParameters/Parameters/IncludeTotalCountParameter.cs
https://developer.kenticocloud.com/reference#view-a-content-type-element
It'll help people, like me, who are new to installing php on Windows.
Add the location in php.ini to add the "zend_extension = ext\php_xdebug-2.7.0-7.3-vc15-nts-x86_64.dll" line
(https://github.com/Kentico/delivery-sdk-php/wiki/Developing-PHP-in-Visual-Studio-Code-for-Dummies)
The method is too complex. It should be possible to cut it to smaller pieces and make it more generic.
On the line 246 of ModelBinder.php, there is a following code:
foreach ($linksElements as $linkElement) {
$elementId = $linkElement->getAttribute('data-item-id');
if (array_key_exists($elementId, $elementLinksMetadata)) {
$contentLink = new ContentLink($elementId, $elementLinksMetadata[$elementId]);
$resolvedLink = $this->contentLinkUrlResolver->resolveLinkUrl($contentLink);
} else {
$resolvedLink = $this->contentLinkUrlResolver->resolveBrokenLinkUrl($contentLink);
}
$linkElement->href = $resolvedLink;
}
If you look closely on the only line inside else
branch, you will notice that it passes $contentLink
variable to resolveBrokenLinkUrl
method, but the variable is not defined.
Review the architecture of the original work.
Resources:
Documentation:
Add a capability of dealing with transient network outages via the following retry policy:
DeliveryOptions
class):
The goals is to create some kind of interface or event that a developer can hook into to resolve the hyperlinks in rich-text elements.
Similarly to:
DoD:
Listing taxonomy groups supports pagination. We need to reflect that in the SDK.
{
"taxonomies": [
{
"system": {
"id": "f30c7f72-e9ab-8832-2a57-62944a038809",
"name": "Personas",
"codename": "personas",
"last_modified": "2016-10-20T13:24:00.3200182Z"
},
"terms": [
{
"name": "Coffee expert",
"codename": "coffee_expert",
"terms": [
{
"name": "Barista",
"codename": "barista",
"terms": []
},
{
"name": "Cafe owner",
"codename": "cafe_owner",
"terms": []
}
]
},
{
"name": "Coffee enthusiast",
"codename": "coffee_enthusiast",
"terms": [
{
"name": "Coffee lover",
"codename": "coffee_lover",
"terms": []
},
{
"name": "Coffee blogger",
"codename": "coffee_blogger",
"terms": []
}
]
}
]
},
{
"system": {
"id": "d351400e-0290-87b2-1413-6c411d8ae5a4",
"name": "Processing type",
"codename": "processing_type",
"last_modified": "2017-09-04T12:50:20.7857817Z"
},
"terms": [
{
"name": "Wet (Washed)",
"codename": "wet__washed_",
"terms": []
},
{
"name": "Dry (Natural)",
"codename": "dry__natural_",
"terms": []
},
{
"name": "Semi-dry",
"codename": "semi_dry",
"terms": []
}
]
},
{
"system": {
"id": "79b1c5b6-30bc-d076-a236-d9ec9f1ff01b",
"name": "Product status",
"codename": "product_status",
"last_modified": "2016-09-15T10:53:25.2233101Z"
},
"terms": [
{
"name": "On sale",
"codename": "on_sale",
"terms": []
},
{
"name": "Bestseller",
"codename": "bestseller",
"terms": []
}
]
}
],
"pagination": {
"skip": 0,
"limit": 3,
"count": 3,
"next_page": ""
}
}
DoD:
How do we get items by type then filter e.g
getItems((new QueryParams())->type('A') ->equals('name', 'bob'));
Are they any examples ?
Thanks
Failing test: https://travis-ci.org/Kentico/delivery-sdk-php/builds/443073860
It's failing due to a removed content item in the sample project. The task is to find another content item that uses a multiple-choice element and adjust the test so that it uses new testing data.
The library's code's ok. Just the test is missing correct testing data.
I am working on updating Stephenr85's DG sample app to use current SDK version and I have discovered a possible issue in our SDK.
Steps to reproduce:
composer update
and then php artisan serve
The page will be loading for quite some time (approximately 2*t_max-execution_time + 1-2 seconds). After maximum execution time is reached, you will be able to see PHP Fatal error that preceeds the page finally loading:
Map the following:
adjust default mapper
Kentico Kontent now supports image optimization. It gives developers the option of transforming images using URL parameters. The goal of this task is to implement a helper class that will make generation of image URLs easy for the developers.
The reference code can be observed in the .NET SDK.
The full specification follows:
Scale
image.jpg?mode=scale&width=300
image.jpg?mode=scale&height=150
image.jpg?mode=fit&height=150&width=300
DPR
image.jpg?mode=scale&width=300&dpr=2.0
If a developer provides a parameter with invalid value or omits a parameter that is required for desired optimization, the Asset API will either ignore this parameter, or return the original asset without any optimizations.
Also, to keep our sanity, we will transform each image optimization parameter independently from others. Yes, this approach might sometimes produce surprising results. However, both Fastly and imgix are designed to handle a set of parameters that do not make sense and we are not making the situation worse.
Regarding requests to the Asset API, the idea is to go through all parameters, transform the supported ones and get rid of everything else.
To get a grasp of the image optimization You can experiment with two identical images:
- | - |
---|---|
x is not float | Nothing |
x < 0.0 | Nothing |
y is not float | Nothing |
y < 0.0 | Nothing |
w is not float | Nothing |
w <= 0.0 | Nothing |
h is not float | Nothing |
h <= 0.0 | Nothing |
h <= 0.0 | Nothing |
otherwise | crop={w},{h},x{x},y{y} |
If the rect
parameter is malformed, just ignore it.
- | - |
---|---|
x is not float | set x as 0.5 |
y is not float | set y as 0.5 |
z is not float | Nothing |
z <= 1.0 | Nothing |
1 / z < 1.0 | Nothing |
otherwise | crop={1 / z},{1 / z},offset-x{(x * z - 0.5) / (z - 1)},offset-y{(y * z - 0.5) / (z - 1) * 100} |
Both offset-x and offset-y must be clamped into range from 0 to 100.
imgix supports crop by both rectangle and focal point. Unfortunately, it is not so easy to calculate Fastly parameters. Therefore, let's declare the rect
parameter more important. So, if both crop by rectangle and focal point are specified, choose the first.
- | - |
---|---|
x = gif | format=gif |
x = png | format=png |
x = png8 | format=png8 |
x = jpg | format=jpg |
x = pjpg | format=pjpg |
x = webp | format=webp |
otherwise | Nothing |
- | - |
---|---|
x = 1 | format=webpll |
x = true | format=webpll |
x = 0 | format=webply |
x = false | format=webply |
otherwise | format=webp |
- | - |
---|---|
x is not float | Nothing |
otherwise | quality={x}\ |
- | - |
---|---|
x = format | auto=webp |
otherwise | Nothing |
Local variables and related functions will be required to transform parameters.
ModelBinder
Sample occurrences:
DoD:
Dependencies like typeMapper
, propertyMapper
, valueConverter
, *Factory
could be injected using DI. If we implemented DI, we could also have a default container and get rid of method such as getModelBinder
.
The goal of this task is to:
Resources:
Listing content types supports pagination. We need to reflect that in the SDK.
{
"types": [
{
"system": {
"id": "b2c14f2c-6467-460b-a70b-bca17972a33a",
"name": "About us",
"codename": "about_us",
"last_modified": "2017-08-02T07:33:28.2997578Z"
},
"elements": {
"facts": {
"type": "modular_content",
"name": "Facts"
},
"url_pattern": {
"type": "url_slug",
"name": "URL pattern"
}
}
},
{
"system": {
"id": "d9748663-f567-4c51-a922-c24a1d6b935a",
"name": "Accessory",
"codename": "accessory",
"last_modified": "2017-08-02T07:33:39.3620325Z"
},
"elements": {
"product_name": {
"type": "text",
"name": "Product name"
},
"price": {
"type": "number",
"name": "Price"
},
"image": {
"type": "asset",
"name": "Image"
},
"manufacturer": {
"type": "text",
"name": "Manufacturer"
},
"product_status": {
"type": "taxonomy",
"name": "Product status",
"taxonomy_group": "product_status"
},
"short_description": {
"type": "rich_text",
"name": "Short description"
},
"long_description": {
"type": "rich_text",
"name": "Long description"
},
"url_pattern": {
"type": "url_slug",
"name": "URL pattern"
}
}
},
{
"system": {
"id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89",
"name": "Article",
"codename": "article",
"last_modified": "2017-08-02T07:33:19.8599559Z"
},
"elements": {
"personas": {
"type": "taxonomy",
"name": "Personas",
"taxonomy_group": "personas"
},
"title": {
"type": "text",
"name": "Title"
},
"teaser_image": {
"type": "asset",
"name": "Teaser image"
},
"post_date": {
"type": "date_time",
"name": "Post date"
},
"summary": {
"type": "text",
"name": "Summary"
},
"body_copy": {
"type": "rich_text",
"name": "Body Copy"
},
"related_articles": {
"type": "modular_content",
"name": "Related articles"
},
"meta_keywords": {
"type": "text",
"name": "Meta keywords"
},
"meta_description": {
"type": "text",
"name": "Meta description"
},
"url_pattern": {
"type": "url_slug",
"name": "URL pattern"
}
}
}
],
"pagination": {
"skip": 0,
"limit": 3,
"count": 3,
"next_page": "https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/types?limit=3&skip=3"
}
}
DoD:
https://developer.kenticocloud.com/v1/reference#view-a-content-type
Inspiration / usage:
Based on our vision regarding content items, we have to rename "Modular content element" to "Linked items element". From the Delivery SDK's point of view, it means that we are going to rename everything that contains "modularContent" to "linkedItems".
Checklist:
Keep in mind, that the Delivery API responses will remain the same. They'll still contain "modular_content".
Example implementation: kontent-ai/delivery-sdk-net#130
Plan your release so that the changes go live on 2018-10-03 and onwards.
[DCN-2] Test JIRA Integration
Allow developers to fetch all content item variants from the new \items-feed
endpoint. This offers developers a way to export an entire project no matter the size.
The content is is provided in small chunks together with a continuation token for the next chunk. The continuation token is sent in X-Continuation
header both for request and response. Should the response from Delivery API contain the token, there are additional items to fetch. If the request does not contain the continuation header, Delivery API will return the first chunk.
Filtering parameters are same as for items
endpoint but paging and depth are not supported.
The response has also the similar structure to items
endpoint but paging object is missing and modular_content
contains only components.
Implementation details for consistency: (name casing should be adapted according to the rest of SDK)
Add a new method to DeliveryClient
with a name GetItemsFeed()
. The method should support the same filtering parameters as GetItems()
except for depth, skip and limit and return a content items variants feed.
The feed contains a bool property HasMoreResults
that is true if the first batch was not yet fetched or there are more items to fetch (indicated by a continuation header in the previous response). The feed also contains a method FetchNextBatch()
that would retrieve the next response from \items-feed
endpoint.
See .NET SDK for reference code
Modular content should be accessible both through generic content item type and through typed models:
DoD:
Motivation:
We'd like to start sending a header for identifying SDKs + their versions with each request from all SDKs. The header would be then tracked by App Insights and should provide us with information valuable for multiple departments in Kentico. App Insights already gather information about the user agent, but that is not always usable or present (there are some screenshots below).
In the future, the tracking should help us:
Specification:
Send the following header with each request to the Kentico Cloud Delivery API.
Examples:
X-KC-SDKID: nuget.org;KenticoCloud.Delivery;4.12.0
X-KC-SDKID: packagist.org;kentico-cloud/delivery-sdk-php;0.9.1
X-KC-SDKID: maven.org;com.kenticocloud:delivery-sdk-java;1.0.5
X-KC-SDKID: npmjs.com;kentico-cloud-delivery-typescript-sdk;2.2.2
It is not possible to pare the HTML in the Simple DOM HTML parser
It is caused by:
TODO:
sunra/php-simple-html-dom-parser
libraryA declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.