Getting Started

First, the obvious: this is a Symfony bundle, not a Laravel package. stgbundle/cas-bundle ships a *Bundle.php class, DependencyInjection/, and Resources/config — it will not install or boot inside a Laravel app. If you're working in Laravel, stop here and look at apereo/phpcas or a CAS/OIDC socialite provider instead. Everything below is for the Symfony side of the house (or a Laravel team that also maintains a Symfony service).

Install and confirm what you actually got. This is a small, low-traffic bundle, so the first job is verifying it works in your Symfony version before you build on it. Release 8.0 explicitly targets Symfony 7.4, which almost certainly means PHP 8.2+ and a dropped 5.4/6.x support matrix — check before you composer require on a 6.4 LTS app.

composer require stgbundle/cas-bundle

Then immediately:

Check vendor/stgbundle/cas-bundle/composer.json for symfony/* and php constraints and the PSR-4 namespace — the package name (stgbundle/cas-bundle) rarely matches the PHP namespace, and you'll need the namespace for every service reference. In 8.0 expect symfony/framework-bundle: ^7.4 and a hard PHP floor.
Look for the bundle class (*Bundle.php) and register it in config/bundles.php. Many small bundles ship without Flex recipes, so auto-registration may not happen.
Run php bin/console config:dump-reference <alias> (try the vendor name lowercased with underscores, e.g. stg_cas, then cas) to discover the real config tree. Also check config/routes/ or php bin/console debug:router | grep -i cas for a shipped CAS route/controller.
Open the bundle's DependencyInjection/Configuration.php and Extension.php — for an obscure bundle this is the documentation. Ten minutes there beats an hour of guessing. Given the 8.0 release notes are a single Portuguese line ("Bundle de cas para symfony 7.4"), the source remains the only reliable spec.

First use case: gate a firewall on CAS. The typical shape is a Symfony security firewall pointing at the bundle's authenticator or entry point:

# config/packages/security.yaml
security:
    firewalls:
        main:
            pattern: ^/
            custom_authenticators:
                - stg_cas.authenticator   # confirm the actual service id via debug:container
            entry_point: stg_cas.authenticator

Then hit a protected route in a private window and watch /var/log/dev.log and the _security.* entries in the profiler. That single round-trip is the fastest way to learn what the bundle actually does: redirect to CAS, ticket validation on return, and what it writes into the token.

Set the three things that are always environment-specific up front: the CAS server base URL, the service URL (the absolute callback URL as CAS sees it), and the validation endpoint. Get those wrong and you get opaque "ticket invalid" failures later.

Implementation Patterns

Config-first, code-second. Put server URL, service base URL, and validation path in config/packages/<vendor>.yaml with %env()% references, and keep a .env entry per environment. Everything else (attribute mapping, redirects) should hang off that. On 8.0, dump the reference tree once into version control as a comment so the next major bump shows you a diff.

User provisioning on ticket validation. The common pattern is a listener or a custom user provider that takes the CAS attributes (usually under cas:attributes after parsing) and maps them to your User entity:

// Typical flow inside whichever hook the bundle exposes
// (authenticator, event subscriber, or user provider)
$username = $ticket->getAttribute('uid') ?? $ticket->getAttribute('mail');
$user = $userRepository->findOneBy(['casId' => $username])
    ?? $this->provisionFrom($ticket);

If the bundle already returns a generic CasUser, wrap it: register your own UserProvider or decorate the bundle's service, and map CAS attributes into your real entity. Don't scatter $user->getAttribute() calls through controllers.

Redirect hygiene. Keep a target_path / _target_path in the session before the CAS redirect and restore it after login. If the bundle doesn't do this, an AbstractAuthenticationListener-style listener or a small subscriber on the login-success event is the cleanest place.

Single logout and ticket lifecycle. CAS sessions live outside Symfony. The typical integration is:

On Symfony logout, redirect to the CAS logout endpoint with service set to your homepage, so the central session dies too.
Accept the small window where a stale CAS ticket exists by relying on CAS's own single-use guarantee rather than trying to re-validate.

Testing without a CAS server. Wrap the bundle's validation client behind an interface you control (or decorate the service), and in test env bind a fake that returns canned ticket attributes. That's the only sane way to get functional tests green in CI.

# config/services_test.yaml
services:
    stg_cas.client:
        class: App\Tests\Fake\FakeCasClient

Local development. Run a cas container (e.g. Apereo CAS or apereo/cas) via Docker Compose alongside Symfony, with both on the same host so the service URL can actually be reached by CAS. Otherwise every local login attempt dies on the callback.

Version pinning as a pattern. Because majors here move with the Symfony release train, pin to "stgbundle/cas-bundle": "8.0.*" (not ^8.0 if you're conservative) and treat every bump as a review event, not a CI auto-merge.

Gotchas and Tips

8.0 is a major bump with a one-line changelog — diff it. The release note names Symfony 7.4 and nothing else, which in practice means: PHP floor raised, older symfony/* constraints dropped, and possibly renamed config keys or service ids. Before upgrading an existing app:

git diff v7.x..v8.0.0 -- DependencyInjection Resources/config config
php bin/console config:dump-reference stg_cas > /tmp/cas-after.yaml
# compare against the reference tree you dumped before upgrading

If your app is on Symfony 6.4 LTS, this release is not for you — the 7.x line is your terminal branch unless you upgrade the framework first. That's a scheduling decision, not a bundle one.

The service URL must match byte-for-byte. CAS validates the ticket against the exact callback URL, including scheme, host, port, and trailing slash. Behind a proxy or Docker network, Symfony may generate http://localhost:8080 while CAS saw https://app.example.com. Fix it explicitly:

# config/packages/<vendor>.yaml
framework:
    trusted_proxies: '%env(TRUSTED_PROXIES)%'
    trusted_hosts: ['%env(TRUSTED_HOSTS)%']

...and set the service URL from an env var rather than letting it be inferred.

Low-maintenance package = pin and monitor. Thin downloads and no dependents means the bus-factor is one maintainer, and the 8.0 release note is literally one sentence in Portuguese. Pin to an exact version with a comment explaining why, and check the repo's issue tracker and tag date when upgrading Symfony. Don't assume BC promises across majors — the jump from 7.x to 8.0 is the evidence.

Ticket validation SSL failures. Most "ticket invalid" surprises are actually TLS: expired cert on the CAS server, or the bundle's HTTP client verifying against a CA it doesn't trust in your container. Check the underlying HTTP client error, not just the authentication exception — the bundle may swallow it. Symfony 7.4's HttpClient + framework.http_client config is the place to inject a CA bundle or a scoped mock.

debug:container and debug:event-dispatcher are your friends. With no README you'll be inspecting:

php bin/console debug:container --tag=security.authenticator
php bin/console debug:event-dispatcher | grep -i cas
php bin/console config:dump-reference stg_cas
php bin/console debug:config stg_cas

Re-run all four after the upgrade — Symfony 7.4's container changes (attribute-based config, removed aliases) can silently break service ids that "just worked" on 6.x.

Session and firewall interplay. CAS login writes into the Symfony session; if you have session.firewall configured or multiple firewalls, make sure the CAS firewall has its own or shared context explicitly. A context: main reference on the right firewall prevents "user disappears after login" bugs.

Attribute names are CAS-server specific. uid, mail, cn, eduPersonPrincipalName vary between Apereo, Shibboleth-backed CAS, and internal instances. Don't hardcode attribute keys in the authenticator; put them in config so switching CAS servers is a YAML change.

Extension points to prefer. Before forking the bundle, check whether it exposes:

an event dispatched after successful authentication (subscribe, don't override),
an interface for the ticket validator/client (decorate it),
a configurable UserFactory or provider.

If none exist, the surgical option is a compiler pass that swaps a service by id, or a small adapter service around the bundle — that keeps future major-version upgrades survivable, which matters more now that majors track Symfony releases.

Watch the return URL after login. If the bundle redirects to / regardless of the original request, users hitting deep links will be annoyed. Restoring _target_path yourself is generally the highest-value patch you'll make to a bundle like this.

Cas Bundle Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips