diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7c4b445 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,135 @@ +# AGENTS.md + +Guidance for coding agents working on this repository. + +## Project Overview + +This is `badges/poser`, a PHP library and CLI tool that generates Shields-style SVG badges. It is used by `https://poser.pugx.org`. + +Core areas: + +- `src/Badge.php`: parses badge input/URIs, normalizes colors, escaping, style, format, label color, and logo options. +- `src/Poser.php`: main facade that maps badge styles to renderers. +- `src/Render/`: SVG renderers and shared local-template rendering logic. +- `src/Resources/templates/`: SVG templates for each style. +- `src/Calculator/`: text width calculators used to size badges. +- `src/UI/` and `bin/poser`: Symfony Console CLI entrypoint. +- `tests/`: PHPUnit tests and SVG fixtures. +- `features/`: Behat CLI scenarios and fixtures. +- `doc/`: generated example badge images. + +The package is PSR-4 autoloaded under `PUGX\Poser\`. + +## Requirements + +- PHP `^8.1` +- Composer +- PHP extensions: `gd`, `simplexml` +- Docker Compose is the preferred reproducible development path. + +The current Makefile defaults to `CONTAINER=php84`. The README still mentions `php83` in a few places, so treat `Makefile`, `composer.json`, and CI workflows as the more current sources of truth. + +## Common Commands + +Install/update dependencies in Docker: + +```bash +CONTAINER=php84 make setup +``` + +Run the full local Makefile test target: + +```bash +CONTAINER=php84 make tests +``` + +This runs: + +- PHP-CS-Fixer dry run +- PHPUnit +- Behat + +Useful focused commands: + +```bash +bin/phpunit +bin/phpunit tests/Render/SvgFlatRenderTest.php +bin/php-cs-fixer fix --verbose --diff --dry-run +bin/php-cs-fixer fix +php -d error_reporting='E_ALL & ~E_DEPRECATED' bin/behat --snippets-for +bin/psalm +composer validate +``` + +Docker equivalents: + +```bash +docker compose run --rm php84 bin/phpunit +docker compose run --rm php84 bin/php-cs-fixer fix --verbose --diff --dry-run +docker compose run --rm php84 php -d error_reporting='E_ALL & ~E_DEPRECATED' bin/behat --snippets-for +``` + +Generate documentation badge SVGs: + +```bash +make doc-images +``` + +## CI Expectations + +GitHub Actions runs: + +- PHP-CS-Fixer on PHP 8.1 +- PHPUnit on PHP 8.1, 8.2, 8.3, and 8.4 +- `composer validate` +- Commit linting on pull requests + +Before a PR, run the most relevant local tests plus CS checks. For broad changes, prefer `CONTAINER=php84 make tests`; for compatibility-sensitive changes, run the matrix target or targeted Docker services. + +## Coding Style + +- Follow the existing PHP style and namespace layout. +- PHP-CS-Fixer config is in `.php-cs-fixer.php`. +- The rule set is Symfony-based with PHP 8.1 migration rules and risky rules enabled. +- Source files generally do not declare strict types, while newer tests do. Match the surrounding file style. +- Prefer constructor injection already used by renderers, especially for text calculators and template paths. +- Keep renderer classes small; shared behavior belongs in `LocalSvgRenderer` or `SvgBaseRenderer` when it applies to multiple styles. + +## Testing Notes + +- PHPUnit fixtures compare generated SVG output, often exactly after template rendering. Small whitespace or sizing changes can be behaviorally significant. +- Renderer tests commonly mock `TextSizeCalculatorInterface` to stabilize dimensions. +- Behat scenarios exercise CLI behavior and compare output similarity. +- If you change URI parsing, escaping, colors, logos, label colors, sizing, or template placeholders, update/add focused PHPUnit coverage and consider the Behat CLI path. +- If you change SVG templates, update affected fixtures under `tests/Fixtures/` and generated docs only when intentional. + +## SVG Rendering Notes + +- `LocalSvgRenderer::render()` loads a style template, builds replacement parameters, replaces `{{ name }}` placeholders, normalizes whitespace, validates XML, and returns an `Image`. +- Templates live in `src/Resources/templates/{style}.svg`. +- Supported styles currently include `flat`, `flat-square`, `plastic`, `for-the-badge`, and `social` in code, tests, templates, and README examples. +- Badge color names are mapped in `Badge::$colorScheme`; arbitrary 3- or 6-digit hex values are also accepted. +- Logo handling supports SVG path data, `data:image/...`, base64 SVG data URLs, and HTTP URLs. + +## Dependency Hygiene + +- Do not edit `vendor/`. +- Do not commit `.php-cs-fixer.cache`, `.php_cs.cache`, coverage output, or IDE files. +- Composer dependencies are sorted by config; use Composer commands rather than hand-editing lockfile content. + +## Git and Contribution Notes + +- Commit messages must always follow Conventional Commits. +- Branch names created for repository work must follow the same Conventional Commits intent, using a lowercase type prefix and short kebab-case description, for example `docs/documentation-alignment`, `fix/logo-query-encoding`, or `feat/social-badge-docs`. +- Preserve existing user changes in the worktree. Check `git status --short` before editing and avoid unrelated rewrites. +- Keep changes narrowly scoped. This library relies on stable SVG output, so avoid opportunistic refactors around rendering unless they are needed for the task. + +## Quick Orientation Checklist + +When starting future work: + +1. Run `git status --short`. +2. Read the relevant source and matching tests/fixtures before editing. +3. For renderer changes, inspect both `src/Resources/templates/` and `tests/Fixtures/`. +4. Run the narrowest useful PHPUnit test first. +5. Run CS fixer dry run and broader tests when the change touches shared rendering, parsing, CLI behavior, or dependencies. diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f22c4b..19cfb16 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,20 @@ +## [v3.4.0] - 2026-05-26 + +### Added +* add `labelColor`, `logo`, and `logoColor` URI options for generated badges +* add the `social` badge style +* add support for 3-digit hex colors +* update Docker documentation + +### Changed +* SVG template placeholders `vendorStartPosition` and `valueStartPosition` were replaced by `vendorStartX` and `valueStartX`; custom templates must be updated accordingly +* SVG rendering now exposes additional template placeholders for logo-aware layout and social badge geometry + +## [v3.3.0] - 2025-12-09 + +### Added +* add support for Symfony 8.x + ## [v3.2.0] - 2025-10-13 ### Added @@ -172,6 +189,9 @@ - stable release for poser +[v3.4.0]: https://github.com/badges/poser/tree/v3.4.0 +[v3.3.0]: https://github.com/badges/poser/tree/v3.3.0 +[v3.2.0]: https://github.com/badges/poser/tree/v3.2.0 [v3.1.0]: https://github.com/badges/poser/tree/v3.1.0 [v3.0.0]: https://github.com/badges/poser/tree/v3.0.0 [v2.3.1]: https://github.com/badges/poser/tree/v2.3.1 diff --git a/README.md b/README.md index 02e7483..d33c42e 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,8 @@ Choose a different style poser license MIT blue -s "for-the-badge" ``` +The available styles are `plastic`, `flat`, `flat-square`, `for-the-badge`, and `social`. + You can also use the provided Docker Compose services: ```bash @@ -79,7 +81,48 @@ $image = $poser->generate('license', 'MIT', '428F7E', 'plastic'); echo $image->getStyle(); ``` -The allowed styles are: `plastic`, `flat`, `flat-square`, and `for-the-badge`. +The allowed styles are: `plastic`, `flat`, `flat-square`, `for-the-badge`, and `social`. + +## Badge customization + +Badges generated from a URI support these query string options: + +| Option | Description | +| --- | --- | +| `style` | Badge style: `plastic`, `flat`, `flat-square`, `for-the-badge`, or `social`. | +| `labelColor` | Color for the left side of the badge. Accepts named colors, 6-digit hex, or 3-digit hex. | +| `logo` | Optional logo as an image URL, `data:image/...` URI, or SVG path data. | +| `logoColor` | Color used when `logo` is SVG path data. Defaults to white. Accepts named colors, 6-digit hex, or 3-digit hex. | + +Examples: + +```php +echo $poser->generateFromURI('license-MIT-blue.svg?style=social'); +echo $poser->generateFromURI('build-passing-brightgreen.svg?labelColor=555'); +echo $poser->generateFromURI('github-stars-333.svg?style=social&logo=https%3A%2F%2Fexample.com%2Fgithub.svg'); + +$logo = rawurlencode('M12 2L2 22h20L12 2z'); +echo $poser->generateFromURI('php-8.4-777.svg?logoColor=blueviolet&logo=' . $logo); +``` + +When these options are used in a URL, encode reserved characters. In particular, encode `#` as `%23`, and encode full image/data URLs passed as `logo`. + +The CLI currently exposes style selection with `--style`; `labelColor`, `logo`, and `logoColor` are available through URI-based generation. + +## Custom SVG templates + +Since `v3.4.0`, SVG templates use `vendorStartX` and `valueStartX` instead of the old `vendorStartPosition` and `valueStartPosition` placeholders. If you maintain custom templates, update them before upgrading: + +```diff +- {{ vendorStartPosition }} +- {{ valueStartPosition }} ++ {{ vendorStartX }} ++ {{ valueStartX }} +``` + +These values are the text center positions multiplied by 10 and are intended to be used with `transform="scale(.1)"`, as the bundled templates do. + +The renderer also provides these optional template placeholders: `vendorUpper`, `valueUpper`, `vendorTextLength`, `valueTextLength`, `vendorWidthMinus1`, `valueWidthMinus1`, `valueRectX`, `separatorX`, and `logoElement`. ### Examples (generated with `make doc-images`)