# brainpink/gravatar: a Laravel package for Gravatar URLs and existence checks

> This is a Laravel package that turns an email address into a Gravatar image URL, tells you whether an avatar actually exists, and lets you configure the size, the fallback style, the rating ceiling and the default image per named configuration group. The interesting design choices are the group system, which lets one application serve avatars at different sizes and security settings from a single config file, and the option of passing inline options that merge with the default group.

**brainpink/gravatar** — A Laravel Gravatar package for retrieving gravatar image URLs or checking the existance of an image.

- Repository: https://github.com/brainpink/gravatar
- Stars: 545 · Forks: 58
- Language: PHP
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/brainpink-gravatar

## What the package does

The package is described as a Laravel Gravatar package for retrieving Gravatar image URLs or checking the existence of an image, and the README title states the range it covers, Gravatar for Laravel 5 to 12.

The surface is small and it is worth seeing all of it, because a package this small can be judged on whether it does one thing well. There are three operations.

Gravatar::get takes an email address and returns the URL to the Gravatar image for it. If no Gravatar exists for that address, it returns a URL to a placeholder image instead, and the type of placeholder is set in the configuration option fallback, with a link to the Gravatar documentation on default images for the list of types.

Gravatar::exists takes the same argument and returns a boolean, telling you whether there really is an image for that address rather than a placeholder.

And Gravatar::fallback lets you pass a URL to a custom image, which is chained onto the get call.

So the package covers the three things an application actually needs from Gravatar: a URL to put in an img tag, a way to know whether to show a real avatar or a default, and a way to supply your own default. That is the whole feature set, and it is a coherent one.

The primary language is PHP, the licence is MIT, the default branch is 1.0, and the recent releases are v1.0.26 from 2026-03-23, v1.0.25 from 2025-02-22 and v1.0.24 from 2024-02-28. The last push was on 2026-10-20 with the project not archived.

The top-level listing is what you would expect for a Laravel package and nothing more: .github/, .gitignore, LICENSE, composer.json, a config/ directory, readme.md and src/. There is no test directory, no changelog and no documentation site in the tree, which is worth knowing before you decide how much to trust it.

## Installing it, and the three ways to register the provider

The installation starts by pulling the package in through Composer:

```bash
composer require creativeorange/gravatar ~1.0
```

Or you can add it to composer.json by hand and run composer update:

```json
"require": {
    "creativeorange/gravatar": "~1.0"
}
```

Then the service provider, and here the README splits by Laravel version, which is the correct thing to do because the registration mechanism changed.

For Laravel 5.3 or below, the provider goes in app/config/app.php:

```php
'providers' => [
    'Creativeorange\Gravatar\GravatarServiceProvider'
];
```

For Laravel 5.4, the same file but with the class reference syntax:

```php
'providers' => [
    Creativeorange\Gravatar\GravatarServiceProvider::class
];
```

And the facade alias follows the same split. For 5.3 and below, add the alias to the bottom of the same file:

```php
'aliases' => [
    'Gravatar' => 'Creativeorange\Gravatar\Facades\Gravatar',
];
```

For 5.4 or greater:

```php
'aliases' => [
    'Gravatar' => Creativeorange\Gravatar\Facades\Gravatar::class,
];
```

Finally, publish the config by running the php artisan vendor:publish command, which copies the package's configuration file into your application so you can edit it.

That last step is the one people forget, and the configuration groups feature depends on it. Publishing the config is what gives you a config/gravatar.php to edit, and the group system is the package's most distinctive feature, so the config file is not optional in practice.

The version split in the README covers 5.3, 5.4 and later, and the title says up to Laravel 12, so the package has been kept working across a long span of framework versions. That is not unusual for a small utility package, since the surface it touches is the service provider and the facade, both of which are stable.

One detail worth noticing is the loose wording in the text about the facade alias, which says to add it to the bottom of app/config/app.php. It does not change anything, but it is a reminder that this documentation has been edited by someone working quickly, and the kind of small looseness worth checking against the actual code when you integrate.

## The three calls in use

The usage section shows the three operations in order, and each one is a single line.

The basic call:

```php
    Gravatar::get('email@example.com');
```

The existence check:

```php
    Gravatar::exists('email@example.com');
```

And the custom fallback, which is a chain rather than a separate argument:

```php
    Gravatar::fallback('http://urlto.example.com/avatar.jpg')->get('email@example.com');
```

The chaining style in the fallback example is the one design decision here worth dwelling on, because it tells you the shape of the API. The fallback method returns an object, and that object has a get method. So the call reads as a sentence: give me a fallback, then get the image.

The alternative would have been a second argument, get with a fallback argument. The chosen form has a consequence worth knowing: because fallback returns an object rather than a value, the order of the chain matters, and a call that puts the fallback after the get would not work. For a package with three methods that is a reasonable trade, because the fluent form reads better than a bag of optional arguments.

The existence check returns a plain boolean, and the documentation says so explicitly, which is the kind of small clarity that saves a reader from digging into the source.

There is also a note about the placeholder behaviour that is easy to miss. The get call does not return null or an empty string when there is no Gravatar; it returns a URL to a placeholder image. So if you want to know whether a real avatar exists, you need the separate exists call, because get will always give you something to put in an img tag.

That distinction is the practical reason both methods exist. A template that always renders an image wants get, and a template that wants to show initials or a different treatment when there is no registered avatar wants exists first and then decides. The package gives you both rather than making you parse the returned URL to work out which happened, which would have been a poor design given that the fallback images are ordinary image paths.

## Configuration groups, and the per-group options

The configuration file is where the package becomes more interesting than a URL builder, and the grouping mechanism is the feature to understand.

You can create different configuration groups to use within your application and pass the group name as a second parameter to the get method. There is a default group in config/gravatar.php which is used when you do not specify a second parameter.

So the config file is a map of named arrays, and the shipped file looks like this:

```php
return array(
	'default' => array(
		'size'   => 80,
		'fallback' => 'mm',
		'secure' => false,
		'maximumRating' => 'g',
		'forceDefault' => false,
		'forceExtension' => 'jpg',
	),
	'small-secure' => array (
	    'size'   => 30,
	    'secure' => true,
	),
	'medium' => array (
	    'size'   => 150,
	)
);
```

Reading the options themselves is the next step. The default group sets a size of 80, a fallback of mm, secure to false, a maximumRating of g, forceDefault to false, and a forceExtension of jpg.

The size is the pixel dimension of the requested image. The fallback of mm is one of Gravatar's built-in default image types, and it is a placeholder rather than a generated one, which is what the earlier documentation about default images was pointing at.

The secure flag is the interesting one, because it changes the host rather than the image. secure false means the request goes over plain HTTP, and secure true means HTTPS. That matters for a mixed-content situation, where a page served over HTTPS cannot load an image from an HTTP host without the browser blocking it. The small-secure group in the example is exactly that case, a 30 pixel avatar served securely.

The maximumRating option sets the ceiling on the maturity rating the avatar is allowed to have, with g being the most restrictive. The forceDefault option makes every request return the default image regardless of whether a Gravatar exists, which is what you want if you have decided not to show user-uploaded avatars at all.

And forceExtension pins the file extension, so a request returns a jpg even if the stored avatar is a png.

The naming of the second group, small-secure, is the clue to how the groups are meant to be used. They are not just presets, they are named combinations of size and transport, and a single application can serve a large avatar on a profile page and a small secure one in a comment list by asking for a different group name.

Using the groups is a second argument to get:

```php
Gravatar::get('email@example.com', 'small-secure'); // will use the small-secure group
Gravatar::get('email@example.com', 'medium'); // will use the medium group
Gravatar::get('email@example.com', 'default'); // will use the default group
Gravatar::get('email@example.com'); // will use the default group
```

The last line in that block is the important one, since calling get with no second parameter at all still resolves to the default group.

## Inline options, and what to check before depending on it

The last capability in the README is the one that is easiest to miss and the most convenient.

Alternatively, you could also pass an array directly as the second parameter as inline options. So, instead of passing a configuration key, you pass an array, which will be merged with the default group:

```php
Gravatar::get('email@example.com', ['size'=>200]); 
```

The merge behaviour is the useful part. Because the inline array is merged with the default group rather than replacing it, a call that specifies only the size keeps the default fallback, the default rating ceiling and everything else from the default group. So you get one override without having to restate the whole set.

That gives the package three ways to vary the output, and they are worth comparing. Named groups, which are configured centrally in a file and are the right choice for anything a designer or a developer will refer to repeatedly. Inline options, which are right for a one-off variation at a call site. And the fallback chain, which supplies the image itself rather than the settings.

The consequence is that the same second parameter carries two different types, a string naming a group or an array of overrides. That is a slightly loose API, and it means a caller who passes a variable has to be certain of its type, since a string that does not match a group name and an array are handled by different code paths.

The practical advice is to use one mechanism per call site. Where you have named groups, use them. Where you have a single call with one override, use the inline array. Mixing them across a codebase makes it hard to answer the question of where a given avatar's settings actually come from.

Two things to verify before you rely on the package. The first is the fallback type list, since the shipped default uses mm and the valid values are documented on the Gravatar site rather than in the package. The second is the behaviour of the maximumRating and forceDefault options on a Gravatar that does not exist, since a placeholder is served in that case and the rating ceiling may not apply to it. Neither is documented in the repository, and both are cheap to check against the Gravatar documentation.

The last point to weigh is the project's own shape. There is no test directory in the tree, no changelog, and the documentation lives entirely in the readme file, so the behaviour you rely on is the behaviour of a small amount of code that you should read once. The package is MIT licensed and the source is in src/, so reading it is a short exercise rather than a research project, and for a package this size that is the right amount of diligence.

## Conclusion

Adopt brainpink/gravatar if your Laravel application needs avatar URLs and you want the size, the transport, the rating ceiling and the fallback style configured centrally rather than hard-coded in templates, because the named group mechanism covers the case of serving avatars at different sizes on different pages. Do not treat it as a package with a documented public contract, since the repository has no test directory, no changelog and its documentation lives entirely in the readme file, so read the source in src/ once rather than relying on the description. Before you commit, publish the configuration with the vendor:publish command, because the group system is unavailable without it, check the valid fallback types against the Gravatar documentation since the shipped default uses mm, and settle on one mechanism per call site, since the second parameter accepts either a group name or an inline array and mixing the two makes it hard to trace where an avatar's settings came from.

## FAQ

### What does the brainpink/gravatar package do?

It is a Laravel package for retrieving Gravatar image URLs or checking the existence of an image, and the README title states the range it covers as Gravatar for Laravel 5 to 12. It is MIT licensed and written in PHP.

### How do I install the Gravatar package for Laravel?

Run composer require creativeorange/gravatar ~1.0, or add the requirement to composer.json and run composer update. Then register the service provider in app/config/app.php, using the string form for Laravel 5.3 and below and the class reference form for 5.4 and above, add the facade alias the same way, and publish the configuration with php artisan vendor:publish.

### What is the difference between Gravatar::get and Gravatar::exists?

Gravatar::get takes an email address and returns the URL to the image, falling back to a placeholder URL when no Gravatar exists, with the placeholder type set in the fallback configuration option. Gravatar::exists takes the same argument and returns a boolean telling you whether a real image exists.

### What configuration options does the Gravatar package support?

The shipped config groups define size, fallback, secure, maximumRating, forceDefault and forceExtension. The size is the pixel dimension, fallback is the placeholder type, secure chooses HTTP or HTTPS, maximumRating sets the rating ceiling, forceDefault always returns the placeholder, and forceExtension pins the file extension.

### Can I pass options inline instead of using a configuration group?

Yes. Instead of a configuration key you can pass an array as the second parameter, and it is merged with the default group, so a call specifying only the size keeps the other default settings. The same parameter therefore accepts either a group name or an array of overrides.

## Sources

- [brainpink/gravatar on GitHub](https://github.com/brainpink/gravatar)
- [Issues](https://github.com/brainpink/gravatar/issues)
- [License: MIT](https://github.com/brainpink/gravatar/blob/1.0/LICENSE)
- [README](https://github.com/brainpink/gravatar/blob/1.0/README.md)
- [Releases](https://github.com/brainpink/gravatar/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brainpink-gravatar