bluefly/recipe_onboarding

OpenAPI-driven onboarding and migration engine for Drupal recipes and modules, providing guided tours and automated setup processes.

Maintainers

Details

gitlab.bluefly.io/llm/drupal/recipe_onboarding

Homepage

Source

Issues

Installs: 0

Dependents: 0

Suggesters: 0

Security: 0

Type:drupal-module

dev-main / 1.x-dev 2025-06-04 00:41 UTC

Requires

  • php: >=8.1
  • drupal/alternative_services: ^1.0
  • drupal/core: ^10 || ^11
  • drupal/eca: ^1.0
  • drupal/field_eca_bridge: ^1.0
  • drupal/llm: ^1.0
  • drupal/migrate_plus: ^6.0
  • drupal/migrate_tools: ^6.0
  • drupal/tour: ^1.0
  • langchain/langchain: ^0.1.0
  • symfony/yaml: ^6.0

Requires (Dev)

Suggests

  • drupal/admin_toolbar: Enhanced admin experience
  • drupal/alternative_services: Provides alternative AI service providers for recipe generation
  • drupal/eca: Event-driven automation for recipe processing
  • drupal/field_eca_bridge: Enables ECA workflows for field-level automation in recipes
  • drupal/recipe_marketplace: Integrates with Recipe Marketplace to provide guided installation of marketplace recipes

GPL-2.0-or-later 1b79c9ffc94cf865e5743627e7a45da8c4859022

wizardmigrationdrupaltouropenapirecipeonboarding

This package is auto-updated.

Last update: 2025-06-04 00:41:11 UTC

README

Recipe Onboarding is a reusable, OpenAPI-driven onboarding, migration, and guided tour engine for Drupal 10/11. It provides a composable, pluggable framework for building onboarding wizards, migration flows, and interactive admin tours—powered by OpenAPI, TDD, and AI/analytics hooks.

Drupal Test Coverage TDD Methodology API Status

  • Extracted from: cannabis_platform_wizard (2024)
  • Intended for: Any Drupal distribution, recipe, or module needing world-class onboarding, migration, or guided tours.
  • Integrated with: llm_platform_recipe to provide advanced wizard interfaces and recipe handling.

Features

  • Multi-step onboarding wizard (UI + API):

    • Pluggable step system with dependency management
    • Stateful wizard progress tracking
    • Responsive, accessible UI with real-time validation

  • OpenAPI contract for all endpoints (Dredd/CI ready):

    • Comprehensive API documentation
    • Standardized request/response formats
    • Authentication and authorization controls

  • Pluggable step registration (via hooks/plugins):

    • Custom step plugins for any functionality
    • Easy extension by other modules
    • Declarative step definitions with annotations

  • Migration mapping and preview (AI-ready):

    • Visual field mapping interface
    • Preview capability for migration results
    • Integration with Drupal's migration system

  • Guided admin tours and contextual help:

    • Step-by-step guided tours
    • Context-aware help content
    • Interactive tooltips and walkthroughs

  • Export/import onboarding flows as YAML "recipes":

    • Shareable configuration as code
    • Version-controlled recipe definitions
    • Environment-specific recipe variants

  • Analytics, event, and ECA integration:

    • Progress tracking and analytics
    • Event-driven workflows with ECA module
    • Customizable triggers and actions

Requirements

  • Drupal ^10 or ^11
  • PHP >= 8.1
  • Dependencies:
    • Tour (drupal/tour)
    • Migrate Plus (drupal/migrate_plus)
    • Migrate Tools (drupal/migrate_tools)

Installation

  1. Install the module via Composer:
    composer require drupal/recipe_onboarding
  2. Enable the module either via the Drupal UI (Extend page) or Drush:
    drush en recipe_onboarding -y

Configuration

Configure the Recipe Onboarding module at: /admin/config/recipe/onboarding (Administration > Configuration > Workflow > Recipe Onboarding Wizard)

Architecture

  • Controller: Handles API endpoints and step sequencing
  • OpenAPI Spec: Documents all onboarding/migration endpoints
  • Hooks/Plugins: Allow other modules/recipes to register steps, API, and tours
  • TDD: Unit, functional, kernel, and contract tests

Usage

Basic Usage

  1. Enable recipe_onboarding module
  2. Navigate to the Recipe Onboarding dashboard at /admin/config/recipe/onboarding
  3. Follow the wizard steps to complete the onboarding process
  4. Configure recipe settings as needed
  5. Apply recipes to your Drupal site

Programmatic Usage

// Get the recipe manager service
$recipeManager = \Drupal::service('recipe_onboarding.recipe_engine');

// Apply a recipe programmatically
$result = $recipeManager->applyRecipe('default', [
  'site_name' => 'My Recipe Site',
  'environment' => 'development',
]);

// Check the result
if ($result->isSuccessful()) {
  \Drupal::messenger()->addStatus(t('Recipe applied successfully!'));
}

Command Line Usage

# List available recipes
drush recipe:list

# Apply a recipe
drush recipe:apply default --site-name="My Site" --environment=development

# Check environment compatibility
drush recipe:check-environment

Extending

Recipe Onboarding is designed to be extended by other modules. You can add custom steps, recipes, and integrations.

Adding Custom Steps

  1. Create a plugin implementing SetupStepInterface in your module:
/**
 * @SetupStep(
 *   id = "my_custom_step",
 *   label = @Translation("My Custom Step"),
 *   description = @Translation("Description of my custom step"),
 *   weight = 10,
 *   category = "default"
 * )
 */
class MyCustomStep extends SetupStepBase {

  /**
   * {@inheritdoc}
   */
  public function buildForm(array $form, FormStateInterface $form_state) {
    $form['example'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Example field'),
      '#required' => TRUE,
    ];
    
    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function submitForm(array &$form, FormStateInterface $form_state) {
    $this->state->set('my_module.example', $form_state->getValue('example'));
  }
}
  1. Clear caches to register your new step:
drush cr

Adding Custom Recipes

Create a YAML file in your module's config/install directory:

# my_module.recipe.my_custom_recipe.yml
id: my_custom_recipe
label: 'My Custom Recipe'
description: 'A custom recipe for my module'
version: '1.0.0'
steps:
  - welcome
  - environment_check
  - my_custom_step
  - configuration
  - final_summary
dependencies:
  - core
  - user
  - node
  - my_module

API Integration

Recipe Onboarding provides a comprehensive API for integrating with other systems. See the API Documentation for details.

For integration examples in various languages and environments, see Integration Examples.

Services

Core Services

  • recipe_onboarding.environment_detection: Detects environment and adapts configuration
  • recipe_onboarding.recipe_engine: Manages recipe loading, adapting, and application
  • recipe_onboarding.wizard_builder: Builds wizard UI components with consistent UX
  • recipe_onboarding.validation: Validates recipes and configuration

Integration with llm_platform_recipe

The module provides foundational services that are leveraged by the llm_platform_recipe module:

  • LivingRecipeEngine in llm_platform_recipe uses the RecipeEngine service to handle basic recipe operations
  • EnhancedLLMOnboardingWizard uses the WizardBuilder service for UI components
  • Both modules work together to provide a comprehensive recipe-based installation and configuration system

Documentation

Testing

The module follows a strict Test-Driven Development (TDD) methodology:

# Run PHPUnit tests
./vendor/bin/phpunit --group=recipe_onboarding

# Run specific test classes
./vendor/bin/phpunit --filter=RecipeEngineTest

# Run API contract tests with Dredd
dredd openapi/recipe_onboarding.openapi.yml http://localhost/api/recipe-onboarding

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Write tests before implementation (TDD)
  4. Implement your changes
  5. Submit a pull request

Ensure that all tests pass and code meets Drupal coding standards.

License

GPL-2.0-or-later

Maintainers

This module is maintained by the Drupal Recipe Onboarding team.

Related Modules