Citygov Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no config/citygov.php, no Eloquent integration, and no facade. If you are a Laravel developer, the realistic "getting started" path is one of two routes:

1. Bridge route – Run the Symfony app that consumes this bundle alongside your Laravel app (shared Solr cluster, shared auth, GraphQL as the contract), and call its GraphQL endpoints from Laravel via Http::post(...).
2. Adopt route – Accept that you are writing Symfony code for the CityGov domain, and treat your knowledge of Laravel's DI/console/HTTP layers as transferable but not portable.

Minimal steps once you're inside a Symfony app:

composer require atoolo/citygov-bundle

• Register the bundle in config/bundles.php (it will appear under the Atoolo\CityGov namespace).
• Read the atoolo/search-bundle docs first — CityGov builds on top of the search infrastructure (Solr indexing, DocumentEnricher, ContentCollector, GraphQL search features). Most of your debugging will happen there.
• The bundle's own docs live at https://sitepark.github.io/atoolo-docs/develop/bundles/citygov/ — that should be your first tab open.
• First use case to prove out: index a CityGov OnlineService into Solr and fetch it back through the GraphQL OnlineServiceFeature. That exercises the whole pipeline (content collection → enrichment → indexing → GraphQL expose) and confirms your Solr config before you touch person search.

Implementation Patterns

Because the bundle is a set of Symfony services and GraphQL schema extensions, the day-to-day patterns are event-driven and schema-driven rather than controller-driven.

Content collection + document enrichment The bundle contributes index documents (one per content item; per alternative title if configured). The pattern is:

• A ContentCollector gathers raw content.
• A DocumentEnricher (citygov-specific) fills fields like sp_meta_string_leikanumber, startletter, phone number, full-text content.
• Your job as an integrator is usually configuring which enrichers run and extending the schema for fields you care about, not writing the collector.

GraphQL as your public contract CityGov exposes OnlineServiceFeature (with an OnlineService list), teaser online-service features, and CityGov person search/suggest. This is where a Laravel backend should integrate: treat the bundle's GraphQL schema as the API surface and consume it from Laravel with Lighthouse or a plain HTTP client. Do not try to reuse the PHP classes — the value is the schema, not the code.

Person search & suggest (v1.5+ / v1.6+) Sort criteria were added in 1.6.0. Pattern: define your person index fields, expose search + suggest resolvers, and drive employee-directory UIs. From Laravel, this is just another GraphQL query with arguments — no coupling required.

Online service links via LinkFactory v1.5.0 switched online-service link generation to the shared LinkFactory, so URLs are resolved consistently across the bundle. If you generate links yourself in Laravel, mirror this — don't hardcode link templates, or your URLs will drift from what the Symfony side produces.

Integration tip for Laravel teams: keep the Symfony app as a read/index service (Solr + GraphQL) and keep writes/UI in Laravel. This gives you the bundle's search features without importing Symfony's request lifecycle into your codebase.

Gotchas and Tips

• It is not for Laravel. No service provider, no auto-discovery. Do not attempt to load the bundle's config through AppServiceProvider — the services are wired via Symfony DI and will not resolve.
• Hard Solr dependency. Nothing meaningful works without a running Solr cluster and index. Budget for that first; it's the usual source of "bundle doesn't work" reports.
• Tight version coupling with atoolo/search-bundle. Release 1.5.0 explicitly bumped to ^1.14.0. Treat them as a pair and pin both; mismatched versions are the most likely cause of runtime DI errors.
• PHP version is constrained but permissive within a range: 8.1 is present but "no longer checked automatically"; active CI covers 8.2 / 8.3 / 8.4. Run 8.2+ if you want support.
• Umlaut handling in startletter. There is a specific fix ensuring indexing works without umlauts. If you build A–Z navigation in a Laravel frontend off a facet, normalize yourself — don't assume the index value matches the display letter.
• Alternative-title indexing is config-dependent (added in 1.4.0). If you're surprised by duplicate or missing search results, check that config flag before assuming a bug.
• Archive settings are configured, not automatic (see the add config to archive settings chore). Documents that never "disappear" from search are usually an archive-config issue, not an indexing one.
• Debugging entry points: the Solr index itself (inspect the raw document fields first — sp_meta_string_leikanumber, phone, startletter), then the enricher pipeline. If a field is wrong, it's almost always the enricher, not GraphQL.
• Extension points you'll actually use: custom document enrichers, GraphQL schema extensions, and the shared LinkFactory — in that order of frequency. Adding enrichers is the cleanest way to inject your own fields without forking the bundle.
• Read the release notes before upgrading. Every 1.x release carries behavior changes (link generation, phone-number field, sort criteria). There is no semver guarantee that a minor bump is silent for integrators.
• Stars = 0, dependents = 0. This is a vendor-driven bundle for Sitepark's CityGov product. There is no community to lean on — your support path is Sitepark's docs and their e2e test repo, not Stack Overflow. Plan accordingly before making it a critical dependency.