Merged
Conversation
Refresh the README around a clearer value proposition, with new sections that answer 'What is Swap?', 'When should you use Swap?', 'Why not call an exchange rate API directly?', and 'Which package should I use?'. Replace the introductory provider name-drops and quickstart with a neutral default (european_central_bank, free, no API key) so the example works end-to-end without external accounts. Reorganize the providers table into Public vs Commercial groups and add the registry-identifier column so the string passed to Builder::add() is documented. Simplify the Fixer rows. Fix the stale FlorianvSwapBundle links (now florianv/symfony-swap) and the 'Ukranie' typo. Cross-link to Exchanger, Laravel Swap, and Symfony Swap. Update composer.json description and keywords for Packagist SEO. No runtime changes; public API of Swap and Builder is unchanged.
Rewrite doc/readme.md around clearer structure: 'About this documentation' intro, modernized installation (PSR-18 first, Guzzle 7 alternative), neutralized configuration examples (european_central_bank as default), explicit 'How the fallback chain works' paragraph (skip / retry / ChainException), a minimal Symfony Cache PSR-16 example before the Predis + bridge example, and an updated HTTP request caching example using Guzzle 7 instead of the EOL guzzle6-adapter. Replace the legacy 'Supported Services' code dump with a focused 'Provider configuration' table that maps each commercial identifier to its required option (api_key, access_key, app_id, token, api-key) and optional flags (enterprise, paid). Public providers and the array fixture are documented separately. The full provider list with capabilities now lives in the README's Providers table; the doc points to it instead of duplicating it. Add a short FAQ at the end (what happens when every provider fails, can I use Swap without an API key, how do I cache rates, etc.) for faster scanning and easier reference. Add light, professional emojis to section titles in both README.md and doc/readme.md to aid visual scanning. Emojis are restricted to top-level sections; paragraphs, code blocks, and tables remain plain. No runtime changes; documentation only.
- Rewrite the 'Why not call an exchange rate API directly?' section
with a clearer framing (single API vs Swap), shorter bullets, and
a closing note that calling a single API can be enough for simple
cases.
- Add a one-line onboarding sentence at the top of the Providers
section ('start with a single provider, then add others as needed').
- Reduce repetition of the '30 providers' phrasing in the intro and
in the 'What is Swap?' section; the count is kept in the tagline
and in the Providers section where it is most informative.
- Add light emojis to the remaining top-level sections (Sponsorship,
Contributing, License, Credits) for consistency with the rest of
the README.
Add three orientation sections at the top of the doc so a developer or
search engine landing on doc/readme.md directly gets the same value
proposition as the README:
- 'What is Swap?' (factual, ~5 lines)
- 'When should you use Swap?' (factual, ~3 lines)
- 'Why not call an exchange rate API directly?' (mirrors the README
verbatim so the canonical phrasing is consistent across both surfaces)
Drop the 'About this documentation' meta section; its orientation role
is taken over by the three sections above.
Compact 'Per-query options' from three sub-headings (cache_ttl, cache,
cache_key_prefix) into a single options table plus one example block.
Same information, denser and easier to scan.
Trim the prose around the HTTP request caching example.
Add one FAQ entry: 'How does Swap relate to Exchanger?' that points to
the README's 'Which package should I use?' section, so the doc covers
the ecosystem map without duplicating it.
Update the index to reflect the new section order and the emoji-prefixed
anchors.
Net length: roughly the same as before; structure is clearer, the doc
stands on its own for a discovery-stage reader, and vocabulary is
aligned with the README ('currency conversion library', 'exchange rate
provider', 'fallback chain', 'caching').
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
README
european_central_bank, free, no API key). The example shows// EUR → USD exchange ratefollowed by an explicit$amount * $rate->getValue()step so the conversion is unambiguous.Builder::add(), sourced fromExchanger\Service\Registry.apilayer_fixerfor "Fixer (APILayer)",fixerfor "Fixer (direct)").FlorianvSwapBundlelinks (they now point toflorianv/symfony-swap).Ukranietypo.doc/readme.mdsymfony/http-client, Guzzle 7 alternative noted;php-http/curl-clientis no longer the recommended path).european_central_bankas the default, no commercial provider name-drops).ChainExceptionafter all collected exceptions).ExchangeRate.guzzle6-adapter.api_key,access_key,app_id,token,api-key) and optional flags (enterprise,paid). Public providers and thearrayfixture are documented separately. The full provider list with capabilities now lives in the README's Providers table; the doc points to it instead of duplicating it.composer.jsoncurrency conversion,currency conversion library,php currency conversion,exchange rate api,forex,forex api).Why
What did NOT change
Swap\SwapandSwap\Builderis unchanged.src/,tests/, CI, Psalm config, or php-cs-fixer config.