Wisudabundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package to composer.json under require:

   "ais/wisudabundle": "dev-master"
   

   Run:

   composer update ais/wisudabundle
   

2. Register the Bundle Add to AppKernel.php:

   new Ais\WisudaBundle\AisWisudaBundle(),
   

   Ensure dependencies (NelmioApiDocBundle, FOSRestBundle, JMSSerializerBundle) are also registered.

3. Configure Routing Add to app/config/routing.yml:

   ais_wisudas:
     type: rest
     prefix: /api
     resource: "@AisWisudaBundle/Resources/config/routes.yml"
   

4. First Use Case Access the API docs at:

   http://localhost/web/app_dev.php/api/doc
   

   Explore endpoints under /api/wisuda.

Implementation Patterns

API-Driven Workflows

• RESTful Endpoints: Leverage the bundle’s pre-defined routes (e.g., GET /api/wisuda, POST /api/wisuda). Example: Fetch all wisuda records:

  curl -X GET http://localhost/api/wisuda
  

• Request/Response Handling Use FOSRestBundle for request/response transformations. Example:

  // In a controller
  use FOS\RestBundle\Controller\FOSRestController;
  use FOS\RestBundle\View\View;
  
  class WisudaController extends FOSRestController {
      public function getWisudasAction() {
          $wisudas = $this->getDoctrine()->getRepository('AisWisudaBundle:Wisuda')->findAll();
          return $this->handleView(View::create($wisudas));
      }
  }
  

• Serialization Configure jms_serializer in config.yml to handle entity serialization:

  jms_serializer:
      metadata:
          directories:
              AisWisudaBundle:
                  namespace_prefix: "Ais\\WisudaBundle\\Entity"
                  path: "%kernel.root_dir%/config/serializer/AisWisudaBundle"
  

Integration with Doctrine

• Entity Management Extend the Wisuda entity (located in AisWisudaBundle/Entity/Wisuda.php) or create custom repositories:

  namespace Ais\WisudaBundle\Entity;
  
  use Doctrine\ORM\Mapping as ORM;
  
  /**
   * @ORM\Entity(repositoryClass="Ais\WisudaBundle\Entity\WisudaRepository")
   */
  class Wisuda {
      // ...
  }
  

• Fixtures for Testing Use doctrine-fixtures-bundle to seed test data:

  php app/console doctrine:fixtures:load --env=test
  

API Documentation

• NelmioApiDocBundle Automatically generates Swagger docs. Customize annotations in controllers:

  /**
   * @ApiDoc(
   *   resource=true,
   *   description="Get all wisuda records",
   *   output="Ais\WisudaBundle\Entity\Wisuda"
   * )
   */
  public function getWisudasAction() { ... }
  

Gotchas and Tips

Common Pitfalls

1. Symfony Version Mismatch The bundle targets Symfony 2.7.4. Avoid mixing with newer Symfony versions (e.g., 3.x/4.x) without forks or patches. Fix: Use a compatible Symfony version or fork the bundle.

2. Missing Dependencies NelmioApiDocBundle, FOSRestBundle, and JMSSerializerBundle are required. Forgetting to register them causes:

   • API docs not loading (/api/doc returns 404).
   • Serialization errors. Fix: Ensure all dependencies are in AppKernel.php and composer.json.

3. Route Conflicts The bundle’s rest route prefix (/api) may clash with other bundles. Fix: Override routing in routing.yml or use unique prefixes:

   ais_wisudas_custom:
     prefix: /custom-api
     resource: "@AisWisudaBundle/Resources/config/routes.yml"
   

4. Entity Namespace Issues The bundle assumes entities are under Ais\WisudaBundle\Entity. Custom entities must mirror this structure. Fix: Adjust jms_serializer metadata or use aliases:

   jms_serializer:
       metadata:
           directories:
               CustomBundle:
                   namespace_prefix: "AppBundle\Entity"
                   path: "%kernel.root_dir%/config/serializer/CustomBundle"
   

Debugging Tips

• Check API Docs First Always verify /api/doc works before debugging endpoints. Missing docs often indicate routing or bundle registration issues.

• Enable Debug Mode Symfony’s debug toolbar (_profiler) reveals:

  • Doctrine queries (slow queries stand out).
  • Serialization errors (e.g., circular references).
  • Twig/Assetic issues (if using frontend features).

• Log Serialization Errors Enable jms_serializer logging in config.yml:

  jms_serializer:
      handlers:
          date_handler:
              type: datetime
          array_collection_handler:
              type: array_collection
      metadata:
          debug: "%kernel.debug%"
  

Extension Points

1. Custom Controllers Override bundle controllers by creating a WisudaController in your bundle:

   // src/AppBundle/Controller/WisudaController.php
   namespace AppBundle\Controller;
   use Ais\WisudaBundle\Controller\WisudaController as BaseWisudaController;
   
   class WisudaController extends BaseWisudaController {
       public function customAction() { ... }
   }
   

   Update routing to point to your controller.

2. Event Listeners Hook into lifecycle events (e.g., prePersist) via Symfony’s event dispatcher:

   // src/AppBundle/EventListener/WisudaListener.php
   namespace AppBundle\EventListener;
   use Doctrine\ORM\Event\LifecycleEventArgs;
   use Ais\WisudaBundle\Entity\Wisuda;
   
   class WisudaListener {
       public function prePersist(Wisuda $wisuda, LifecycleEventArgs $args) {
           $wisuda->setCreatedAt(new \DateTime());
       }
   }
   

   Register in services.yml:

   services:
       app.wisuda_listener:
           class: AppBundle\EventListener\WisudaListener
           tags:
               - { name: doctrine.event_listener, event: prePersist, entity: Ais\WisudaBundle\Entity\Wisuda }
   

3. Custom Fields Extend the Wisuda entity with new fields:

   /**
    * @ORM\Column(type="string", length=255)
    */
   private $customField;
   

   Update jms_serializer metadata to include the new field.

Performance Quirks

• Eager-Loading Associations Avoid N+1 queries by configuring fetch in Doctrine:

  $query->leftJoin('wisuda.user', 'u')->addSelect('u');
  

• Caching API Docs NelmioApiDocBundle caches docs. Clear cache after changes:

  php app/console cache:clear