Base Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require clamidity/base-bundle
   

   Enable it in config/bundles.php (Symfony):

   return [
       // ...
       Clamidity\BaseBundle\ClamidityBaseBundle::class => ['all' => true],
   ];
   

2. First Use Case The bundle provides a BaseController trait for common CRUD operations. Extend it in your controller:

   use Clamidity\BaseBundle\Controller\BaseController;
   
   class ProductController extends AbstractController
   {
       use BaseController;
   
       protected $entityClass = Product::class;
   }
   

   • Automatically handles:
     • Index (GET /products)
     • Show (GET /products/{id})
     • Create (GET/POST /products/new)
     • Edit (GET/POST /products/{id}/edit)
     • Delete (DELETE /products/{id})

3. Where to Look First

   • Documentation: Check src/Resources/doc/ for usage examples.
   • Traits: Focus on BaseController and BaseEntity traits in src/Controller/ and src/Entity/.
   • Templates: Override Twig templates in templates/base/ (default location: src/Resources/views/).

Implementation Patterns

Core Workflows

1. Entity Management

   • BaseEntity Trait: Extend to add common methods like getId(), getCreatedAt(), etc.

     use Clamidity\BaseBundle\Entity\BaseEntity;
     
     class Product extends BaseEntity
     {
         // Your fields...
     }
     

   • Lifecycle Callbacks: Hook into prePersist(), preUpdate(), etc., via the trait.

2. Controller Integration

   • Custom Actions: Override methods from BaseController (e.g., createAction(), updateAction()).

     protected function createAction(Request $request)
     {
         $this->validateRequest($request); // Custom logic
         return parent::createAction($request);
     }
     

   • Form Handling: Use $this->createForm() and $this->getFormHandler() for DRY form logic.

3. Routing

   • Auto-Routing: The bundle generates routes for CRUD actions. Customize via YAML/XML/Attribute routes:

     # config/routes.yaml
     product:
         resource: 'product'
         type: 'clamidity_base'
         prefix: '/products'
     

4. Twig Integration

   • Templates: Override default templates by copying files from src/Resources/views/base/ to templates/base/.
   • Helpers: Use Twig extensions like base_path() or entity_url().

5. Services

   • BaseService: Extend Clamidity\BaseBundle\Service\BaseService for reusable logic:

     class ProductService extends BaseService
     {
         public function getActiveProducts()
         {
             return $this->repository->findBy(['active' => true]);
         }
     }
     

Integration Tips

• Doctrine: Works seamlessly with Doctrine ORM. Ensure your BaseEntity extends AbstractEntity (from the bundle).
• Validation: Use Symfony’s Validator component with the bundle’s form handling.
• Events: Dispatch custom events (e.g., postCreate, preDelete) via the EventDispatcher in your controllers/services.
• APIs: For APIs, extend BaseController and override methods to return JSON responses:

  public function indexAction()
  {
      $data = parent::indexAction();
      return $this->json($data);
  }
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • The bundle uses Clamidity\BaseBundle namespace. Avoid naming your classes/traits similarly to prevent collisions.
   • Fix: Use unique namespaces (e.g., App\Controller\ProductController).

2. Template Overrides

   • Forgetting to copy template files from src/Resources/views/base/ to templates/base/ will use the bundle’s defaults, which may not match your design.
   • Tip: Use {{ dump(app.request.uri) }} in Twig to debug template paths.

3. Entity Inheritance

   • If your BaseEntity extends the bundle’s trait but also Doctrine’s AbstractEntity, ensure the trait is loaded after Doctrine’s base class to avoid conflicts.
   • Fix: Use autoload-dev or composer dump-autoload after changes.

4. Route Conflicts

   • Auto-generated routes may clash with existing routes. Explicitly define route prefixes or use _prefix in YAML:

     product:
         resource: 'product'
         type: 'clamidity_base'
         _prefix: '/admin/products'
     

5. Form Handling Quirks

   • The bundle’s form handler assumes specific field names (e.g., id, createdAt). Customize via setFormOptions() in your controller:

     protected function getFormOptions()
     {
         return [
             'csrf_protection' => false, // Disable if using API
             'allow_extra_fields' => true,
         ];
     }
     

Debugging

1. Enable Debug Mode Set APP_DEBUG=true in .env to see detailed errors and template inheritance chains.

2. Log Events Dispatch custom events to track workflows:

   $this->eventDispatcher->dispatch(new BaseEvent('preCreate', $entity));
   

3. Check Route Debug Use Symfony’s route debugger (/debug/router) to verify auto-generated routes.

Extension Points

1. Custom Traits Extend BaseController or BaseEntity to add domain-specific logic:

   trait SoftDeletesTrait
   {
       public function delete()
       {
           $this->deletedAt = new \DateTime();
           $this->save();
       }
   }
   

2. Event Subscribers Listen to bundle events (e.g., base.entity.pre_persist) in your services.yaml:

   services:
       App\EventListener\ProductListener:
           tags:
               - { name: kernel.event_subscriber }
   

3. Override Services Replace the bundle’s services (e.g., base.repository) in config/services.yaml:

   Clamidity\BaseBundle\Repository\BaseRepository: '@app.custom_repository'
   

4. Add Fields Dynamically Use the BaseEntity trait’s getDynamicFields() to include computed properties in forms:

   public function getDynamicFields()
   {
       return ['fullName' => $this->getFirstName() . ' ' . $this->getLastName()];
   }
   

Performance Tips

• Eager-Loading: Use BaseRepository::findWith() to preload associations:

  $products = $this->repository->findWith(['category', 'images'], $criteria);
  

• Caching: Cache repository queries with Symfony’s cache component:

  $cache = $this->container->get('cache.app');
  $data = $cache->get('products_list', function() {
      return $this->repository->findAll();
  });