Currently undergoing maintenance - Some pages may not work as expected

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: 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: 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: 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 red
orange #fe7d37 orange
yellow #dfb317 yellow
green #97CA00 green
brighgreen #44cc11 brighgreen
cyan #00eaff cyan
blue #007ec6 blue
violet #7b16ff violet
pink #ff69b4 pink
grey #555555 grey
silver #9f9f9f silver
lightgrey #9f9f9f lightgrey
black #000000 black
white #ffffff white
critical #e05d44 critical
important #fe7d37 important
highlight #dbe300 highlight
ok #97CA00 ok
success #44cc11 success
informational #007ec6 informational
inactive #9f9f9f inactive

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: f179

Icon Codes

Example Codes:

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: 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: scale=2https://api.jm26.net/badge?scale=0.5: 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: 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: 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: autofontcolor=false

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: 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: 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 ☕

Github Repository Github Releases