Usage
After you have installed PHP-Badges, you can start using it.
Note: In the following examples, the Badges are scaled down due to the limitation of jeckyll (our website generator).
List of contents
Click to expand
Simple usage
To change the badge, you just need to add some parameters to the URL, all* of the parameters can be used together.
All parameters are optional, the default values are:
| Parameter | Default Value |
|---|---|
| label | Documentation |
| message | go.jm26.net/badge-docs |
| color | #97CA00 |
| icon | (f09b - GitHub) |
E.g. https://api.jm26.net/badge?label=Hello&message=World
Label
The Label is the text on the left side of the badge.
To set the label, use the label parameter.
E.g. https://api.jm26.net/badge?label=Hello:
Message
The Message is the text on the right side of the badge.
To set the message, use the message parameter.
E.g. https://api.jm26.net/badge?message=World:
Color
The Color is the background color of the right side of the badge (the message).
To set the color, use the color parameter.
E.g. https://api.jm26.net/badge?color=blue:
Color Codes
PHP-Badges supports HEX color codes and some color names:
Click to expand
**Some colors are only available in newer versions of PHP-Badges.**| Color Name | HEX Code | Preview |
|---|---|---|
| red | #e05d44 | |
| orange | #fe7d37 | |
| yellow | #dfb317 | |
| green | #97CA00 | |
| brighgreen | #44cc11 | |
| cyan | #00eaff | |
| blue | #007ec6 | |
| violet | #7b16ff | |
| pink | #ff69b4 | |
| grey | #555555 | |
| silver | #9f9f9f | |
| lightgrey | #9f9f9f | |
| black | #000000 | |
| white | #ffffff | |
| critical | #e05d44 | |
| important | #fe7d37 | |
| highlight | #dbe300 | |
| ok | #97CA00 | |
| success | #44cc11 | |
| informational | #007ec6 | |
| inactive | #9f9f9f |
Icon
The Icon is the image on the left side of the badge.
To set the icon, use the icon parameter.
E.g. https://api.jm26.net/badge?icon=f179:
Icon Codes
Example Codes:
f179- GitHubf1a0- Googlef179- Applef099- Twitter
All icons are from Font Awesome and the codes can be found here.
Advanced Usage
Image Format
The Image Format is the format of the output image.
There are 3 supported formats: png, jpg and gif.
To set the image format, use the format parameter.
E.g. https://api.jm26.net/badge?format=jpg:
Image Scale
The Image Scale is the scale of the output image.
The maximum scale is 100, numbers can be decimal (e.g. 1.5), but not smaller than 0.1.
To set the image scale, use the scale parameter.
E.g. https://api.jm26.net/badge?scale=2.1: https://api.jm26.net/badge?scale=0.5:
Label Color
The Label Color is the background color of the left side of the badge (the label).
To set the label color, use the labelcolor parameter.
Important: The parameter names are CASE SENSITIVE (e.g. labelcolor is valid, but labelColor is not).
E.g. https://api.jm26.net/badge?labelcolor=blue:
Font Color
The Font Color is the color of the text on the badge (the label, icon and message).
To set the font color, use the fontcolor parameter.
Important: The parameter names are CASE SENSITIVE (e.g. fontcolor is valid, but fontColor is not).
E.g. https://api.jm26.net/badge?fontcolor=blue:
Auto Font Color
The Auto Font Color is the color of the text on the badge (the label, icon and message) that is automatically chosen based on the background color.
For example, if the background color is to light, the font color will be black and if the background color is to dark, the font color will be white.
This feature is enabled by default, but can be disabled by setting the autofontcolor parameter to false.
Important: The parameter names are CASE SENSITIVE (e.g. autofontcolor is valid, but autofontColor is not).
E.g. https://api.jm26.net/badge?autofontcolor=false&color=FFE99A:
Cache Lifetime
The Cache Lifetime is the time in seconds that the badge will be cached for.
To set the cache lifetime, use the cache parameter.
E.g. https://api.jm26.net/badge?cache=3600: - This badge will be cached for 1 hour.
Status of PHP-Badges
The simple Status of the PHP-Badges instance is viewable by anyone and more detailed information is available with a valid password.
To view the simple status, use the status parameter.
E.g. https://api.jm26.net/badge/beta?status:
To view the detailed status, use the status parameter with a valid password. The password is the same as the password for the maintenance mode and the default password is password. PLEASE CHANGE THE PASSWORD! Here is a guide on how to change the password.
E.g. https://api.jm26.net/badge/beta?status=password - The result will be a JSON object with the status information. Here is an example:
Click to view example
{ "status": "ok", "warnings": 0, "message": "Everything is working fine!", "version": { "current version": "1.2.2", "newest version": "1.2.0", "update available": false, "check for updates": true, "update url": "https://github.com/JMcrafter26/php-badges/releases/latest" }, "server": { "server": "Apache", "php": "7.4.33", "directory": "/htdocs/badge", "file": "/htdocs/badge/generate.php", "host": "example.com", "ip": "1.1.1.1", "gd extension": "true" }, "assets": { "font": "true", "icons": "true" }, "external services": { "internet": "true", "github repo": "true", "update server": "true" }, "configuration": { "maintenance mode": false, "icon": "", "label": "Documentation:", "message": "go.jm26.net/badge-docs", "label color": "#555555", "message color": "#97CA00", "color text": "#ffffff", "auto font color": true, "image format": "png", "cachelife": 5, "scale": 15, "resize output": false, "font path": "./DejaVuSans.woff", "icons path": "./font-awesome.woff" } } Status Viewer
A simple status viewer will be available in the future at test.jm26.net/badge-generator/status-viewer.
Screenshot of the status viewer:
Conclusion
That’s it! You now know how to use PHP-Badges!
There are more features coming soon, so stay tuned!
If you haven’t already configured your instance, you can do so here - it is highly recommended that you do so, because the default configuration contains a password that is publicly available.
If you have any questions, or issues, feel free to open an issue on GitHub or contact me directly at contact[at]jm26.net
Made with ❤️ by JMcrafter26
Enjoying PHP-BADGES? Show some love by liking and sharing this repository or support me by buying me a coffee ☕