包简介

A deterministic mesh gradient avatar generator for PHP.

README 文档

README

Beautifully deterministic avatars for PHP

✨ About Radiance

Radiance is a modern PHP library designed to generate beautiful, deterministic mesh gradient avatars from any string. Same input always produces the same unique avatar, making it perfect for user profiles, identicons and more.

radiance.mp4

👉 Try the interactive playground

📑 Features

🎨 Deterministic Generation: Same seed, same avatar. Always.
🌈 Mesh Gradients: Smooth, vibrant, and perceptually balanced color transitions.
📐 Multiple Shapes: Circles, Squircles, and Rectangles.
⌨️ Text Overlay: Add initials or names with automatic font resizing and shadow effects.
🧩 Pixel Patterns: Optional identicon-style pixel overlays with customizable shapes and colors.
⚡ Fluent API: An intuitive and expressive interface.

🚀 Installation

Requires PHP 8.2+.

Install Radiance via Composer:

composer require tomloprod/radiance

✨ Usage

Basic Usage

Generate a simple avatar from a seed:

$svg = radiance()
    ->seed('tomloprod')
    ->text('TL')
    ->toSvg();

Advanced Customization

Radiance provides a fluent API to fully customize your avatars:

$svg = radiance()
    ->seed('tomloprod')
    ->text('TL')
    ->size(256)
    ->squircle()
    ->baseColor('#3498db')
    ->saturation(1.5)
    ->contrast(1.2)
    ->toSvg();

Pixel Patterns

Add a identicon-like pixelated overlay:

$svg = radiance()
    ->seed('tomloprod')
    ->enablePixelPattern()
    ->pixelGridSize(8)
    ->pixelOpacity(0.4)
    ->pixelDensity(0.5)
    ->pixelShapeCircles()
    ->pixelColorAccent()
    ->toSvg();

Text Controls

Fine-tune how text is displayed:

$svg = radiance()
    ->seed('tomloprod')
    ->text('TL')
    ->fontFamily('Inter')
    ->fontSizeRatio(0.45)
    ->fontSizeRatioAuto(false)
    ->textShadow(0.8)
    ->toSvg();

🧱 API Reference

Base

Method	Description	Default
`seed(string $seed)`	Set the deterministic seed.	`null` (random)

Shape & Size

Method	Description	Default
`size(int $size)`	Set the dimension in pixels (width/height).	`512`
`circle()`	Set the shape to Circle.	-
`square()`	Set the shape to Square.	(Square)
`squircle()`	Set the shape to Squircle (rounded).	-

Colors

Method	Description	Default
`baseColor(string $color)`	Influence the generated palette hue. Accepts hex, rgb, or hsl.	`null`
`solidColor(string $color)`	Use a fixed background instead of gradient.	`null`

Gradient Filters

Method	Description	Default
`saturation(float $val)`	Adjust gradient saturation. 1.0 = original, >1 = vivid, <1 = muted.	`1.0`
`contrast(float $val)`	Adjust gradient contrast. 1.0 = original, >1 = higher contrast.	`1.0`
`fadeDistance(int $val)`	Control gradient circle size (40-200). Lower = colors more separated.	`50`

Text Overlay

Method	Description	Default
`text(string $text)`	Add a centered text overlay.	`null`
`fontFamily(string $font)`	Set the font-family for the text.	`monospace`
`fontSizeRatio(float $ratio)`	Set font size as ratio of avatar size (0.01-1.0). Disables auto-sizing.	`0.5`
`fontSizeRatioAuto(bool $enabled)`	Enable/disable automatic font sizing based on text length.	`true`
`fontWeight(int $fontWeight)`	Set the weight of the used font.	`600`
`textShadow(float $val)`	Set text shadow intensity. 0 = no shadow.	`1.0`

Pixel Pattern

Method	Description	Default
`enablePixelPattern(bool $enable)`	Enable/disable the identicon-style overlay.	`true`
`pixelGridSize(int $size)`	Set the pixel grid size (3, 5, 7...). Must be odd for symmetry.	`13`
`pixelOpacity(float $opacity)`	Set pixel pattern opacity (0.0-1.0).	`0.3`
`pixelDensity(float $density)`	Control how many pixels are drawn (0.0-1.0).	`0.25`
`pixelColorGradient()`	Use gradient-derived colors for pixels.	(Gradient)
`pixelColorMonochrome()`	Use white color for all pixels.	-
`pixelColorAccent()`	Use complementary accent color for pixels.	-
`pixelShapeSquares()`	Use square shapes for pixels.	(Squares)
`pixelShapeCircles()`	Use circle shapes for pixels.	-
`pixelShapeMix()`	Use mixed shapes (deterministic per seed).	-

Output

Method	Description
`toSvg()`	Get the avatar as an SVG string.
`toBase64()`	Get the avatar as a Base64 encoded data URI.

🧑‍🤝‍🧑 Contributing

Contributions are welcome! Please review the Contributing Guidelines before submitting a pull request.

Fork the project.
Create a new branch (git checkout -b feature/amazing-feature).
Commit your changes (git commit -m 'Add some feature').
Push to the branch (git push origin feature/amazing-feature).
Open a Pull Request.

📝 License

Radiance is open-sourced software licensed under the MIT license.

Created by Tomás López • Powered by Colority

tomloprod/radiance 适用场景与选型建议

tomloprod/radiance 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 8.7k 次下载、GitHub Stars 达 139，最近一次更新时间为 2026 年 01 月 11 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「generator」「php」「deterministic」「avatar」「svg」「identicon」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 tomloprod/radiance 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 tomloprod/radiance 我们能提供哪些服务？

定制开发 / 二次开发

基于 tomloprod/radiance 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 tomloprod/radiance 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

memio/pretty-printer 6

Memio's PrettyPrinter, used to generate PHP code from given Model

kendall-hopkins/formal-theory 33

FormalTheory is a library that allows for manipulation and conversion of NFAs, DFAs and Regular Expressions.

saade/filament-facehash 4

Use Facehash as the default avatar provider in your Filament panels.

saade/facehash 6

Deterministic avatar faces from any string. Lightweight, pure SVG output. Laravel integration.

c01l/formal-theory 0