diff --git a/CHANGELOG.md b/CHANGELOG.md
index b094f5a..433a993 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,14 @@
CHANGELOG
=========
+2.0.1 (2023-03-20)
+------------------
+
+- Improved preset support
+- Added some defaults customs presets
+- Rewritten README file
+
+
2.0.0 (2023-03-18)
------------------
diff --git a/README.md b/README.md
index b9bc46d..b049d8f 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,39 @@ Gravatar for Laravel
This package provides an easy Gravatar integration in a Laravel project.
-This package is built on top of [forxer/Gravatar](https://github.com/forxer/gravatar).
+This package is built on top of [forxer/Gravatar](https://github.com/forxer/gravatar). If you want to dig deeper, you can find additional information on its README file.
+
+```php
+$avatar = gravatar('email@example.com')
+ ->size(120)
+ ->defaultImage('robohash')
+ ->extension('jpg');
+//...
+echo $avatar;
+```
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+ - [Retrieve instances](#retrieve-instances)
+ - [Show directly in your views](#show-directly-in-your-views)
+- [Mandatory parameter](#mandatory-parameter)
+- [Optional parameters](#optional-parameters)
+ - [Gravatar image size](#gravatar-image-size)
+ - [Default Gravatar image](#default-gravatar-image)
+ - [Gravatar image max rating](#gravatar-image-max-rating)
+ - [Gravatar image file-type extension](#gravatar-image-file-type-extension)
+ - [Force to always use the default image](#force-to-always-use-the-default-image)
+ - [Combine them](#combine-them)
+- [Image presets](#image-presets)
+
+Requirements
+------------
+
+- PHP 8.0.0 or newer
+- Laravel 8.0 or newer
+
+If you want to use it with a version earlier than PHP 8 and/or a version earlier than Laravel 8, please use [version 1](https://github.com/forxer/laravel-gravatar/tree/1.x).
Installation
------------
@@ -18,84 +50,363 @@ Install through composer:
composer require forxer/laravel-gravatar
```
-Usage for Gravatar Images
--------------------------
+Usage
+-----
-### Directly in your views
+There are three ways to use this library:
-With the helper:
+- With the `gravatar()` helper fonction
+- With the facade `Gravatar::create()`
+- Or by injecting the `LaravelGravatar\Gravatar` service
-```blade
- }})
-// or
-->image('email@example.com') }})
-// or
-->avatar('email@example.com') }})
+All of these ways return an instance of the `LaravelGravatar\Gravatar` service. The Gravatar service has 3 main methods :
+
+- `image()` which return an instance of `Gravatar\Image` from [forxer/Gravatar](https://github.com/forxer/gravatar)
+- `avatar()` which is an alias of the first
+- `profile()` which return an instance of `Gravatar\Profile` from [forxer/Gravatar](https://github.com/forxer/gravatar)
+
+This instances of `Gravatar\Image` and `Gravatar\Profile` allow you to define specific settings/parameters as needed. So you can use them to build Gravatar images/profiles URL.
+
+Whatever method you use, you could use the `url()` method to retrieve it. Or display the URL directly because they implement the `__toString()` method.
+
+### Retrieve instances
+
+With the helper
+
+```php
+$gravatar = gravatar();
+// LaravelGravatar\Gravatar instance
+
+$avatar = gravatar('email@example.com');
+// Gravatar\Image instance
+
+$avatar = gravatar()->image('email@example.com');
+// Gravatar\Image instance
+
+$avatar = gravatar()->avatar('email@example.com');
+// Gravatar\Image instance
+
+$profile = gravatar()->profile('email@example.com');
+// Gravatar\Profile instance
```
Or with the facade:
-```blade
- }})
-// or
- }})
+```php
+use LaravelGravatar\Facade as Gravatar;
+
+$gravatar = Gravatar::create();
+// LaravelGravatar\Gravatar instance
+
+$avatar = Gravatar::image('email@example.com');
+// Gravatar\Image instance
+
+$avatar = Gravatar::avatar('email@example.com');
+// Gravatar\Image instance
+
+$profile = Gravatar::profile('email@example.com');
+// Gravatar\Profile instance
```
Or with the service injection:
+```php
+use App\Models\User;
+use LaravelGravatar\Gravatar as Gravatar;
+
+class UserController
+{
+ public function show(User $user, Gravatar $gravatar)
+ {
+ $avatar = $gravatar->avatar($user->email);
+
+ $profile = $gravatar->profile($user->email);
+ }
+}
+```
+
+### Show directly in your views
+
```blade
-@inject('gravatar', 'forxer\LaravelGravatar\Gravatar')
+
+
+
- }})
-// or
- }})
+
```
-### Optional parameters
+[Back to top ^](#gravatar-for-Laravel)
-You can set optional parameters:
+Mandatory parameter
+-------------------
-```blade
-->s(120)->e('png') }})
-// or
-->size(120)->extension('png') }})
-// or
-->setSize(120)->setExtension('png') }})
+Obviously the email address is a mandatory parameter that can be entered in different ways.
+
+```php
+// pass it as argument of the helper
+$gravatarImage = gravatar($email);
+
+// or use the `setEmail()` method of a `Gravatar\Image` instance
+$gravatarImage = gravatar();
+$gravatarImage->setEmail($email);
+
+// or the `email()` helper method of a `Gravatar\Image` instance
+$gravatarImage = gravatar();
+$gravatarImage->email($email);
+```
+
+These previous examples are also valid for the profile.
+
+[Back to top ^](#gravatar-for-Laravel)
+
+Optional parameters
+-------------------
+
+In all the examples below we will use the helper but it obviously works with the facade or the dependency injection of the service.
+
+### Gravatar image size
+
+By default, images are presented at 80px by 80px if no size parameter is supplied.
+You may request a specific image size, which will be dynamically delivered from Gravatar.
+You may request images anywhere from 1px up to 2048px, however note that many users have lower resolution images,
+so requesting larger sizes may result in pixelation/low-quality images.
+
+An avatar size should be an integer representing the size in pixels.
+
+```php
+// use the `setSize()` method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->setSize(120);
+
+// or the `size()` helper method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->size(120);
+
+// or its alias `s()` (as in the generated query string)
+$gravatarImage = new Gravatar\Image($email);
+$gravatarImage->s(120);
+```
+
+[Back to top ^](#gravatar-for-Laravel)
+
+### Default Gravatar image
+
+What happens when an email address has no matching Gravatar image or when the gravatar specified exceeds your maximum allowed content rating?
+
+By default, this:
+
+
+
+If you'd prefer to use your own default image, then you can easily do so by supplying the URL to an image.
+In addition to allowing you to use your own image, Gravatar has a number of built in options which you can also use as defaults.
+Most of these work by taking the requested email hash and using it to generate a themed image that is unique to that email address.
+To use these options, just pass one of the following keywords:
+
+- '404': do not load any image if none is associated with the email hash, instead return an HTTP 404 (File Not Found) response
+- 'mp': (mystery-person) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash)
+- 'identicon': a geometric pattern based on an email hash
+- 'monsterid': a generated 'monster' with different colors, faces, etc
+- 'wavatar': generated faces with differing features and backgrounds
+- 'retro': awesome generated, 8-bit arcade-style pixelated faces
+- 'robohash': a generated robot with different colors, faces, etc
+- 'blank': a transparent PNG image
+
+
+
+
+
+
+
+
+```php
+// use the `setDefaultImage()` method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->setDefaultImage('mp');
+
+// or the `defaultImage()` helper method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->defaultImage('mp');
+
+// or its alias `d()` (as in the generated query string)
+$gravatarImage = gravatar($email);
+$gravatarImage->d('mp');
+```
+
+[Back to top ^](#gravatar-for-Laravel)
+
+### Gravatar image max rating
+
+Gravatar allows users to self-rate their images so that they can indicate if an image is appropriate for a certain audience.
+By default, only 'g' rated images are displayed unless you indicate that you would like to see higher ratings.
+
+You may specify one of the following ratings to request images up to and including that rating:
+
+- 'g': suitable for display on all websites with any audience type.
+- 'pg': may contain rude gestures, provocatively dressed individuals, the lesser swear words, or mild violence.
+- 'r': may contain such things as harsh profanity, intense violence, nudity, or hard drug use.
+- 'x': may contain hardcore sexual imagery or extremely disturbing violence.
+
+```php
+// use the `setMaxRating()` method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->setMaxRating('g');
+
+// or the `maxRating()` helper method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->maxRating('g');
+
+// or its alias `r()` (as in the generated query string)
+$gravatarImage = gravatar($email);
+$gravatarImage->r('g');
```
-There is several available parameters:
+[Back to top ^](#gravatar-for-Laravel)
+
+### Gravatar image file-type extension
-- size `setSize()` `size()` or `s()`
-- default image `setDefaultImage()` `size()` or `s()`
-- force default `setForceDefault()` `defaultImage()` or `d()`
-- max rating `setMaxRating()` `rating()` or `r()`
-- extension `setExtension()` `extension()` or `e()`
+If you require a file-type extension (some places do) then you may also specify it.
+
+You can specify one of the following extensions for the generated URL:
+
+- 'jpg'
+- 'jpeg'
+- 'gif'
+- 'png'
+- 'webp'
+
+```php
+// use the `setExtension()` method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->setExtension('jpg');
-For more details, please refer to the [forxer/Gravatar documentation](https://github.com/forxer/gravatar#optional-parameters).
+// or the `extension()` helper method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->extension('jpg');
+
+// or its alias `e()` (as in the generated query string)
+$gravatarImage = gravatar($email);
+$gravatarImage->e('jpg');
+```
+
+[Back to top ^](#gravatar-for-Laravel)
+
+### Force to always use the default image
+
+If for some reason you wanted to force the default image to always be load, you can do it:
+
+```php
+// use the `setForceDefault()` method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->setForceDefault(true);
-### Using presets
+// or the `forceDefault()` helper method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->forceDefault(true);
-It is possible to define groups of defaults, known as presets. This is helpful if you have standard settings that you use throughout your app. In the configuration file, you can define as many avatar preset as you wish and a default preset to be used.
+// or its alias `f()` (as in the generated query string)
+$gravatarImage = gravatar($email);
+$gravatarImage->f(true);
+
+$gravatarImage = new Gravatar\Image($email);
+$gravatarImage->f(true);
+
+// or use the `enableForceDefault()` method of a `Gravatar\Image` instance
+$gravatarImage = gravatar($email);
+$gravatarImage->setForceDefault(true);
+```
+
+To check to see if you are forcing default image, call the method `forcingDefault()` of `Gravatar\Image`,
+which will return a boolean value regarding whether or not forcing default is enabled.
+
+```php
+$gravatarImage = gravatar();
+$gravatarImage->enableForceDefault();
+//...
+$gravatarImage->forcingDefault(); // true
+//...
+$gravatarImage->disableForceDefault();
+//...
+$gravatarImage->forcingDefault(); // false
+```
+
+[Back to top ^](#gravatar-for-Laravel)
+
+### Combine them
+
+You can combine them seamlessly:
+
+```php
+$avatar = gravatar('email@example.com')
+ ->size(120)
+ ->rating('pg')
+ ->defaultImage('robohash')
+ ->extension('jpg');
+```
+
+[Back to top ^](#gravatar-for-Laravel)
+
+Image presets
+-------------
+
+It is possible to define groups of defaults parameters, known as presets. This is helpful if you have standard settings that you use throughout your application. In the configuration file, you can define as many gravatar presets as you wish and a default preset to be used.
First, publish the config file of the package using artisan:
```sh
-php artisan vendor:publish --provider="forxer\LaravelGravatar\ServiceProvider"
+php artisan vendor:publish --tag="gravatar-config"
```
-Then, define a preset in the configuration file:
+Then, define some presets in the configuration file in the 'presets' array, for example:
```php
- 'my_preset' => [
+ 'my_default' => [
+ 'size' => 80,
+ 'default_image' => 'mp',
+ 'max_rating' => 'g',
+ 'extension' => 'webp',
+ ],
+ 'small' => [
+ 'size' => 40,
+ 'extension' => 'jpg',
+ ],
+ 'medium' => [
'size' => 120,
- 'extension' => 'png',
+ 'extension' => 'jpg',
+ ],
+ 'large' => [
+ 'size' => 360,
+ 'extension' => 'jpg',
+ ],
+ 'profile' => [
+ 'size' => 360,
+ 'default_image' => 'robohash',
+ 'max_rating' => 'pg',
],
```
-Finally, use it in your views by specifying its name.
+Finally, use it in your application with the second argument:
-```blade
- }})
+```php
+$navbarAvatar = gravatar('email@example.com', 'small');
+
+$lateralAvatar = gravatar()->image('email@example.com', 'medium');
+
+$ProfileAvatar = Gravatar::image('email@example.com', 'profile');
+```
+
+For the preset key name, as these are array keys and we follow naming conventions, you can use either:
+
+- `'size'` or `'s'`
+- `'default_image'` or `'d'`
+- `'max_rating'` or `'r'`
+- `'extension'` or `'e'`
+- `'force_default'` or `'f'`
+
+If you wish you can default to one of these presets at the top of the configuration file.
+
+```php
+ 'default_preset' => 'my_default',
```
+[Back to top ^](#gravatar-for-Laravel)
diff --git a/UPGRADE.md b/UPGRADE.md
index cad6ef3..57b1dd7 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -10,3 +10,6 @@ Namespaces have been renamed from `forxer\LaravelGravatar\` to `LaravelGravatar\
- Find: `use forxer\LaravelGravatar\`
- Replace: `use LaravelGravatar\`
+
+Since this version, if you use an undefined preset an exception is thrown. You must define presets before you can use them.
+Please consult the chapter of the README concerning presets to adjust your settings.
diff --git a/config/gravatar.php b/config/gravatar.php
index 78ddf07..81a2d73 100644
--- a/config/gravatar.php
+++ b/config/gravatar.php
@@ -15,7 +15,6 @@
*/
'default_preset' => null,
- // 'default_preset' => 'gravatar',
/*
|--------------------------------------------------------------------------
@@ -77,7 +76,7 @@
| - null value to fallback to the default Gravatar
| - a string represanting the URL of your own default image
| - '404': do not load any image if none is associated with the email hash, instead return an HTTP 404 (File Not Found) response
- | - 'mm': (mystery-person) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash)
+ | - 'mp': (mystery-person) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash)
| - 'identicon': a geometric pattern based on an email hash
| - 'monsterid': a generated 'monster' with different colors, faces, etc
| - 'wavatar': generated faces with differing features and backgrounds
@@ -138,24 +137,34 @@
| Another Preset
|--------------------------------------------------------------------------
|
- | Here is another example of a preset.
+ | Define here your own presets.
|
*/
- 'another_preset' => [
-
- 'size' => 120,
-
+ 'xxs' => [
+ 'size' => 23,
'default_image' => 'mp',
+ ],
- 'force_default' => false,
+ 'xs' => [
+ 'size' => 35,
+ 'default_image' => 'mp',
+ ],
- 'max_rating' => 'g',
+ 'sm' => [
+ 'size' => 90,
+ 'default_image' => 'mp',
+ ],
- 'extension' => 'jpg',
+ 'md' => [
+ 'size' => 180,
+ 'default_image' => 'mp',
+ ],
+ 'lg' => [
+ 'size' => 360,
+ 'default_image' => 'mp',
],
],
-
];
diff --git a/src/Gravatar.php b/src/Gravatar.php
index b8f8c81..d062b2c 100644
--- a/src/Gravatar.php
+++ b/src/Gravatar.php
@@ -27,6 +27,11 @@ public function __construct(array $config)
$this->config = $config;
}
+ public static function create()
+ {
+ return app()->make('gravatar');
+ }
+
/**
* Return the Gravatar image based on the provided email address.
*
@@ -82,27 +87,38 @@ private function applyPreset(Image $image, ?string $presetName = null): Image
return $image;
}
- foreach ($this->getPresetValues($presetName) as $k => $v) {
- $setter = 'set'.ucfirst(Str::camel($k));
+ $presetValues = $this->presetValues($presetName);
+
+ if (empty($presetValues)) {
+ return $image;
+ }
- if (! method_exists($image, $setter)) {
- throw new InvalidArgumentException("Gravatar image [{$setter}] method does not exists.");
+ foreach ($presetValues as $k => $v) {
+ if (! in_array($k, $this->allowedSetterPresetKeys())) {
+ throw new InvalidArgumentException(
+ "Gravatar image could not find method to use \"$k\" key".
+ "Allowed preset keys are: ".implode(',', $this->allowedSetterPresetKeys()).'.'
+ );
}
- $image->{$setter}($v);
+ if (strlen($k) === 1) {
+ $image->{$k}($v);
+ } else {
+ $image->{Str::camel($k)}($v);
+ }
}
return $image;
}
/**
- * Return preset values to use.
+ * Return preset values to use from configuration file.
*
* @param string $presetName
* @return array
* @throws InvalidArgumentException
*/
- private function getPresetValues(?string $presetName = null): array
+ private function presetValues(?string $presetName = null): array
{
if ($presetName === null) {
if (empty($this->config['default_preset'])) {
@@ -126,4 +142,15 @@ private function getPresetValues(?string $presetName = null): array
return $presetValues;
}
+
+ private function allowedSetterPresetKeys()
+ {
+ return [
+ 'size', 's',
+ 'default_image', 'd',
+ 'max_rating', 'r',
+ 'extension', 'e',
+ 'force_default', 'f',
+ ];
+ }
}