Ruangbundle Laravel Package

Getting Started

Minimal Setup

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

   "require": {
       "ais/ruangbundle": "dev-master"
   }
   

   Run composer update to install dependencies.

2. Register the Bundle Add Ais\RuangBundle\AisRuangBundle() to your AppKernel.php under registerBundles():

   new Ais\RuangBundle\AisRuangBundle(),
   

3. Enable Required Dependencies Ensure these bundles are also registered (required by ais-ruangbundle):

   new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
   new FOS\RestBundle\FOSRestBundle(),
   new JMS\SerializerBundle\JMSSerializerBundle(),
   

4. Configure Routing Add the bundle’s routes to app/config/routing.yml:

   ais_ruangs:
       type: rest
       prefix: /api
       resource: "@AisRuangBundle/Resources/config/routes.yml"
   

5. Access API Documentation Visit /api/doc (e.g., http://localhost/web/app_dev.php/api/doc) to explore the API endpoints via NelmioApiDocBundle.

First Use Case: CRUD Operations

The bundle likely provides RESTful endpoints for "Ruang" (Indonesian for "space" or "room"). Test a basic GET request to fetch all resources:

curl -X GET http://localhost/web/app_dev.php/api/ruangs

Expected response: A JSON array of Ruang entities (if the bundle follows standard FOSRest conventions).

Implementation Patterns

Common Workflows

1. RESTful API Development

   • Use FOSRestBundle annotations (e.g., @Route, @Get, @Post) to define endpoints in controllers.
   • Example:

     use FOS\RestBundle\Controller\Annotations\Route;
     use FOS\RestBundle\Controller\Annotations\Get;
     
     /**
      * @Route("/ruangs/{id}", name="get_ruang")
      * @Get()
      */
     public function getRuangAction($id) {
         // Fetch and return a single Ruang entity
     }
     

2. Serialization with JMS

   • Annotate entities with @JMS\Serializer\Annotation\Type for automatic JSON serialization:

     use JMS\Serializer\Annotation as Serializer;
     
     class Ruang {
         /**
          * @Serializer\Type("string")
          */
         private $name;
     }
     

3. Documentation-Driven Development

   • Use NelmioApiDocBundle to auto-generate Swagger/OpenAPI docs. Annotate controllers for metadata:

     /**
      * @ApiDoc(
      *   resource=true,
      *   description="Returns a list of Ruang entities",
      *   output="Ais\RuangBundle\Entity\Ruang[]"
      * )
      */
     

4. Form Handling with FOSRest

   • Use FOS\RestBundle\Form\Handler\AbstractFormHandler for form submission:

     $formHandler = new FormHandler($this->get('form.factory'), $this->get('request'), $ruang, $formType);
     if ($formHandler->process()) {
         // Handle success
     }
     

Integration Tips

• Doctrine ORM: The bundle uses Doctrine 2.4+. Ensure your Ruang entity extends Doctrine\ORM\Mapping\Entity and is mapped in config.yml:

  doctrine:
      orm:
          entity_managers:
              default:
                  mappings:
                      AisRuangBundle: ~
  

• Assetic for Assets: If the bundle includes frontend assets (e.g., CSS/JS), configure AsseticBundle in config.yml:

  assetic:
      bundles: [AisRuangBundle]
  

• SwiftMailer: For email-related features, configure swiftmailer in config.yml:

  swiftmailer:
      transport: %mailer_transport%
      host: %mailer_host%
      username: %mailer_user%
      password: %mailer_password%
  

Gotchas and Tips

Pitfalls

1. Symfony 2.7 Dependency

   • The bundle is hardcoded for Symfony 2.7.4. Avoid upgrading Symfony without testing compatibility.
   • Workaround: Fork the repo and update dependencies if needed.

2. Missing Dependencies

   • NelmioApiDocBundle, FOSRestBundle, and JMSSerializerBundle are required but not auto-installed. Add them manually to composer.json:

     "nelmio/api-doc-bundle": "^3.0",
     "friendsofsymfony/rest-bundle": "^2.0",
     "jms/serializer-bundle": "^1.0"
     

3. Route Conflicts

   • The bundle’s routes.yml may conflict with existing routes. Prefix routes explicitly:

     ais_ruangs:
         prefix: /api/v1
     

4. Dev-Master Instability

   • The package is in dev-master. Expect breaking changes. Pin a specific commit in composer.json:

     "ais/ruangbundle": "dev-commit-hash"
     

Debugging Tips

1. Enable Profiler Add %kernel.debug%: true to app/config/parameters.yml to access Symfony’s profiler for debugging routes/controllers.

2. Check Doctrine Mappings Run php app/console doctrine:schema:validate to ensure entities are mapped correctly.

3. API Doc Issues Clear the cache if docs fail to load:

   php app/console cache:clear
   

Extension Points

1. Custom Entities Extend the Ruang entity by overriding its methods or adding new fields. Example:

   namespace Ais\RuangBundle\Entity;
   
   class CustomRuang extends Ruang {
       /**
        * @ORM\Column(type="string")
        */
       private $customField;
   }
   

2. Event Listeners Use Symfony’s event system to hook into lifecycle events (e.g., prePersist):

   // src/Ais/RuangBundle/EventListener/RuangListener.php
   class RuangListener {
       public function onPrePersist(Ruang $ruang) {
           $ruang->setCreatedAt(new \DateTime());
       }
   }
   

   Register the listener in services.yml:

   services:
       ais_ruang.listener.ruang:
           class: Ais\RuangBundle\EventListener\RuangListener
           tags:
               - { name: doctrine.event_listener, event: prePersist }
   

3. Custom Controllers Override bundle controllers by creating a Controller directory in your bundle and using override: true in services.yml:

   services:
       ais_ruang.controller.ruang:
           class: Your\Bundle\Controller\RuangController
           parent: ais_ruang.controller.ruang_base
           tags: ['controller.service_arguments']