Citygov Bundle Laravel Package

Product Decisions This Supports

Build vs. buy for public-sector portals. atoolo/citygov-bundle is a pre-built integration layer for Sitepark's CityGov product family — municipal and district administration websites plus employee intranets. It ships domain objects most teams would otherwise build from scratch: online-service records and links, person/contact directories with search and suggest, teaser/GraphQL projections, and search-index documents enriched with full text, alternative titles, and sort-friendly keys (e.g. startletter normalized without umlauts). That is a strong argument for buy/adopt on the content-and-search half of a government portal, and for build only on the citizen-facing frontend where differentiation actually lives.

The Laravel caveat is the first decision. This is a Symfony bundle, not a Laravel package. It registers services, config, and document-enrichment hooks into the Symfony container and the atoolo/search-bundle + atoolo/resource-bundle indexing pipeline. In a Laravel codebase the realistic adoption paths are:

1. Standalone Symfony service for CityGov content ingestion/indexing, consumed by the Laravel app over HTTP or GraphQL. Cleanest separation, most operationally honest.
2. Solr/OpenSearch index as the contract — run the bundle's indexer in the Symfony service, query the index from Laravel. Good when Laravel only needs search + person lookup.
3. Direct in-Laravel use — not supported; would mean porting service wiring and enrichment hooks. Treat as a rewrite, not an integration.

Roadmap sequencing it enables.

• MVP portal: online services + person directory + search/suggest. These are the features with the most release churn (1.5.0 added person search/suggest and link-factory'd service links; 1.6.0 added person sort criteria) — i.e. the vendor is actively hardening exactly what an MVP needs.
• Headless / omni-channel: the OnlineServiceFeature GraphQL projection (1.3.0 teaser, 1.4.0 service list) is the integration point for mobile apps, chatbots, and third-party portals. This is the highest-leverage feature for a Laravel team: GraphQL is the seam that makes the Symfony/Laravel split invisible to product.
• SEO and discoverability: one index document per alternative title (1.4.0) plus index-level full-text enrichment means better landing-page coverage for ordinances, events, and service pages without bespoke SEO plumbing.
• Deferred: multi-language, accessibility conformance, eID/eIDAS signature flows — none are visible in the release history, so budget them as your own work.

Use cases this actually unlocks: consolidating legacy municipal CMS instances onto one API-first platform; employee intranets with searchable staff directories and role-scoped service catalogs; citizen self-service for permits, registrations, and fee payments where the catalog is CityGov-managed and the transaction is yours.

What it does not decide for you: frontend framework, auth/identity, payments, workflow/back-office case handling, or hosting sovereignty. Those remain product decisions the bundle is silent on.

When to Consider This Package

Adopt when all of these hold:

• The customer or programme is actually a CityGov site — the bundle is a companion to Sitepark's product, not a general government toolkit. If you are not on CityGov (or migrating to it), most of its value evaporates.
• You have, or will stand up, a Symfony runtime (Symfony 6.3/7.x, PHP 8.1–8.4) alongside your Laravel app, and you accept a two-service architecture.
• Search is a first-class requirement — person lookup, faceted service search, suggest-as-you-type — and you want the Solr/atoolo/search-bundle conventions rather than designing a schema yourself.
• You need German public-sector content shapes (Leistungsnummer/leikanumber metadata, umlaut-normalized sort keys, alternative-title indexing) and would otherwise reverse-engineer them.
• Headless delivery is on the roadmap and GraphQL is an acceptable contract.

Evaluate, but proceed with eyes open, when:

• You are a Laravel-only shop. The integration cost is a Symfony service, its deployment, and its upgrade cadence — price that in before comparing against a native Laravel search stack (Meilisearch/Typesense + a small domain model).
• You need long-term vendor independence. MIT license is genuinely permissive, and PHPStan level 9 + E2E tests signal real engineering discipline, but the package is effectively single-vendor: 0 stars, 0 dependents, all commits from Sitepark staff. It is a product component, not a community library. Assume you are buying a relationship, not just code.
• You must support non-German locales or accessibility certification — verify before committing; neither is evidenced in releases.

Look elsewhere when:

• The project is private-sector, e-commerce, or a general CMS — use Sylius, Strapi, or a plain Laravel + CMS pairing.
• You need a pure Laravel dependency. There is no Laravel service provider, no facade, no published config in Laravel idioms; every integration is hand-built.
• You cannot run a second runtime (small team, single-platform ops mandate, hard serverless constraint).
• You require stable long-term support guarantees — the 1.x line is moving fast (five minor releases, dependency bumps to atoolo/search-bundle ^1.14), which is healthy but means pinning and regression testing on every bump.
• Frontend is fully bespoke React/Vue against a headless CMS — you would be paying for indexing machinery you then bypass.

Minimum due-diligence checklist before adoption: pin a version and read its release notes; confirm the atoolo/search-bundle and resource-bundle versions you inherit; get a written support/upgrade commitment from Sitepark; and prototype the Laravel↔Symfony GraphQL seam end-to-end in a spike before it enters a roadmap.

How to Pitch It (Stakeholders)

To executives — one paragraph. CityGov is the incumbent platform for municipal and district administration portals in the German-speaking market, and this bundle is the ready-made integration layer for it. Adopting it lets us ship a compliant, searchable public-service portal in a fraction of the time a greenfield build would take, because the hard domain details — service catalogs, staff directories, official reference numbers, German text normalization, SEO-oriented indexing — are already solved and actively maintained. The license is MIT, so there is no licensing cost or lock-in on the code itself. The real commitment is architectural: it runs on Symfony, so we operate it as a dedicated content-and-search service behind our Laravel application rather than mixing it into the app. That is a deliberate, bounded decision with a well-understood interface — GraphQL and a search index — and it is reversible if needed.

To engineering — the honest version. This is a Symfony bundle with real rigor: PHPStan level 9, E2E tests, codecov, PHP 8.1 through 8.4 supported, clean release notes. It is also a vendor-owned component: zero stars, zero dependents, one committer organization, and a dependency chain into atoolo/search-bundle that moves independently of us. So: we adopt it as an external service we control the boundary of, not as a library we sprinkle through the codebase. Concretely — run the CityGov indexing stack in its own Symfony deployment, expose GraphQL for online services and person search, let Laravel own auth, UX, transactions, and business workflow, and treat the Solr schema as a versioned contract. Pin versions, add contract tests on the GraphQL surface, and re-run them on every atoolo/* bump. If the spike shows the seam is more expensive than a native Laravel search implementation for our actual query set, we say so and walk — and we will know that within two weeks, not two quarters.

The ask. Fund a two-week integration spike: stand up the bundle in a Symfony container, index a sample of CityGov content, and prove GraphQL person-search and online-service retrieval from the Laravel app. Deliverable is a go/no-go with a measured cost for the seam versus the native-Laravel alternative, plus a written support expectation from Sitepark. This is the cheapest possible way to convert a 0-star, single-vendor dependency into a decision we can defend on evidence.