Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ryangjchandler/color
A simple Color object for PHP packages and applications. 🎨
https://github.com/ryangjchandler/color
color color-difference color-distance color-object composer hex-to-rgb php php-color random-color rgb-to-hex
Last synced: 3 months ago
JSON representation
A simple Color object for PHP packages and applications. 🎨
- Host: GitHub
- URL: https://github.com/ryangjchandler/color
- Owner: ryangjchandler
- License: mit
- Created: 2021-01-21T16:07:03.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2021-03-19T10:06:44.000Z (almost 4 years ago)
- Last Synced: 2024-10-14T08:27:59.765Z (4 months ago)
- Topics: color, color-difference, color-distance, color-object, composer, hex-to-rgb, php, php-color, random-color, rgb-to-hex
- Language: PHP
- Homepage:
- Size: 61.5 KB
- Stars: 38
- Watchers: 2
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Color
A simple Color object for PHP packages and applications. 🎨
## Installation
This package can be installed via Composer:
```bash
composer require ryangjchandler/color
```
## Usage
This package provides a single `RyanChandler\Color\Color` object.
### Creating a color
To create a color, instantiate a new `RyanChandler\Color\Color` object:
```php
use RyanChandler\Color\Color;
$color = new Color(255, 255, 255);
```
The constructor accepts three _optional_ arguments. The red, green and blue decimal representations of your color.
If you prefer using static constructors you can use the `Color::new()` method, Ã la Rust.
```php
$color = Color::new(255, 255, 255);
```
### Creating a color from a hex
If you wish to create a color using the hex representation, you can use the `Color::hex()` method.
```php
$color = Color::hex('#ffffff');
```
This will convert your hex representation into the RGB equivalent.
The `#` is not compulsory. It will only be removed _if_ the string provided starts with it.
> It's worth noting that any alpha values specified on the hex value will be stripped since the string is clamped to a length of 6. This is something that might be supported in a future version.
### Creating a color from HSL values
You can also use hue, saturation and lightness values to create a color using the `Color::hsl()` method.
```php
$color = Color::hsl(0, 0, 100);
```
This will convert your HSL values into the RGB equivalent.
> You can also define the alpha as an optional fourth argument `Color::hsl(0, 0, 100, 0.5)`
### Generating a random color
You can generate a random color using the `Color::random()` method.
```php
$random = Color::random();
```
### Accessing the red, green and blue values
Each color value can be accessed using a public property on the `Color` object.
```php
$color = Color::new(255, 255, 255);
$color->red; // 255
$color->green; // 255
$color->blue; // 255
```
### Getting the hex representation
If you wish to get the hex equivalent of your color, you can use the `Color::toHex()` method.
```php
Color::new(255, 255, 255)->toHex(); // #ffffff
```
### Getting the HSL representation
If you wish to get the HSL equivalent of your color as an array, you can use the `Color::toHsl()` method.
```php
[$h, $s, $l] = Color::new(255, 255, 255)->toHsl(); // [0, 0, 100]
```
### Getting the string representation
By default, the `Color::toString()` method returns a tuple-like string.
```php
Color::new(255, 255, 255)->toString(); // "(255, 255, 255)"
```
You can also use the `Color::toString()` method to retrieve the hex representation.
```php
Color::new(255, 255, 255)->toString(true); // #ffffff
```
Or use PHP's typecasting to get a string instead.
```php
(string) Color::new(255, 255, 255); // "(255, 255, 255)"
```
### Getting an array
You can use the `Color::toArray()` method to get all three color values in an ordered list.
```php
Color::new(255, 255, 255)->toArray(); // [255, 255, 255]
```
The array does not use string-keys, so you can unpack the array into separate variables too.
```php
[$r, $g, $b] = Color::new(255, 255, 255)->toArray();
```
### Finding the distance between 2 colors
If you need to calculate the distance between 2 colors, you can use the `Color::distanceBetween()` method.
```php
$one = Color::new(0, 0, 220);
$two = Color::new(255, 0, 220);
Color::distanceBetween($one, $two); // 65_025
```
The return value is the distance between the 2 colors, squared. Generally speaking, this number will be more
readable and recognisable than the radical (result of the square root).
#### Using an existing `Color`
If you already have a `Color` object, you can use the `Color::distanceTo()` method as well.
```php
$one = Color::new(0, 0, 220);
$two = Color::new(255, 0, 220);
$one->distanceTo($two); // 65_025
```
> It is worth noting that the distance calculations and `Color` objects **do not** support alpha-based colors. This is potentially something that will be added in the future.
### Comparing colors
You can compare two colors using the `Color::bothEqual()` method.
```php
$one = Color::rgb('#aaa');
$two = Color::rgb('#aaa');
$three = Color::rgb('#ccc');
Color::bothEqual($one, $two); // true
Color::bothEqual($one, $three); // false
```
You can also compare one color to another using the `equals` method on one of the colors.
```php
$one = Color::rgb('#aaa');
$two = Color::rgb('#aaa');
$three = Color::rgb('#ccc');
$one->equals($two); // true
$one->equals($three); // false
```