Pet Store Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Install via Composer

   composer require common-gateway/pet-store-bundle:dev-main
   

   • Use dev-main for the latest features (or a stable tag if available).

2. Install Schemas

   php bin/console commongateway:install common-gateway/pet-store-bundle
   

   • This registers the bundle’s database schemas, routes, and configurations.

3. Admin UI Discovery

   • Navigate to the Plugins tab in the Common Gateway admin panel.
   • Search for PetStoreBundle, select it, and install via the UI (no manual config needed).

4. Verify Installation

   • Check if new routes (e.g., /api/pets) or admin UI sections appear.
   • Run php bin/console debug:router | grep pet to confirm route registration.

First Use Case: Extending Core Functionality

• Example: Add a custom pet management endpoint.
  • Override or extend the bundle’s PetController (located in src/Controller/).
  • Use the bundle’s event system (e.g., PetEvents::POST_CREATED) to hook into workflows.
  • Test with:

    php bin/console debug:event-dispatcher | grep Pet
    

Implementation Patterns

1. Bundle Structure as a Template

• Directory Layout:

  src/
  ├── Controller/       # Extend or replace controllers (e.g., PetController)
  ├── Entity/           # Define custom entities (e.g., Pet.php)
  ├── Event/            # Listen to/emit events (e.g., PetEvents)
  ├── Resources/config/ # Override services/routing (YAML/XML/PHP)
  ├── Migrations/       # Database schema changes (Doctrine)
  

• Key Files:
  • PetStoreBundle.php: Define dependencies (e.g., CommonGatewayCoreBundle).
  • Resources/config/routing.yaml: Add custom routes (e.g., pet_store.index).

2. Integration Workflows

A. Extending Core Features

• Hook into Events:

  // src/EventListener/PetListener.php
  namespace App\EventListener;
  
  use CommonGateway\PetStoreBundle\Event\PetEvents;
  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  
  class PetListener implements EventSubscriberInterface
  {
      public static function getSubscribedEvents(): array
      {
          return [
              PetEvents::POST_CREATED => 'onPetCreated',
          ];
      }
  
      public function onPetCreated(PetEvent $event): void
      {
          // Custom logic (e.g., send notification)
      }
  }
  

• Override Services:

  # config/services.yaml
  services:
      CommonGateway\PetStoreBundle\Service\PetManager:
          arguments:
              $logger: '@monolog.logger.pet_store'
  

B. Adding Custom Routes

# src/Resources/config/routing.yaml
pet_store_custom:
    path: /api/pets/custom
    controller: App\Controller\CustomPetController::index
    methods: [GET]

C. Database Migrations

• Use Doctrine migrations to add tables/columns:

  php bin/console make:migration
  php bin/console doctrine:migrations:migrate
  

3. Admin UI Integration

• The bundle auto-registers plugin metadata in the Plugins tab.
• Customize the admin UI by extending the bundle’s Resources/views/ templates or using Twig overrides.

Gotchas and Tips

Pitfalls

1. Schema Conflicts:

   • Running commongateway:install twice may cause duplicate schema errors.
   • Fix: Drop and recreate the schema or check Migrations/ for conflicts.

2. Event Dispatcher Order:

   • Events fired by PetStoreBundle may not trigger if the bundle isn’t loaded early.
   • Fix: Ensure PetStoreBundle is listed before your app bundle in config/bundles.php.

3. Route Prefix Collisions:

   • Default routes (e.g., /api/pets) may conflict with existing routes.
   • Fix: Override the route prefix in config/routing.yaml:

     common_gateway_pet_store:
         resource: "@PetStoreBundle/Resources/config/routing.yaml"
         prefix: "/custom-prefix"
     

4. Dev vs. Prod Dependencies:

   • Using dev-main in production may break stability.
   • Fix: Pin to a stable tag (e.g., 1.0.0) in composer.json.

Debugging Tips

• Check Bundle Loading:

  php bin/console debug:container | grep PetStoreBundle
  

• Enable Debug Events:

  php bin/console debug:event-dispatcher
  

• Log Schema Installation:

  php bin/console commongateway:install common-gateway/pet-store-bundle --verbose
  

Extension Points

1. Custom Entities:

   • Extend CommonGateway\PetStoreBundle\Entity\Pet or create new entities in your app.
   • Example:

     namespace App\Entity;
     
     use CommonGateway\PetStoreBundle\Entity\Pet as BasePet;
     
     class Pet extends BasePet
     {
         // Add custom fields/methods
     }
     

2. Plugin Metadata:

   • Override plugin metadata in config/packages/pet_store.yaml:

     common_gateway_pet_store:
         plugin:
             name: "Custom Pet Store"
             description: "Extended pet management"
             icon: "paw"
     

3. Command-Line Tools:

   • Create custom commands in src/Command/ to interact with the bundle’s data:

     php bin/console make:command ListPets