Citygov Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to your composer.json:

   composer require sitepark/atoolo-citygov-bundle
   

   Enable in config/bundles.php:

   return [
       // ...
       Sitepark\Atoolo\CityGovBundle\CityGovBundle::class => ['all' => true],
   ];
   

2. Configure Required Dependencies Ensure atoolo/search-bundle and atoolo/resource-bundle are installed (handled automatically via composer require). Verify Solr/Elasticsearch is configured in config/packages/atoolo_search.yaml:

   atoolo_search:
       clients:
           default:
               type: solr
               host: 'http://solr:8983/solr'
               core: 'citygov'
   

3. First Use Case: Indexing Municipal Content Use the ContentCollector to index documents (e.g., ordinances, event listings):

   use Sitepark\Atoolo\CityGovBundle\Collector\CityGovContentCollector;
   
   $collector = $container->get(CityGovContentCollector::class);
   $collector->collect($resource); // Pass a `ResourceInterface` (e.g., `Page`, `Document`)
   

4. Search for Persons (v1.5.0+) Leverage the search API for employee directories:

   use Sitepark\Atoolo\CityGovBundle\Search\PersonSearch;
   
   $search = new PersonSearch($searchClient);
   $results = $search->search('John Doe', ['sort' => 'lastName']);
   

Implementation Patterns

Core Workflows

1. Content Enrichment for SEO

Extend DocumentEnricher to add metadata (e.g., sp_meta_string_leikanumber for Swiss/German compliance):

use Sitepark\Atoolo\CityGovBundle\Enricher\CityGovDocumentEnricher;

class CustomEnricher extends CityGovDocumentEnricher {
    public function enrich($document, $resource) {
        $document->set('sp_meta_string_leikanumber', $resource->getLeikaNumber());
        return parent::enrich($document, $resource);
    }
}

Register in services.yaml:

services:
    Sitepark\Atoolo\CityGovBundle\Enricher\DocumentEnricher:
        class: App\Enricher\CustomEnricher

2. GraphQL for Online Services (v1.4.0+)

Query online services via GraphQL:

query {
    onlineServices {
        id
        title
        description
        link
    }
}

Use the OnlineServiceFeature resolver:

use Sitepark\Atoolo\CityGovBundle\GraphQL\OnlineServiceFeature;

$feature = new OnlineServiceFeature($linkFactory);
$services = $feature->getOnlineServices();

3. Personnel Directory Search (v1.5.0+)

Implement a search controller:

use Sitepark\Atoolo\CityGovBundle\Search\PersonSearch;

class PersonSearchController extends AbstractController {
    public function search(Request $request, PersonSearch $personSearch) {
        $query = $request->query->get('q');
        $results = $personSearch->search($query, [
            'sort' => $request->query->get('sort', 'lastName'),
            'limit' => 10
        ]);
        return $this->json($results);
    }
}

4. Multi-Lingual Content Handling

Use ResourceLocation and ResourceLanguage for translations:

use Sitepark\Atoolo\CityGovBundle\Model\ResourceLocation;

$location = new ResourceLocation();
$location->setLanguage('de_CH'); // Swiss German
$location->setTitle('Verwaltung');
$resource->addLocation($location);

Integration Tips

Solr/Elasticsearch Schema

Extend the default schema to include CityGov-specific fields:

<!-- solrconfig.xml -->
<field name="sp_meta_string_leikanumber" type="string" indexed="true" stored="true"/>
<field name="startletter" type="string" indexed="true" stored="true" multiValued="false"/>

Event Listeners for Automation

Trigger indexing on resource updates:

use Sitepark\Atoolo\CityGovBundle\Event\CityGovIndexEvent;

class IndexOnUpdateListener {
    public function onResourceUpdate(CityGovIndexEvent $event) {
        $collector = $event->getContainer()->get(CityGovContentCollector::class);
        $collector->collect($event->getResource());
    }
}

Register in services.yaml:

services:
    App\EventListener\IndexOnUpdateListener:
        tags:
            - { name: kernel.event_listener, event: atoolo.resource.update, method: onResourceUpdate }

Link Factory for Online Services

Use LinkFactory to generate compliant URLs (v1.5.0+):

use Sitepark\Atoolo\CityGovBundle\Service\LinkFactory;

$linkFactory = $container->get(LinkFactory::class);
$serviceUrl = $linkFactory->createOnlineServiceLink($serviceId);

Gotchas and Tips

Pitfalls

1. Schema Mismatches

   • Issue: Solr/Elasticsearch fields (e.g., startletter) may not map correctly if the schema isn’t updated.
   • Fix: Rebuild the index after schema changes:

     php bin/console atoolo:search:reindex
     

2. Deprecated Namespaces

   • Issue: Some classes use SiteKitSchema21 (deprecated in favor of SiteKitSchema2x).
   • Fix: Update imports in custom code:

     // Old (deprecated)
     use Sitepark\Atoolo\CityGovBundle\Schema\SiteKitSchema21;
     
     // New
     use Sitepark\Atoolo\CityGovBundle\Schema\SiteKitSchema2x;
     

3. Missing Resource Argument

   • Issue: ContentCollector may fail if the ResourceInterface lacks required arguments (e.g., getLeikaNumber()).
   • Fix: Implement missing methods or extend the resource class:

     class CustomResource implements ResourceInterface {
         public function getLeikaNumber() {
             return $this->leikaNumber ?? null;
         }
     }
     

4. PHP 8.4+ Compatibility

   • Issue: Some type hints may break in PHP 8.4 due to strict checks.
   • Fix: Use null coalescing or @phpstan-ignore-line:

     $value = $resource->getField() ?? null;
     

5. GraphQL Over-Fetching

   • Issue: Queries for OnlineServiceFeature may return excessive data.
   • Fix: Use fragments or custom resolvers to limit fields:

     fragment OnlineServiceTeaser on OnlineService {
         id
         title
         teaser
     }
     

Debugging Tips

1. Check Indexing Logs Enable debug mode for atoolo/search-bundle:

   # config/packages/dev/atoolo_search.yaml
   atoolo_search:
       debug: true
   

2. Validate Solr Queries Use the Solr admin UI (http://solr:8983/solr/#/citygov/query) to test queries manually.

3. Person Search Sorting If sort criteria (e.g., lastName) fail, verify the field exists in Solr:

   curl "http://solr:8983/solr/citygov/schema/fields?show=lastName"
   

4. Link Factory Errors Debug URL generation:

   $linkFactory = $container->get(LinkFactory::class);
   try {
       $url = $linkFactory->createOnlineServiceLink($serviceId);
   } catch (\Exception $e) {
       // Log or rethrow with context
       throw new \RuntimeException('Invalid service ID: ' . $serviceId, 0, $e);
   }
   

Extension Points

1. Custom Document Enrichment Override CityGovDocumentEnricher to add domain-specific fields:

   class CustomEnricher extends CityGovDocumentEnricher {
       public function enrich($document, $resource) {
           $document->set('custom_field', $this->getCustomData($resource));
           return parent::enrich($document, $resource);
       }
   }
   

2. **