https://github.com/breadthe/php-contrast
Helpers for generating accessible color pairs
https://github.com/breadthe/php-contrast
color-pairs contrast-ratio generated-pairs php php-contrast
Last synced: 6 months ago
JSON representation
Helpers for generating accessible color pairs
- Host: GitHub
- URL: https://github.com/breadthe/php-contrast
- Owner: breadthe
- License: mit
- Created: 2020-02-20T02:32:55.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-09-05T13:31:01.000Z (almost 3 years ago)
- Last Synced: 2026-01-11T19:34:16.864Z (6 months ago)
- Topics: color-pairs, contrast-ratio, generated-pairs, php, php-contrast
- Language: PHP
- Homepage: https://mumu.pw/contrast
- Size: 23.4 KB
- Stars: 6
- Watchers: 1
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# PHP Contrast Tools
[](https://packagist.org/packages/breadthe/php-contrast)
[](https://travis-ci.org/breadthe/php-contrast)
[](https://scrutinizer-ci.com/g/breadthe/php-contrast)
[](https://packagist.org/packages/breadthe/php-contrast)
Provides various utilities for working with color contrast.
The primary purpose is to facilitate easy generation of accessible (minimum 3.0 contrast ratio) hex color pairs. A variation of these tools restricts the generated colors to [TailwindCSS's](https://tailwindcss.com/) default palette.
I've created a [demo page](https://mumu.pw/contrast) to show how color pairs can be generated by this package.
## Installation
You can install the package via composer:
```bash
composer require breadthe/php-contrast
```
## Usage
Import the class.
```php
use Breadthe\PhpContrast\HexColor; // factory
use Breadthe\PhpContrast\HexColorPair; // hex pair utilities
use Breadthe\PhpContrast\TailwindColor; // Tailwind color pair utilities
```
## Check the contrast ratio between 2 colors
```php
$hexColorPair = HexColorPair::make(HexColor::make('000000'), HexColor::make('ffffff'));
$hexColorPair->ratio; // 21
$hexColorPair->fg; // '#000000'
$hexColorPair->bg; // '#ffffff'
```
## Get a random color pair (with the resulting ratio), with minimum 3:1 contrast ratio
```php
$hexColorPair = HexColorPair::random();
$hexColorPair->ratio; // 3.8
$hexColorPair->fg->hex; // '#36097e'
$hexColorPair->fg->name; // null
$hexColorPair->bg->hex; // '#ed4847'
$hexColorPair->bg->name; // null
```
## Get a random color pair (with the resulting ratio), with minimum specified contrast ratio (but no less than 3:1)
**⚠️ Warning** For performance reasons, the minimum requested contrast ratio is capped at 4.5, although the generated pairs can go up to the theoretical maximum 21:1 ratio.
**⚠️ Caution** When chaining with `minContrast()`, make sure to use `getRandom()` instead of `random()`.
```php
$hexColorPair = HexColorPair::minContrast(4.5)->getRandom();
$hexColorPair->ratio; // 7.6
$hexColorPair->fg->hex; // '#0c402f'
$hexColorPair->fg->name; // null
$hexColorPair->bg->hex; // '#badd73'
$hexColorPair->bg->name; // null
```
## Get a random accessible sibling for the given color, with minimum specified contrast ratio (but no less than 3:1)
```php
// Minimum 3:1 contrast ratio
HexColorPair::sibling('000000')->hex; // '#ffffff'
// Minimum specified contrast ratio (no less than 3:1)
HexColorPair::minContrast(4.5)->getSibling('000000')->hex; // '#ffffff'
```
## Generate a random TailwindCSS color
```php
$twColor = TailwindColor::random();
$twColor->hex; // '#e2e8f0'
$twColor->name; // 'gray-300'
```
## Generate a pair of random accessible TailwindCSS colors
```php
$twColorpair = TailwindColor::randomPair();
$twColorpair->ratio; // 3.3
$twColorpair->fg->hex; // '#63b3ed'
$twColorpair->fg->name; // 'blue-400'
$twColorpair->bg->hex; // '#4a5568'
$twColorpair->bg->name; // 'green-700'
```
## Generate a pair of random accessible TailwindCSS colors, with minimum specified contrast ratio (but no less than 3:1)
**⚠️ Warning** For performance reasons, the minimum requested contrast ratio is capped at 4.5, although the generated pairs can go up to the theoretical maximum 21:1 ratio.
**⚠️ Caution** When chaining with `minContrast()`, make sure to use `getRandomPair()` instead of `randomPair()`.
```php
$twColorpair = TailwindColor::minContrast(4.5)->getRandomPair();
$twColorpair->ratio; // 7.0
$twColorpair->fg->hex; // '#faf5ff'
$twColorpair->fg->name; // 'purple-100'
$twColorpair->bg->hex; // '#9b2c2c'
$twColorpair->bg->name; // 'red-800'
```
## Merge the default Tailwind colors with a custom palette
You may extend the default Tailwind colors with your own custom palette. Here's an example of how to import a custom palette from a JSON file.
```json
{
"background": "#FFFFFF",
"headline": "#1f1235",
"sub-headline": "#1b1425",
"button": "#ff6e6c",
"button-text": "#1f1235"
}
```
```php
$customPalette = json_decode(file_get_contents('custom-palette.json'), true);
$colors = TailwindColor::merge($customPalette)->getColors();
```
### Testing
``` bash
composer test
```
### Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
### Security
If you discover any security related issues, please email omigoshdev@protonmail.com instead of using the issue tracker.
## Credits
- [Omigosh Dev](https://github.com/breadthe)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
## PHP Package Boilerplate
This package was generated using the [PHP Package Boilerplate](https://laravelpackageboilerplate.com).