From 017f912846c044d965a57e42930c91a95c9f1583 Mon Sep 17 00:00:00 2001 From: Davide Borsatto Date: Thu, 8 Nov 2018 12:04:27 +0100 Subject: [PATCH] chore(release): Prepare version 4.0.0 --- CHANGELOG.md | 2 +- README.md | 67 ++++++++++++++++++++++++++++------------------------ 2 files changed, 37 insertions(+), 32 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 784db495..6c8dbe25 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). -## [Unreleased](https://github.com/contentful/contentful.php/compare/3.4.0...HEAD) +## [4.0.0](https://github.com/contentful/contentful.php/tree/4.0.0) (2018-11-08) **ATTENTION**: This release contains breaking changes. Please take extra care when updating to this version. See [the upgrade guide](UPGRADE-4.0.md) for more. diff --git a/README.md b/README.md index f59c7e25..6feedef7 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ ![PHP](.github/header-php.png) + +

Join Contentful Community Slack @@ -38,8 +40,6 @@

-> Attention! Version 3 of this package supports PHP 5.6, but starting from version 4, PHP 7 will be required. - > PHP SDK for the Contentful [Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/) and [Content Preview API](https://www.contentful.com/developers/docs/references/content-preview-api/). It helps you to easily access your Content stored in Contentful with your PHP applications. ## What is Contentful? @@ -81,7 +81,7 @@ ## Getting started -In order to get started with the Contentful PHP SDK you'll need not only to install it, but also to get credentials which will allow you to have access to your content in Contentful. +In order to get started with the Contentful PHP SDK you'll need not only to install it, but also to get credentials which will allow you to have access to your content in Contentful. This package requires PHP 7.0 or higher. ### Installation @@ -114,12 +114,9 @@ try { This SDK can also be used with the Preview API. In order to do so, you need to use the Preview API access token, available on the same page where you get the Delivery API token, and tell the client to use the different API: ``` php -$client = new \Contentful\Delivery\Client( - 'b4c0n73n7fu1', - 'cfexampleapi', - 'master', - true // Set this to true to use the Preview API -); +$options = \Contentful\Delivery\ClientOptions::create() + ->usingPreviewApi(); +$client = new \Contentful\Delivery\Client($accessToken, $spaceId, $environmentId, $options); ``` You can find all available methods of our client in our [reference documentation](https://contentful.github.io/contentful.php). @@ -144,37 +141,43 @@ For more information, check the [Contentful REST API reference on Authentication ### Configuration -The client constructor supports several options you may set to achieve the expected behavior: +The `ClientOptions` class allows you to configure the client in a variety of different ways: ``` php +$options = \Contentful\Delivery\ClientOptions::create() + ->usingPreviewApi() + ->withDefaultLocale(string $defaultLocale = null) + ->withHost(string $host) + ->withLogger(Psr\Log\LoggerInterface $logger) + ->withCache(Psr\Cache\CacheItemPoolInterface $cache, bool $autoWarmup = false, bool $cacheContent = false) + ->withHttpClient(GuzzleHttp\Client $client) +; + $client = new \Contentful\Delivery\Client( - $accessToken, - $spaceId, - $environmentId = 'master', - $usePreview = false, - $defaultLocale = null, - $options = [ - 'baseUri' => $baseUri = null, - 'guzzle' => $guzzle = null, - 'logger' => $logger = null, - 'cache' => $cache = null, - 'autoWarmup' => $autoWarmup = false, - ] + string $accessToken, + string $spaceId, + string $environmentId = 'master', + ClientOptions $options = null ); ``` -| Name | Default | Description | +| Client parameter | Default | Description | | ---------------- | ---------- | ----------- | | `$accessToken` | | **Required**. Your access token | | `$spaceId` | | **Required**. Your space ID | | `$environmentId` | `'master'` | Your environment ID | -| `$usePreview` | `false` | Set to true to use the Preview API instead of the default Delivery API | -| `$defaultLocale` | `null` | Set a locale to be automatically used for all requests | -| `$baseUri` | `null` | A string to override the default Contentful API URL (`https://cdn.contentful.com` for Delivery API, and `https://preview.contentful.com` for Preview API) | -| `$guzzle` | `null` | A custom instance of a `GuzzleHttp\Client` object | -| `$logger` | `null` | A PSR-3 logger which implements `Psr\Log\LoggerInterface` | -| `$cache` | `null` | A PSR-6 cache item pool which implements `Psr\Cache\CacheItemPoolInterface` | -| `$autoWarmup` | `false` | When using a cache pool, set this to true to automatically fill the cache during regular use | +| `$options` | `null` | A `ClientOptions` object | + +| ClientOptions method | Parameters | Description | +| -------------------- | ---------- | ----------- | +| `usingPreviewApi()` | - | Use the Preview API host (`preview.contentful.com`) | +| `withDefaultLocale()` | `string $locale` | Set a locale to be automatically used for all requests | +| `withHost()` | `string $host` | A string to override the default Contentful API URL, useful if you have a proxy between your application and the Contentful API | +| `withLogger()` | `Psr\Log\LoggerInterface $logger` | A PSR-3 logger. Two types of logs are written: a generic one using either the `INFO` or `ERROR` level (depending on the response status code) with a brief summary, and a complete dump of request and response using the `DEBUG` level. We suggest to configure the logger minimum level according to your needs. | +| `withCache()` | `Psr\Cache\CacheItemPoolInterface $cache` | A PSR-6 cache item pool. This will be used to stored data such as content types and locales, which are always needed but don't change often | +| `withCache()` | `bool $autoWarmup = false` | When using a cache pool, set this to true to automatically fill the cache during regular use | +| `withCache()` | `bool $cacheContent = false` | When using a cache pool with `$autoWarmup` set to true, se this to true to fill the cache with entries and assets during runtime. This may speed up execution when calling `$client->getEntry($entryId)` and `$client->getAsset($assetId)`, but *not* when calling the `getEntries()` and `getAssets()` methods, as the client can't reliably know which entries or assets will be returned by the API, and for this reason the cache can't intercept the call. | +| `withHttpClient()` | `GuzzleHttp\Client $client` | A Guzzle client instance, which can be configured with custom middleware | ### Reference documentation @@ -189,7 +192,9 @@ Most methods also have examples which show you how to use them. ### Upgrade -For details about how to upgrade from version 2.x to version 3, please check the [upgrade guide](UPGRADE-3.0.md). +For details about how to upgrade from version 3.x to version 4, please check the [changelog entry for version 4.0.0](CHANGELOG.md#400-2018-11-08) and the [upgrade to version 4 guide](UPGRADE-4.0.md). + +For details about how to upgrade from version 2.x to version 3, please check the [changelog entry for version 3.0.0](CHANGELOG.md#300-2018-04-16) and the [upgrade to version 3 guide](UPGRADE-3.0.md). ## Reach out to us