First Registration Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation via Composer

   composer require common-gateway/first-registration-bundle:dev-main
   

   • Ensure your Laravel/Symfony project has Composer configured and the common-gateway base system is installed.

2. Run the Installation Command

   php artisan commongateway:install common-gateway/first-registration-bundle
   

   • This registers the bundle’s schemas and dependencies with the Common Gateway system.

3. Access the Plugin via Admin UI

   • Navigate to the Plugins tab in the Common Gateway admin dashboard.
   • Search for FirstRegistrationBundle, select it, and install it.

4. Verify Functionality

   • Check the Eerste Inschrijving (First Registration) workflow in your application’s relevant modules (e.g., user onboarding, registration forms).

First Use Case: Extending User Registration

• Use the bundle to hook into the first-time user registration flow (e.g., adding mandatory fields, validation, or post-registration actions).
• Example: Extend the User entity or create a custom FirstRegistration entity to store additional data (e.g., registration_date, source, or metadata).

Implementation Patterns

Workflow: Plugin Integration

1. Dependency Injection

   • The bundle provides services for first-registration logic. Inject them into your controllers/services:

     use CommonGateway\FirstRegistrationBundle\Service\FirstRegistrationService;
     
     public function __construct(FirstRegistrationService $firstRegistrationService) {
         $this->firstRegistrationService = $firstRegistrationService;
     }
     

2. Event Listeners

   • Listen to registration events (e.g., FirstRegistrationCreated) to trigger side effects:

     // src/EventListener/FirstRegistrationListener.php
     public function onFirstRegistration(FirstRegistrationEvent $event) {
         // Custom logic (e.g., send welcome email, log activity)
     }
     

   • Register the listener in config/services.php:

     'listeners' => [
         'first_registration.created' => [
             'App\EventListener\FirstRegistrationListener',
         ],
     ],
     

3. Custom Schemas

   • Extend the bundle’s schema (e.g., add fields to the registration form):

     # config/commongateway/first_registration.yaml
     fields:
         custom_field:
             type: text
             label: "Custom Field"
     

4. API/Controller Integration

   • Use the bundle’s controllers or create custom routes:

     Route::post('/register-first', [FirstRegistrationController::class, 'store']);
     

Laravel-Specific Tips

• Service Provider Binding Bind the bundle’s services in AppServiceProvider:

  public function register() {
      $this->app->bind(
          FirstRegistrationService::class,
          CommonGateway\FirstRegistrationBundle\Service\FirstRegistrationService::class
      );
  }
  

• Migrations The bundle may include migrations. Run:

  php artisan migrate
  

• Configuration Publish the bundle’s config:

  php artisan vendor:publish --provider="CommonGateway\FirstRegistrationBundle\FirstRegistrationBundle" --tag="config"
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • The bundle assumes the CommonGateway namespace. If your project uses similar namespaces, alias classes to avoid collisions:

     use CommonGateway\FirstRegistrationBundle\Service\FirstRegistrationService as BundleFirstRegistrationService;
     

2. Missing Dependencies

   • Ensure common-gateway/core or equivalent is installed. The bundle relies on its base functionality.

3. Schema Overrides

   • Custom schemas in config/commongateway/first_registration.yaml must match the bundle’s expected structure. Validate against the bundle’s default schema first.

4. Event Naming

   • Events like FirstRegistrationCreated are case-sensitive. Typos will break listeners.

5. Docker/Composer Permissions

   • If using Docker, ensure the php container has write permissions for vendor/ and config/.

Debugging

1. Check Logs

   • Enable debug mode (APP_DEBUG=true) and inspect storage/logs/laravel.log for bundle-related errors.

2. Console Commands

   • Verify installation with:

     php artisan commongateway:list
     

   • Reinstall if needed:

     php artisan commongateway:uninstall common-gateway/first-registration-bundle
     php artisan commongateway:install common-gateway/first-registration-bundle
     

3. Database Issues

   • If migrations fail, manually check the plugins and first_registration tables for inconsistencies.

Extension Points

1. Custom Validation

   • Override the bundle’s validator by extending its FirstRegistrationValidator class and binding it in AppServiceProvider.

2. API Extensions

   • Extend the bundle’s API endpoints by creating a custom controller and routing it before the bundle’s routes (higher priority in routes/web.php).

3. Frontend Integration

   • The bundle may include Twig templates. Override them in your theme’s templates directory (e.g., resources/views/vendor/first_registration/).

4. Testing

   • Use the bundle’s test utilities (if provided) or mock its services in PHPUnit:

     $this->app->instance(
         FirstRegistrationService::class,
         Mockery::mock(FirstRegistrationService::class)
     );
     

Config Quirks

• Environment Variables The bundle may rely on .env variables (e.g., COMMON_GATEWAY_FIRST_REGISTRATION_ENABLED). Set these explicitly if not auto-loaded.

• Caching Clear caches after schema/config changes:

  php artisan config:clear
  php artisan cache:clear
  

• Local Development Use dev-main branch for testing. Avoid stable tags if the bundle is actively developed.