[BREAKING] Code refactoring

.php-cs-fixer.dist.php

@@ -3,7 +3,7 @@
 declare(strict_types=1);
 
 /*
- * This file is part of the Laravel-Strapi helper.
+ * This file is part of the Laravel-Strapi wrapper.
  *
  * (ɔ) Dave Blakey https://github.com/dbfx
  *
@@ -18,7 +18,7 @@
 use PhpCsFixer\RuleSet;
 
 $header = <<<'EOF'
-    This file is part of the Laravel-Strapi helper.
+    This file is part of the Laravel-Strapi wrapper.
 
     (ɔ) Dave Blakey https://github.com/dbfx
 
@@ -39,8 +39,8 @@
     ->setRiskyAllowed(true)
     ->setRules([
         // https://mlocati.github.io/php-cs-fixer-configurator
-        '@PHP74Migration:risky' => true,
-        '@PHP74Migration' => true,
+        '@PHP80Migration:risky' => true,
+        '@PHP82Migration' => true,
         '@PhpCsFixer' => true,
         // '@PhpCsFixer:risky' => true,
         'general_phpdoc_annotation_remove' => ['annotations' => ['expectedDeprecation']],

README.md

@@ -1,90 +1,147 @@
-# Laravel wrapper for using the Strapi headless CMS
+# Laravel wrapper for the Strapi headless CMS
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/dbfx/laravel-strapi.svg?style=flat-square)](https://packagist.org/packages/dbfx/laravel-strapi)
 [![Total Downloads](https://img.shields.io/packagist/dt/dbfx/laravel-strapi.svg?style=flat-square)](https://packagist.org/packages/dbfx/laravel-strapi)
 
 ---
 
-Laravel-Strapi is a Laravel helper for using the Strapi headless CMS. 
+**Laravel-Strapi** is a Laravel wrapper for the [Strapi headless CMS](https://strapi.io/). 
 
-Note: for Strapi v3 support use version 2.x.x
+## Requirements
+
+- PHP ^8.2
+- Laravel ^9 || ^10 || ^11 || ^12
+- Strapi ^4 || ^5
+
+_Note: to support Strapi v3.x use Laravel-Strapi v2.x._
 
 ## Installation
 
-You can install the package via composer:
+1\) Install the package via composer:
 
 ```bash
 composer require dbfx/laravel-strapi
 ```
 
-You can publish and run the migrations with:
-
-You can publish the config file with:
+2\) Publish the file `config/strapi.php` with:
 ```bash
 php artisan vendor:publish --provider="Dbfx\LaravelStrapi\LaravelStrapiServiceProvider" --tag="strapi-config"
 ```
 
-You need to define your STRAPI_URL and STRAPI_CACHE_TIME in .env:
-You can also optionally define a STRAPI_TOKEN to enable authentication. Do not include 'Bearer' only the token itself.
+3\) Define this mandatory configuration value in your `.env` file:
 
 ```
-STRAPI_URL=https://strapi.test.com
-STRAPI_CACHE_TIME=3600
-STRAPI_TOKEN=abcd1234abcd1234
+STRAPI_URL=https://api.example.com
 ```
 
-## Usage
+_Note: do not use `/api` at the end of `STRAPI_URL`._
 
-laravel-strapi provides the collection() and entry() calls to return a full collection, or a specific entry from a collection. In the 
-example below we are querying the strapi collection 'blogs' and then getting the entry with id 1 from that collection.
-```php
-use Dbfx\LaravelStrapi\LaravelStrapi;
+Optionally you can also define these values:
 
-$strapi = new LaravelStrapi();
-$blogs = $strapi->collection('blogs');
-$entry = $strapi->entry('blogs', 1);
+```
+STRAPI_TOKEN=abcd1234abcd1234
+STRAPI_CACHE_TYPE=deferred
+STRAPI_CACHE_TIME=86400
+STRAPI_CACHE_TTL=86400
+STRAPI_FLEXIBLE_CACHE_FRESH=300
+STRAPI_FLEXIBLE_CACHE_TOTAL=900
+STRAPI_QUEUE_CONNECTION=redis
+STRAPI_FULL_URLS=false
+STRAPI_SORT_FIELD=id
+STRAPI_SORT_ORDER=desc
+STRAPI_PAGINATION_START=0
+STRAPI_PAGINATION_LIMIT=25
+STRAPI_DEBUG=false
 ```
 
-There are several useful options available as well. 
+_Note: do not include `Bearer` in `STRAPI_TOKEN`, only the token itself._
 
-- ```$sortKey``` and ```$sortOrder``` allow you to specify the key to sort on and the direction
-- ```$fullUrls``` will automatically add your STRAPI_URL to the front of any relative URLs (e.g. images, etc).
-- ```$limit``` sets how many items you are requesting
-- ```$start``` is the offset to be used with limit, useful for pagination
-- ```$populate``` is an array containing the fields to populate
-- ```$queryData``` is an array of additional key-value pairs to add to the query string
+## Usage
+
+**Laravel-Strapi** provides these usefull methods:
 
 ```php
-use Dbfx\LaravelStrapi\LaravelStrapi;
+// returns collection-types rows by `$name`
+$strapi->collection(string $name, array $queryParams = [], ?bool $fullUrls = null, ?int $cacheTime = null, ?string $cacheType = null);
 
-$strapi = new LaravelStrapi();
-$blogs = $strapi->collection('blogs', $sortKey = 'id', $sortOrder = 'DESC', $limit = 20, $start = 0, $fullUrls = true, $populate = ['author', 'images'], $queryData = ['locale' => 'en']);
+// returns collection-types row by `$name` and `$id`
+$strapi->entry(string $name, int|string $id, array $queryParams = [], ?bool $fullUrls = null, ?int $cacheTime = null, ?string $cacheType = null);
 
-$entry = $strapi->entry('blogs', 1, $fullUrls = true, $populate = ['author', 'images'], $queryData = ['locale' => 'en']);
+// returns single-types values by `$name`
+$strapi->single(string $name, array $queryParams = [], ?bool $fullUrls = null, ?int $cacheTime = null, ?string $cacheType = null);
 ```
 
-You may also access Single Type items as follows: 
-
-```php
-use Dbfx\LaravelStrapi\LaravelStrapi;
-
-$strapi = new LaravelStrapi();
+These are all the available parameters:
 
-// Fetch the full homepage array
-$homepageArray = $strapi->single('homepage');
-
-// Return just the ['content'] field from the homepage array
-$homepageItem = $strapi->single('homepage', 'content');
-```
+- `$name` _(string)_: name of the collection-types (e.g. `blogs`) or single-types (e.g. `homepage`)
+- `$id` _(int|string)_: id of a collection-types entry
+- `$queryParams` _(array)_: optional array of key-value pairs of REST API parameters (see here https://docs.strapi.io/cms/api/rest/parameters)
+- `$fullUrls` _(bool)_: optional boolean value to override the global value defined in `STRAPI_FULL_URLS` per-call
+- `$cacheTime` _(int)_: optional value in seconds to override the global value defined in `STRAPI_CACHE_TIME` per-call
+- `$cacheType` _(string)_: optional value (e.g. `disabled`, `normal` (default), `forever`, `deferred` and `flexible`) to override the global value defined in `STRAPI_CACHE_TYPE` per-call
 
-And you may select entries by searching for a custom field (e.g. slug): 
+## Examples
 
 ```php
 use Dbfx\LaravelStrapi\LaravelStrapi;
 
 $strapi = new LaravelStrapi();
 
-$entries = $strapi->entriesByField('blogs', 'slug', 'test-blog-post');
+// returns the first 25 rows of the collection-types `blogs`
+// sorted in descending order by `id`
+$rows = $strapi->collection('blogs');
+
+// same thing as before, but in `en` language,
+// sorted descending by field `date` and ascending by field `title`
+// and with population of nested collection-types `author` and `images`
+$rows = $strapi->collection('blogs', [
+    'locale' => 'en',
+    'sort' => [
+        'date:desc',
+        'title:asc',
+    ],
+    'populate' => [
+        'author',
+        'images',
+    ],
+]);
+
+// similar to before, but with pagination by page values
+$rows = $strapi->collection('blogs', [
+    'pagination' => [
+        'page' => 2,
+        'pageSize' => 50,
+    ],
+]);
+
+// similar to before, but with pagination by offset values
+$rows = $strapi->collection('blogs', [
+    'pagination' => [
+        'start' => 0,
+        'limit' => 100,
+    ],
+]);
+
+// returns all rows of the collection-types `blogs`
+// where field `slug` is equal to `test-blog-post`
+$rows = $strapi->collection('blogs', [
+    'filters' => [
+        'slug' => [
+            '$eq' => 'test-blog-post',
+        ],
+    ],
+    'pagination' => [
+        'start' => 0,
+        'limit' => 1,
+    ],
+]);
+
+// returns the row of the collection-types `blogs`
+// where field `id` is `1`
+$row = $strapi->entry('blogs', 1);
+
+// returns all values of the single-types `homepage`
+$rows = $strapi->single('homepage');
 ```
 
 ## Changelog

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "dbfx/laravel-strapi",
-    "description": "Laravel wrapper for using the Strapi headless CMS",
+    "description": "Laravel wrapper for the Strapi headless CMS",
     "license": "MIT",
     "keywords": [
         "laravel",
@@ -18,23 +18,24 @@
     ],
     "homepage": "https://github.com/dbfx/laravel-strapi",
     "require": {
-        "php": "^7.4 || ^8.0",
-        "illuminate/contracts": "^8.37 || ^9.0 || ^10",
-        "laravel/framework": "^8 || ^9 || ^10",
-        "spatie/laravel-package-tools": "^1.4.3"
+        "php": "^8.2",
+        "illuminate/contracts": "^9 || ^10 || ^11 || ^12",
+        "laravel/framework": "^9 || ^10 || ^11 || ^12",
+        "spatie/laravel-package-tools": "^1.12"
     },
     "require-dev": {
-        "brianium/paratest": "^6.2",
-        "ergebnis/composer-normalize": "^2.42",
-        "friendsofphp/php-cs-fixer": "^3.48",
-        "nunomaduro/collision": "^5.3 || ^6.0",
-        "orchestra/testbench": "^6.15",
-        "phpro/grumphp-shim": "^1.13",
-        "phpunit/phpunit": "^9.3",
-        "rector/rector": "^0.19.5",
+        "brianium/paratest": "^7.7",
+        "driftingly/rector-laravel": "^2.0",
+        "ergebnis/composer-normalize": "^2.45",
+        "friendsofphp/php-cs-fixer": "^3.65",
+        "nunomaduro/collision": "^8.5",
+        "orchestra/testbench": "^9.8",
+        "phpro/grumphp-shim": "^2.10",
+        "phpunit/phpunit": "^11.5",
+        "rector/rector": "^2.0",
         "roave/security-advisories": "dev-latest",
-        "spatie/laravel-ray": "^1.9",
-        "vimeo/psalm": "^5.7"
+        "spatie/laravel-ray": "^1.39",
+        "vimeo/psalm": "^6.0@dev"
     },
     "minimum-stability": "dev",
     "prefer-stable": true,