Citygov Bundle Laravel Package

Getting Started

Minimal Setup for Laravel/Symfony Integration

Since this is a Symfony bundle, Laravel developers must bridge it via Symfony components or a Laravel-Symfony bridge (e.g., symfony/panther for testing or laravel-symfony-bridge for partial integration). For a true Laravel workflow, focus on its core features (search, GraphQL, content indexing) and adapt them via:

1. Composer Dependency

   composer require sitepark/atoolo-citygov-bundle
   

   Note: Requires Symfony 6.3+ or a Laravel-Symfony interop layer.

2. Configuration Add to config/bundles.php (Symfony) or manually register services in Laravel’s AppServiceProvider:

   // config/bundles.php (Symfony)
   return [
       Sitepark\Atoolo\CityGovBundle\CityGovBundle::class => ['all' => true],
   ];
   

3. First Use Case: Searchable Employee Directory Leverage the search & suggest for citygov persons (v1.5.0) feature:

   // Symfony Controller Example (adapt for Laravel)
   use Sitepark\Atoolo\CityGovBundle\Service\PersonSearchService;
   
   class EmployeeController extends AbstractController
   {
       public function search(PersonSearchService $personSearch): Response
       {
           $results = $personSearch->search('John Doe', ['sort' => 'name']);
           return $this->json($results);
       }
   }
   

   Laravel Alternative: Use the underlying atoolo/search-bundle (dependency) via a facade or service container.

4. GraphQL Online Services Enable the OnlineServiceFeature (v1.4.0) for headless service APIs:

   # Example GraphQL Query (Symfony)
   query {
     onlineServices {
       id
       title
       link
     }
   }
   

   Laravel Integration: Use graphql-php to mirror the schema.

5. Content Indexing Automate SEO-friendly URLs with index-document generation (v1.4.0):

   # config/packages/atoolo_citygov.yaml (Symfony)
   atoolo_citygov:
       index_documents:
           enabled: true
           alternate_titles: ['English', 'Français']
   

Implementation Patterns

1. Search Workflows

Pattern: Faceted Search for Municipal Data

• Use Case: Search across employees, services, and documents with filters (e.g., department, service type).
• Implementation:
  • Extend PersonSearchService for custom filters:

    $results = $personSearch->search(
        'term',
        ['filters' => ['department' => 'HR'], 'sort' => 'last_name']
    );
    

  • Integrate with Solr/Elasticsearch via atoolo/search-bundle:

    $searchClient = $this->container->get('atoolo_search.client');
    $query = new \Atoolo\SearchBundle\Query\SearchQuery();
    $query->addCriteria('name', 'John');
    $results = $searchClient->search($query);
    

Pattern: Autocomplete/Suggest

• Use Case: Real-time search suggestions for service names or employee names.
• Implementation:

  use Sitepark\Atoolo\CityGovBundle\Service\PersonSuggestService;
  
  $suggestions = $personSuggestService->suggest('Jo', 5);
  // Returns: ['John Doe', 'Joanna Smith', ...]
  

2. GraphQL API for Headless Services

Pattern: Online Service Portal

• Use Case: Expose city services (e.g., permits, tax payments) via GraphQL for mobile apps or chatbots.
• Implementation:
  • Enable the OnlineServiceFeature in Symfony:

    # config/packages/atoolo_citygov.yaml
    atoolo_citygov:
        graphql:
            online_service_feature: true
    

  • Query services:

    query {
      onlineServices(limit: 10) {
        edges {
          node {
            id
            title
            description
            link
          }
        }
      }
    }
    

  • Laravel: Use graphql-php to define a similar schema:

    $schema = new \GraphQL\Type\Definition\ObjectType([
        'name' => 'OnlineService',
        'fields' => [
            'title' => ['type' => Type::string()],
            'link' => ['type' => Type::string()],
        ],
    ]);
    

3. Content Management

Pattern: SEO-Friendly URL Generation

• Use Case: Automatically generate index documents for alternate language titles (e.g., German/French).
• Implementation:

  # config/packages/atoolo_citygov.yaml
  atoolo_citygov:
      index_documents:
          enabled: true
          alternate_titles: ['English', 'Français']
  

  • Triggers Solr indexing for each alternate title, improving multilingual SEO.

Pattern: Document Enrichment

• Use Case: Add metadata (e.g., sp_meta_string_leikanumber) to documents for government compliance.
• Implementation:

  use Sitepark\Atoolo\CityGovBundle\EventListener\DocumentEnricher;
  
  // Symfony Event Listener (adapt for Laravel)
  public function onDocumentEnrich(DocumentEnrichEvent $event)
  {
      $event->getDocument()->setMeta('leikanumber', '12345');
  }
  

4. Personnel Management

Pattern: Employee Directory with Sorting

• Use Case: Search employees with custom sort criteria (e.g., last_name, department).
• Implementation:

  $results = $personSearch->search(
      'term',
      ['sort' => ['field' => 'department', 'direction' => 'asc']]
  );
  

5. Integration with Laravel

Pattern: Service Container Bridge

• Use Case: Use Symfony services in Laravel via service container.
• Implementation:

  // In AppServiceProvider::boot()
  $this->app->singleton(PersonSearchService::class, function ($app) {
      return new PersonSearchService(
          $app->make('atoolo_search.client'),
          // ... other dependencies
      );
  });
  

Pattern: API Resource Wrappers

• Use Case: Expose bundle features via Laravel API Resources.
• Implementation:

  namespace App\Http\Resources;
  
  use Sitepark\Atoolo\CityGovBundle\Entity\Person;
  use Illuminate\Http\Resources\Json\JsonResource;
  
  class PersonResource extends JsonResource
  {
      public function toArray($request)
      {
          return [
              'name' => $this->name,
              'department' => $this->department,
              'phone' => $this->phoneNumber, // Fixed in v1.5.0
          ];
      }
  }
  

Gotchas and Tips

1. Symfony-Specific Pitfalls

Gotcha: Bundle Registration

• Issue: Laravel lacks bundles.php; Symfony bundles won’t auto-register.
• Fix: Manually register services in AppServiceProvider:

  public function register()
  {
      $this->app->register(\Sitepark\Atoolo\CityGovBundle\CityGovBundle::class);
  }
  

  Alternative: Use spatie/laravel-symfony-bridge for partial integration.

Gotcha: Event Listeners

• Issue: Symfony’s EventDispatcher isn’t natively in Laravel.
• Fix: Use Laravel’s events or wrap Symfony listeners:

  // Symfony Listener (e.g., DocumentEnricher)
  public static function getSubscribedEvents()
  {
      return [
          DocumentEnrichEvent::class => 'onDocumentEnrich',
      ];
  }
  

  Laravel Alternative: Dispatch a custom event:

  event(new DocumentEnriching($document));
  

2. Search and Indexing Quirks

Gotcha: Solr/Elasticsearch Dependencies

• Issue: The bundle assumes Solr (via atoolo/search-bundle). Elasticsearch requires custom config.
• Fix: Override the search client in Symfony: