Skip to content

Commit f8093ad

Browse files
tomloprodtomloprod
committed
Initial commit
0 parents  commit f8093ad

33 files changed

Lines changed: 2652 additions & 0 deletions

‎.editorconfig‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
; This file is for unifying the coding style for different editors and IDEs.
2+
; More information at http://editorconfig.org
3+
4+
root = true
5+
6+
[*]
7+
charset = utf-8
8+
end_of_line = lf
9+
insert_final_newline = true
10+
indent_style = space
11+
indent_size = 4
12+
trim_trailing_whitespace = true
13+
14+
[*.md]
15+
trim_trailing_whitespace = false
16+
17+
[*.yml]
18+
indent_size = 2

‎.gitattributes‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/docs export-ignore
2+
/tests export-ignore
3+
/scripts export-ignore
4+
/.github export-ignore
5+
/.php_cs export-ignore
6+
.editorconfig export-ignore
7+
.gitattributes export-ignore
8+
.gitignore export-ignore
9+
phpstan.neon.dist export-ignore
10+
phpunit.xml.dist export-ignore
11+
rector.php export-ignore
12+
CHANGELOG.md export-ignore
13+
CONTRIBUTING.md export-ignore
14+
README.md export-ignore

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
custom: https://www.paypal.com/paypalme/tomloprod

‎.github/workflows/formats.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Formats
2+
3+
on: ['push', 'pull_request']
4+
5+
jobs:
6+
ci:
7+
runs-on: ${{ matrix.os }}
8+
9+
strategy:
10+
fail-fast: true
11+
matrix:
12+
os: [ubuntu-latest]
13+
php: [8.2]
14+
dependency-version: [prefer-lowest, prefer-stable]
15+
16+
name: Formats P${{ matrix.php }} - ${{ matrix.os }} - ${{ matrix.dependency-version }}
17+
18+
steps:
19+
20+
- name: Checkout
21+
uses: actions/checkout@v3
22+
23+
- name: Setup PHP
24+
uses: shivammathur/setup-php@v2
25+
with:
26+
php-version: ${{ matrix.php }}
27+
extensions: dom, mbstring, zip
28+
coverage: pcov
29+
30+
- name: Get Composer cache directory
31+
id: composer-cache
32+
shell: bash
33+
run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
34+
35+
- name: Cache dependencies
36+
uses: actions/cache@v3
37+
with:
38+
path: ${{ steps.composer-cache.outputs.dir }}
39+
key: dependencies-php-${{ matrix.php }}-os-${{ matrix.os }}-version-${{ matrix.dependency-version }}-composer-${{ hashFiles('composer.json') }}
40+
restore-keys: dependencies-php-${{ matrix.php }}-os-${{ matrix.os }}-version-${{ matrix.dependency-version }}-composer-
41+
42+
- name: Install Composer dependencies
43+
run: composer update --${{ matrix.dependency-version }} --no-interaction --prefer-dist
44+
45+
- name: Coding Style Checks
46+
run: composer test:lint
47+
48+
- name: Type Checks
49+
run: composer test:types

‎.github/workflows/tests.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Tests
2+
3+
on: ['push', 'pull_request']
4+
5+
jobs:
6+
ci:
7+
runs-on: ${{ matrix.os }}
8+
strategy:
9+
fail-fast: true
10+
matrix:
11+
os: [ubuntu-latest, macos-latest, windows-latest]
12+
php: [8.2, 8.3]
13+
dependency-version: [prefer-lowest, prefer-stable]
14+
15+
name: Tests P${{ matrix.php }} - ${{ matrix.os }} - ${{ matrix.dependency-version }}
16+
17+
steps:
18+
19+
- name: Checkout
20+
uses: actions/checkout@v3
21+
22+
- name: Setup PHP
23+
uses: shivammathur/setup-php@v2
24+
with:
25+
php-version: ${{ matrix.php }}
26+
extensions: dom, mbstring, zip, gd
27+
coverage: none
28+
29+
- name: Get Composer cache directory
30+
id: composer-cache
31+
shell: bash
32+
run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
33+
34+
- name: Cache dependencies
35+
uses: actions/cache@v3
36+
with:
37+
path: ${{ steps.composer-cache.outputs.dir }}
38+
key: dependencies-php-${{ matrix.php }}-os-${{ matrix.os }}-version-${{ matrix.dependency-version }}-composer-${{ hashFiles('composer.json') }}
39+
restore-keys: dependencies-php-${{ matrix.php }}-os-${{ matrix.os }}-version-${{ matrix.dependency-version }}-composer-
40+
41+
- name: Install Composer dependencies
42+
run: composer update --${{ matrix.dependency-version }} --no-interaction --prefer-dist
43+
44+
- name: Integration Tests
45+
run: php ./vendor/bin/pest

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/.phpunit.result.cache
2+
/.phpunit.cache
3+
/.php-cs-fixer.cache
4+
/.php-cs-fixer.php
5+
/composer.lock
6+
/phpunit.xml
7+
/vendor/
8+
*.swp
9+
*.swo

‎CONTRIBUTING.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# 🧑‍🤝‍🧑 Contributing
2+
3+
Contributions are welcome, and are accepted via pull requests.
4+
Please review these guidelines before submitting any pull requests.
5+
6+
## Process
7+
8+
1. Fork the project
9+
1. Create a new branch
10+
1. Code, test, commit and push
11+
1. Open a pull request detailing your changes.
12+
13+
## Guidelines
14+
15+
Radiance uses a few tools to ensure the code quality and consistency. [Pest](https://pestphp.com) is the testing framework of choice, and we also use [PHPStan](https://phpstan.org) for static analysis. Pest's type coverage is at 100%, and the test suite is also at 100% coverage.
16+
17+
In terms of code style, we use [Laravel Pint](https://laravel.com/docs/11.x/pint) to ensure the code is consistent and follows the Laravel conventions. We also use [Rector](https://getrector.org) to ensure the code is up to date with the latest PHP version.
18+
19+
You run these tools individually using the following commands:
20+
21+
```bash
22+
# Lint the code using Pint
23+
composer lint
24+
composer test:lint
25+
26+
# Refactor the code using Rector
27+
composer refactor
28+
composer test:refactor
29+
30+
# Run PHPStan
31+
composer test:types
32+
33+
# Run the test suite
34+
composer test:unit
35+
36+
# Run all the tools
37+
composer test
38+
```

‎LICENSE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) Tomás López <tomloprod@gmail.com>
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

‎README.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
<div align="center">
2+
<img title="Radiance - Deterministic Avatar Generator" alt="Radiance - Deterministic Avatar Generator" src="./docs/radiance.png" width="600">
3+
<p><b>Beautifully deterministic avatars for PHP</b></p>
4+
</div>
5+
6+
<div align="center">
7+
<a href="https://www.php.net/"><img alt="PHP >= 8.2" src="https://img.shields.io/badge/PHP-%E2%89%A5 8.2-777BB4?style=flat-square&logoColor=white&labelColor=111827&color=4f5b93&label=PHP"></a>
8+
<a href="https://packagist.org/packages/tomloprod/radiance"><img alt="Version" src="https://img.shields.io/packagist/v/tomloprod/radiance?style=flat-square&label=version&labelColor=111827&color=white"></a>
9+
<a href="https://github.com/tomloprod/radiance/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/tomloprod/radiance/tests.yml?branch=main&style=flat-square&label=tests&labelColor=111827&color=1a534d"></a>
10+
<a href="https://packagist.org/packages/tomloprod/radiance"><img alt="Downloads" src="https://img.shields.io/packagist/dt/tomloprod/radiance?style=flat-square&label=downloads&labelColor=111827&color=b15356"></a>
11+
<a href="https://packagist.org/packages/tomloprod/radiance"><img alt="License" src="https://img.shields.io/packagist/l/tomloprod/radiance?style=flat-square&label=license&labelColor=111827&color=38543d"></a>
12+
</div>
13+
14+
## ✨ **About Radiance**
15+
16+
**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 consistent UI elements.
17+
18+
<div align="center">
19+
<video src="https://github.com/user-attachments/assets/447b9ffd-8ec6-4b37-9e0f-d48c12a86215" width="80%" controls></video>
20+
<p>👉 <a href="https://radiance.tomloprod.dev/" target="_blank">Try the interactive playground</a></p>
21+
</div>
22+
23+
## 📑 **Features**
24+
25+
- 🎨 **Deterministic Generation**: Same seed, same avatar. Always.
26+
- 🌈 **Mesh Gradients**: Smooth, vibrant, and perceptually balanced color transitions.
27+
- 📐 **Multiple Shapes**: Circles, Squircles, and Rectangles.
28+
- ⌨️ **Text Overlay**: Add initials or names with automatic font resizing and shadow effects.
29+
- 🧩 **Pixel Patterns**: Optional identicon-style pixel overlays with customizable shapes and colors.
30+
- ⚡ **Fluent API**: An intuitive and expressive interface.
31+
32+
## 🚀 **Installation**
33+
34+
Requires [PHP 8.2+](https://php.net/releases/).
35+
36+
Install Radiance via [Composer](https://getcomposer.org):
37+
38+
```bash
39+
composer require tomloprod/radiance
40+
```
41+
42+
---
43+
44+
## **✨ Usage**
45+
46+
### Basic Usage
47+
48+
Generate a simple avatar from a seed:
49+
50+
```php
51+
$svg = radiance()
52+
->seed('tomloprod')
53+
->text('TL')
54+
->toSvg();
55+
```
56+
57+
### Advanced Customization
58+
59+
Radiance provides a fluent API to fully customize your avatars:
60+
61+
```php
62+
$svg = radiance()
63+
->seed('tomloprod')
64+
->text('TL')
65+
->size(256)
66+
->squircle()
67+
->baseColor('#3498db')
68+
->saturation(1.5)
69+
->contrast(1.2)
70+
->toSvg();
71+
```
72+
73+
### Pixel Patterns
74+
75+
Add a identicon-like pixelated overlay:
76+
77+
```php
78+
$svg = radiance()
79+
->seed('tomloprod')
80+
->enablePixelPattern()
81+
->pixelGridSize(8)
82+
->pixelOpacity(0.4)
83+
->pixelDensity(0.5)
84+
->pixelShapeCircles()
85+
->pixelColorAccent()
86+
->toSvg();
87+
```
88+
89+
### Text Controls
90+
91+
Fine-tune how text is displayed:
92+
93+
```php
94+
$svg = radiance()
95+
->seed('tomloprod')
96+
->text('TL')
97+
->fontFamily('Inter')
98+
->fontSizeRatio(0.45)
99+
->fontSizeRatioAuto(false)
100+
->textShadow(0.8)
101+
->toSvg();
102+
```
103+
104+
---
105+
106+
## **🧱 API Reference**
107+
108+
### Base
109+
110+
| Method | Description | Default |
111+
| :--- | :--- | :--- |
112+
| `seed(string $seed)` | Set the deterministic seed. | `null` (random) |
113+
114+
### Shape & Size
115+
116+
| Method | Description | Default |
117+
| :--- | :--- | :--- |
118+
| `size(int $size)` | Set the dimension in pixels (width/height). | `512` |
119+
| `circle()` | Set the shape to Circle. | - |
120+
| `square()` | Set the shape to Square. | (Square) |
121+
| `squircle()` | Set the shape to Squircle (rounded). | - |
122+
123+
### Colors
124+
125+
| Method | Description | Default |
126+
| :--- | :--- | :--- |
127+
| `baseColor(string $color)` | Influence the generated palette hue. Accepts hex, rgb, or hsl. | `null` |
128+
| `solidColor(string $color)` | Use a fixed background instead of gradient. | `null` |
129+
130+
### Gradient Filters
131+
132+
| Method | Description | Default |
133+
| :--- | :--- | :--- |
134+
| `saturation(float $val)` | Adjust gradient saturation. 1.0 = original, >1 = vivid, <1 = muted. | `1.0` |
135+
| `contrast(float $val)` | Adjust gradient contrast. 1.0 = original, >1 = higher contrast. | `1.0` |
136+
| `fadeDistance(int $val)` | Control gradient circle size (40-200). Lower = colors more separated. | `50` |
137+
138+
### Text Overlay
139+
140+
| Method | Description | Default |
141+
| :--- | :--- | :--- |
142+
| `text(string $text)` | Add a centered text overlay. | `null` |
143+
| `fontFamily(string $font)` | Set the font-family for the text. | `monospace` |
144+
| `fontSizeRatio(float $ratio)` | Set font size as ratio of avatar size (0.01-1.0). Disables auto-sizing. | `0.5` |
145+
| `fontSizeRatioAuto(bool $enabled)` | Enable/disable automatic font sizing based on text length. | `true` |
146+
| `textShadow(float $val)` | Set text shadow intensity. 0 = no shadow. | `1.0` |
147+
148+
### Pixel Pattern
149+
150+
| Method | Description | Default |
151+
| :--- | :--- | :--- |
152+
| `enablePixelPattern(bool $enable)` | Enable/disable the identicon-style overlay. | `true` |
153+
| `pixelGridSize(int $size)` | Set the pixel grid size (3, 5, 7...). Must be odd for symmetry. | `13` |
154+
| `pixelOpacity(float $opacity)` | Set pixel pattern opacity (0.0-1.0). | `0.3` |
155+
| `pixelDensity(float $density)` | Control how many pixels are drawn (0.0-1.0). | `0.25` |
156+
| `pixelColorGradient()` | Use gradient-derived colors for pixels. | (Gradient) |
157+
| `pixelColorMonochrome()` | Use white color for all pixels. | - |
158+
| `pixelColorAccent()` | Use complementary accent color for pixels. | - |
159+
| `pixelShapeSquares()` | Use square shapes for pixels. | (Squares) |
160+
| `pixelShapeCircles()` | Use circle shapes for pixels. | - |
161+
| `pixelShapeMix()` | Use mixed shapes (deterministic per seed). | - |
162+
163+
### Output
164+
165+
| Method | Description |
166+
| :--- | :--- |
167+
| `toSvg()` | Get the avatar as an SVG string. |
168+
| `toBase64()` | Get the avatar as a Base64 encoded data URI. |
169+
170+
---
171+
172+
## **🧑‍🤝‍🧑 Contributing**
173+
174+
Contributions are welcome! Please review the [Contributing Guidelines](CONTRIBUTING.md) before submitting a pull request.
175+
176+
1. Fork the project.
177+
2. Create a new branch (`git checkout -b feature/amazing-feature`).
178+
3. Commit your changes (`git commit -m 'Add some feature'`).
179+
4. Push to the branch (`git push origin feature/amazing-feature`).
180+
5. Open a Pull Request.
181+
182+
## **📝 License**
183+
184+
**Radiance** is open-sourced software licensed under the [MIT license](LICENSE.md).
185+
186+
<div align="center">
187+
Created by <b><a href="https://github.com/tomloprod">Tomás López</a></b> • Powered by <b><a href="https://github.com/tomloprod/colority">Colority</a></b>
188+
</div>

0 commit comments

Comments
 (0)