Skip to content

Latest commit

 

History

History
508 lines (365 loc) · 14.6 KB

README.md

File metadata and controls

508 lines (365 loc) · 14.6 KB
Raw

Latest Stable Version Total Downloads License

Gravatar for Laravel

This package provides an easy Gravatar integration in a Laravel project.

This package is built on top of forxer/Gravatar. If you want to dig deeper, you can find additional information on its README file.

$avatar = gravatar('[email protected]')
    ->size(120)
    ->defaultImage('robohash')
    ->extension('jpg');
//...
echo $avatar;

Index

Requirements

  • PHP 8.2 or newer
  • Laravel 10.0 or newer

If you want to use it with a version earlier than PHP 8.2 and/or a version earlier than Laravel 10, please use version 2 or version 1.

Installation

Install through composer:

composer require forxer/laravel-gravatar

Usage

There are three ways to use this library:

  • With the gravatar() helper fonction
  • With the facade Gravatar::create()
  • Or by injecting the LaravelGravatar\Gravatar service

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 LaravelGravatar\Image wich extends Gravatar\Image from forxer/Gravatar
  • avatar() which is an alias of the first
  • profile() which return an instance of LaravelGravatar\Profile wich extends Gravatar\Profile from forxer/Gravatar

This instances of LaravelGravatar\Image and LaravelGravatar\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:

$gravatar = gravatar();
// LaravelGravatar\Gravatar instance

$avatar = gravatar('[email protected]');
// LaravelGravatar\Image instance

$avatar = gravatar()->image('[email protected]');
// LaravelGravatar\Image instance

$avatar = gravatar()->avatar('[email protected]');
// LaravelGravatar\Image instance

$profile = gravatar()->profile('[email protected]');
// LaravelGravatar\Profile instance

Or with the facade:

use LaravelGravatar\Facades\Gravatar;

$gravatar = Gravatar::create();
// LaravelGravatar\Gravatar instance

$avatar = Gravatar::image('[email protected]');
// LaravelGravatar\Image instance

$avatar = Gravatar::avatar('[email protected]');
// LaravelGravatar\Image instance

$profile = Gravatar::profile('[email protected]');
// LaravelGravatar\Profile instance

Or with the service injection:

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);
    }
}

Retrieve the Gravatar URL

Simply use the url() method.

$gravatar = gravatar('[email protected]');
$gravatarUrl = $gravatar->url();

$gravatar = Gravatar::avatar('[email protected]');
$gravatarUrl = $gravatar->url();

Show directly in your views

As classes implement the toString() method you can use instances directly.

<img src="{{ gravatar('[email protected]') }}">

<img src="{{ Gravatar::avatar('[email protected]') }}">

<img src="{{ $avatar }}">

Back to top ^

Mandatory parameter

Obviously the email address is a mandatory parameter that can be entered in different ways.

// pass it as argument of the helper
$gravatarImage = gravatar($email);

// or use the `setEmail()` method
$gravatarImage = gravatar();
$gravatarImage->setEmail($email);

// or the `email()` helper method
$gravatarImage = gravatar();
$gravatarImage->email($email);

These previous examples are also valid for the profile.

Back to top ^

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.

// use the `setSize()` method
$gravatarImage = gravatar($email);
$gravatarImage->setSize(120);

// or the `size()` helper method
$gravatarImage = gravatar($email);
$gravatarImage->size(120);

// or its alias `s()` (as in the generated query string)
$gravatarImage = gravatar($email);
$gravatarImage->s(120);

Back to top ^

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:

Default Gravatar image

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

Mystery-man default Gravatar image Identicon default Gravatar image Wavatar default Gravatar image Retro default Gravatar image Robohash default Gravatar image Blank default Gravatar image

// use the `setDefaultImage()` method
$gravatarImage = gravatar($email);
$gravatarImage->setDefaultImage('mp');

// or the `defaultImage()` helper method
$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 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.
// use the `setMaxRating()` method
$gravatarImage = gravatar($email);
$gravatarImage->setMaxRating('g');

// or the `maxRating()` helper method
$gravatarImage = gravatar($email);
$gravatarImage->maxRating('g');

// or its alias `r()` (as in the generated query string)
$gravatarImage = gravatar($email);
$gravatarImage->r('g');

Back to top ^

Gravatar image file-type extension

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'
// use the `setExtension()` method
$gravatarImage = gravatar($email);
$gravatarImage->setExtension('jpg');

// or the `extension()` helper method
$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 ^

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:

// use the `setForceDefault()` method
$gravatarImage = gravatar($email);
$gravatarImage->setForceDefault(true);

// or the `forceDefault()` helper method
$gravatarImage = gravatar($email);
$gravatarImage->forceDefault(true);

// or its alias `f()` (as in the generated query string)
$gravatarImage = gravatar($email);
$gravatarImage->f(true);

// or use the `enableForceDefault()` method
$gravatarImage = gravatar($email);
$gravatarImage->setForceDefault(true);

To check to see if you are forcing default image, call the method forcingDefault() of LaravelGravatar\Image, which will return a boolean value regarding whether or not forcing default is enabled.

$gravatarImage = gravatar();
$gravatarImage->enableForceDefault();
//...
$gravatarImage->forcingDefault(); // true
//...
$gravatarImage->disableForceDefault();
//...
$gravatarImage->forcingDefault(); // false

Back to top ^

Combine them

You can combine them seamlessly:

$avatar = gravatar('[email protected]')
    ->size(120)
    ->rating('pg')
    ->defaultImage('robohash')
    ->extension('jpg');

Back to top ^

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:

php artisan vendor:publish --tag="gravatar-config"

And define some presets in the configuration file in the 'presets' array. There are a few predefined presets for the example in the configuration file, but you are of course free to delete them and define ones that suit your needs. For example:

    'my_default' => [
        'size' => 80,
        'default_image' => 'mp',
        'max_rating' => 'g',
        'extension' => 'webp',
    ],
    'small' => [
        'size' => 40,
        'extension' => 'jpg',
     ],
    'medium' => [
        'size' => 120,
        'extension' => 'jpg',
     ],
    'large' => [
        'size' => 360,
        'default_image' => 'robohash',
        'max_rating' => 'pg',
     ],

In the configuration file, for the values 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.

    'default_preset' => 'my_default',

Then, use it in your application with the second argument:

$gravatarImage = gravatar($email, 'small');

$gravatarImage = gravatar()->image($email, 'medium');

$gravatarImage = Gravatar::image($email, 'large');

Or you can set it later after instantiation:

// use the `setPreset()` method
$gravatarImage = gravatar($email);
$gravatarImage->setPreset('small');

// or the `preset()` helper method
$gravatarImage = gravatar($email);
$gravatarImage->preset('small');

Back to top ^

Casts

Let's imagine that your user model has a column "gravatar" which represents the email to use. You can cast this attribute to directly obtain an instance of LaravelGravatar\Image:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use LaravelGravatar\Casts\GravatarImage;

class User extends Model
{
    protected $casts = [
        'gravatar' => GravatarImage::class,
    ];
}

Thus it is easy to access the instance and manipulate it:

use App\Models\User;

class UserController
{
    public function show(User $user)
    {
        $user->gravatar->preset('small');

        return view('users.show', [
            'user' => $user,
        ]);
    }
}

You can even define a preset name to be used when casting by appending it's name to the cast:

use LaravelGravatar\Casts\GravatarImage;

class Post extends Model
{
    protected $casts = [
        'gravatar' => GravatarImage::class.':small',
    ];
}

You can also cast to an instance of LaravelGravatar\Profile:

use LaravelGravatar\Casts\GravatarProfile;

class User extends Model
{
    protected $casts = [
        'gravatar' => GravatarProfile::class,
    ];
}

Back to top ^