Login Cidadao Badges Bundle Laravel Package

Getting Started

First, calibrate expectations. procergs/login-cidadao-badges-bundle is a Symfony bundle, not a Laravel package. It has no Illuminate\Support\ServiceProvider, no Laravel package auto-discovery, and no Blade views. Its job is narrow and specific: it wraps the Login Cidadão OAuth2 authorization flow so you can request badge scopes (selos) and read back certified claims — verified e-mail, government-issued identity, and similar assertions — during authentication. In a Laravel codebase the realistic day-to-day leverage is therefore one of three shapes, in order of likelihood:

1. Reference implementation — you read its BadgeInterface, DI extension, and claim mapping, then reimplement the badge-scope exchange in a Laravel Socialite driver or custom OAuth2 client. This is the common path.
2. Co-resident service — a small Symfony app (or a Symfony kernel embedded via a bridge) owns the Login Cidadão handshake and hands authenticated badge data back to Laravel. Justified only if you already run Symfony somewhere.
3. Direct adoption — only if the project is genuinely Symfony.

Where to look first, in this order:

• The DI extension and Configuration class — this is where the bundle declares its config tree (client credentials, scopes, endpoints). It tells you every knob the package actually supports, which is the fastest way to learn what it does and does not give you.
• BadgeInterface — the 3.0.0 release note is literally "Using new BadgeInterface," so this is the contract the whole package pivots on. It is the extension point and the seam you should copy into your own domain model.
• The OAuth2 client wiring — where the authorization request is built, which scopes are appended, and what the token/claims response is expected to look like.
• Tests, if any — with 2 stars and a 2018-10-09 last release, tests are the only reliable documentation you'll get for edge behaviour.

Minimal adoption steps (Symfony case):

composer require procergs/login-cidadao-badges-bundle:^3.0

Register it in config/bundles.php, then surface its config (client id/secret, authorization and token endpoints, requested badge scopes) into config/packages/. Point it at the Login Cidadão sandbox first, not production.

Minimal steps (Laravel case):

composer require procergs/login-cidadao-badges-bundle:^3.0

Then do not try to boot it. Read the source into app/Services/LoginCidadao/, port the scope-and-claim logic into a Socialite driver or a thin GuzzleHttp client, and define your own Badge value object. Budget half a day for the port; the OAuth2 dance itself is standard authorization-code.

First use case to prove out: request the badge scope for verified e-mail, complete the redirect flow against the sandbox, log the raw claims payload, and map one claim onto a local user. That single path exercises config, the authorization request, the token exchange, claim parsing, and your mapping layer — everything else is repetition.

Implementation Patterns

Wrap the contract, don't consume it raw. Whether you adopt the bundle or port it, the highest-value pattern is a first-party interface mirroring BadgeInterface so application code depends on your type, not the vendor's. One adapter class implements the vendor contract and translates into your domain object. This costs an hour now and makes the next major bump (and there will be one — 3.0.0 was itself a breaking interface change) a single-file edit. It also means your badges render in tests without an OAuth round-trip.

Treat badge scopes as configuration, not code. Build a config array of which certified attributes you require, mapped to which scope strings and which local user fields they satisfy. A config/login-cidadao.php with scopes and a claims => user_attribute map keeps the certified-attribute surface auditable and lets you add "government ID" later without touching the flow. It also gives you a single place to diff when the upstream scope naming drifts.

Map claims at the boundary, once. Do the claims-to-user translation in one service (BadgeClaimMapper or similar), called from your callback controller. Everything downstream — login, profile enrichment, gating premium features — consumes the mapped user, never the raw payload. Raw claim arrays are nested, variant, and the least stable part of the integration; leaking them is how claim-shape changes become 500s in unrelated code.

Render badges through a single Blade component. If badges surface in the UI (verification checkmarks, identity chips), one <x-verified-badge :type="..." /> component with the SVG/CSS inside, plus a view:cache-friendly path. Cache the rendered HTML per badge set — the markup is static and the cost is in repeated rendering, especially if badges appear in notification or e-mail fan-out.

Snapshot the rendered output in tests. For a package whose only release note is an interface change, characterisation tests are your upgrade safety net. Assert rendered strings and mapped-claim arrays pre-upgrade, then re-run post-upgrade. Interface changes compile cleanly and break behaviourally; only exercised call paths catch that.

Two-phase rollout for the version bump. Package code and application code must ship in the same release, or an instance running old code will autoload new package code and fatal on a signature mismatch. Rolling deploys make this a real class of production incident — order the rollout deliberately.

Keep a thin kill switch. A config flag that bypasses Login Cidadão badges and falls back to unverified state. With a 2018-dated, 2-star dependency, you want to be able to turn the integration off without a code deploy if the upstream endpoint misbehaves.

Gotchas and Tips

Symfony bundle ≠ Laravel package, and this will bite immediately. There is no service provider, no config/app.php registration, no vendor:publish. composer require succeeds and then nothing happens — no error, no wiring. If you expect Laravel auto-discovery you will spend an hour debugging silence. Decide up front that you're porting, not installing.

Last release 2018-10-09 means version floors, not bugs. Assume a PHP 7.x-era codebase and Symfony 3/4 constraints. On PHP 8 you'll hit the interesting failure modes: interface signatures that don't match, nullable/return-type violations, and — most insidiously — named-argument breakage if any parameter was renamed, which is a silent runtime fatal rather than a static-analysis catch. Check composer.json for the PHP and Symfony constraints before you write a line of code.

BadgeInterface in 3.0.0 is breaking, full stop. The release note is one sentence. Semver obliges you to treat the interface as removed-or-changed until proven otherwise. Before upgrading an existing install, diff the interface method surface — signatures, parameter names, return types, nullability — against every implementation. If you're greenfield, implement against the interface and pin ^3.0 with an explicit upper bound; never float on *.

Login Cidadão is a Brazilian government identity provider. Scopes, endpoints, and the badge taxonomy (selos) are defined upstream by PROCERGS, not by this package — and the package is a thin wrapper. When behaviour looks wrong, the primary source is Login Cidadão's own OAuth2 documentation, not the bundle. Get sandbox credentials and validate the full redirect flow there before touching production.

Do not trust a claim just because it arrived. "Verified e-mail" is an assertion by the issuer. Consume it via the server-side token exchange only, never from a query parameter or a client-supplied field, and confirm the token response is the authority. The bundle handles the flow; it does not audit your trust boundaries.

Debug the raw token response, once, deliberately. Log the decoded claims payload behind a debug flag on first integration. Nested claim structures and optional attributes are the number-one source of "it worked for me" — a field you assumed is always present will be absent for users with partial certification. Fail soft (unverified) rather than throwing.

Stale compiled views are a plausible post-deploy failure. In Laravel, if badge markup was cached or views were compiled against an old class reference, you get confusing errors that only appear on badge-rendering paths — i.e. production, on the least-tested route. Make php artisan view:clear (and config:clear) part of the deploy pipeline alongside any version bump.

No migration guide exists. There is no UPGRADE.md, no deprecation shim referenced, no changelog depth. Write your own one-pager after the port — what you changed, which claims you consume, where the adapter lives. That document is the artefact that makes the next upgrade cheap, and given the maintainer cadence, there will be a next upgrade.

Extension point is the interface and nothing else. Don't subclass internals or reach into the DI container for bundle services — that couples you to implementation detail the maintainer has already shown willingness to change at a major version. Implement the contract, delegate to it, and keep everything else behind your adapter.

Assign an owner. A 2-star, single-line-release-note dependency with a 2018 last release is community-supported at best. That's fine — it's presentation-layer, and the exit cost is low if your adapter boundary is in place — but an unowned package with a breaking-change history is how you end up six months behind on a security advisory.