Laravel

The freeplaceholder/laravel Composer package provides a Facade, Blade components, Blade directives, helper functions, and an Eloquent trait.

Installation

bash

composer require freeplaceholder/laravel

The service provider is auto-discovered.

Facade

php

use FreePlaceholder\Facades\FreePlaceholder;

$url = FreePlaceholder::url(600, 400, [
    'format' => 'png',
    'bg' => '3b82f6',
    'text-color' => 'ffffff',
    'text' => 'Hero Banner',
    'font-weight' => 'bold',
    'rounded' => 'lg',
    'blur' => 2,
]);

$avatar = FreePlaceholder::avatarUrl('John Doe', [
    'size' => 256,
    'format' => 'png',
    'grayscale' => true,
    'border' => 3,
    'border-color' => 'ffffff',
]);

Blade Components

Use the <x-placeholder> and <x-avatar> components in any Blade template:

blade

<x-placeholder
  :width="800"
  :height="400"
  text="Banner"
  format="webp"
  bg="3b82f6"
  text-color="ffffff"
  font-weight="bold"
  rounded="lg"
/>

<x-avatar
  name="John Doe"
  :size="64"
  format="png"
  font-weight="bold"
  :border="2"
  border-color="ffffff"
  grayscale
/>

Placeholder Attributes

Attribute	Type	Default	Description
width	int	300	Image width
height	int	300	Image height
format	string	svg	Output format
bg	string	Background hex color
gradient	string	to-t, to-tr, to-r, to-br, to-b, to-bl, to-l, to-tl, radial
from	string	Gradient start color — hex without #
via	string	Gradient middle color — hex without #
to	string	Gradient end color — hex without #
text-color	string	Text hex color
text	string	Custom text
text-size	int	Font size in px
text-align	string	center	left, center, right
text-transform	string	none	uppercase, lowercase, capitalize
text-decoration	string	none	underline, overline, line-through
letter-spacing	string	tighter, tight, wide, wider, widest
font-weight	string	Font weight
opacity	int	100	0–100
blur	int	0	Gaussian blur 0–100 px
brightness	int	100	0–200
contrast	int	100	0–200
hue-rotate	int	0	0–360 degrees
invert	bool	false	Invert colors
saturate	int	100	0–200
sepia	bool	false	Sepia tone
grayscale	bool	false	Grayscale filter
border	int	0	Border width in px
border-color	string	Border hex color
border-style	string	solid	solid, dashed, dotted, double, none
rounded	string	0	sm, md, lg, xl, 2xl, 3xl, full, or px
lazy	bool	true	Enable lazy loading

Avatar Attributes

Attribute	Type	Default	Description
name	string	Name to derive initials from (required)
size	int	128	Square dimensions in px
format	string	svg	Output format
bg	string	Background hex color
gradient	string	to-t, to-tr, to-r, to-br, to-b, to-bl, to-l, to-tl, radial
from	string	Gradient start color — hex without #
via	string	Gradient middle color — hex without #
to	string	Gradient end color — hex without #
text-color	string	Text hex color
text-decoration	string	none	underline, overline, line-through
letter-spacing	string	tighter, tight, wide, wider, widest
font-weight	string	Font weight
opacity	int	100	0–100
blur	int	0	Gaussian blur 0–100 px
brightness	int	100	0–200
contrast	int	100	0–200
hue-rotate	int	0	0–360 degrees
invert	bool	false	Invert colors
saturate	int	100	0–200
sepia	bool	false	Sepia tone
grayscale	bool	false	Grayscale filter
border	int	0	Border width in px
border-color	string	Border hex color
border-style	string	solid	solid, dashed, dotted, double, none
rounded	string	0	sm, md, lg, xl, 2xl, 3xl, full, or px
lazy	bool	true	Enable lazy loading

Blade Directives

blade

@placeholder(width: 600, height: 400, format: 'png', bg: '3b82f6', textColor: 'ffffff', text: 'Banner')
@avatar(name: 'John Doe', size: 64, format: 'png')

Helper Functions

php

$url = placeholder_url(600, 400, ['format' => 'png', 'bg' => '3b82f6']);
$avatar = avatar_url('John Doe', ['size' => 64, 'format' => 'png', 'sepia' => true]);

Eloquent Trait

Add the HasPlaceholder trait to any model to get $model->placeholder and $model->avatar accessors:

php

use FreePlaceholder\Traits\HasPlaceholder;

class User extends Model
{
    use HasPlaceholder;

    // The attribute used for avatar text (default: 'name')
    protected function placeholderTextField(): string
    {
        return 'name';
    }

    // Default options for all placeholder URLs from this model
    protected function placeholderOptions(): array
    {
        return [
            'format' => 'png',
            'font-weight' => 'bold',
            'grayscale' => false,
        ];
    }
}

Usage:

php

$user = User::find(1);

// Uses the user's name for initials and color hashing
$user->avatar;         // https://freeplaceholder.com/avatar/John+Doe.png?font-weight=bold
$user->placeholder;    // https://freeplaceholder.com/300x300.png?text=John+Doe&font-weight=bold

// Override options
$user->avatarUrl(['size' => 256, 'border' => 3, 'border-color' => 'ffffff']);
$user->placeholderUrl(['width' => 600, 'height' => 400, 'blur' => 2]);

blade

{{-- In Blade templates --}}
<img src="{{ $user->avatar }}" alt="{{ $user->name }}" class="rounded-full" />

Overriding Base URL

Publish the config file and update the base URL:

bash

php artisan vendor:publish --tag=freeplaceholder-config

Then update config/freeplaceholder.php:

php

return [
    'base_url' => 'https://my-custom-instance.com',
];

Laravel

Installation

Facade

Blade Components

Placeholder Attributes

Avatar Attributes

Blade Directives

Helper Functions

Eloquent Trait

Overriding Base URL

Sponsored by CodeKudu