Matakuliahbundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ais/matakuliahbundle:dev-master
   

   Ensure your composer.json includes the required dependencies (FOSRestBundle, JMSSerializerBundle, NelmioApiDocBundle).

2. Register the Bundle: Add to app/AppKernel.php:

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

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

   ais_matakuliahs:
     type: rest
     prefix: /api
     resource: "@AisMatakuliahBundle/Resources/config/routes.yml"
   

4. Verify API Docs: Access /api/doc to see the generated API documentation (requires NelmioApiDocBundle).

First Use Case: CRUD Operations

The bundle provides RESTful endpoints for Matakuliah (course) entities. Test with:

# Create a course
curl -X POST -H "Content-Type: application/json" -d '{
  "name": "Database Systems",
  "code": "CS401",
  "credits": 3
}' http://localhost/api/matakuliah

# Fetch all courses
curl http://localhost/api/matakuliah

# Fetch a single course
curl http://localhost/api/matakuliah/1

Implementation Patterns

Workflows

1. Entity Management:

   • Extend Ais\MatakuliahBundle\Entity\Matakuliah for custom fields or logic.
   • Use Doctrine ORM for database operations (e.g., @ORM\Entity annotations).

2. API Integration:

   • Leverage FOSRestBundle for request/response handling (e.g., @Route("/matakuliah", name="matakuliah_list")).
   • Customize serialization with JMS\Serializer (e.g., @Serializer\ExclusionPolicy("ALL")).

3. Validation:

   • Add constraints to Matakuliah entity (e.g., @Assert\NotBlank for required fields).
   • Use FOSRestBundle's FormHandler for validation in controllers.

4. Testing:

   • Write functional tests with LiipFunctionalTestBundle (dev dependency).
   • Mock API calls using Guzzle (dev dependency).

Integration Tips

1. Database Migrations:

   • Generate migrations for Matakuliah entity:

     php app/console doctrine:schema:update --force
     

2. Custom Controllers:

   • Override default controllers by extending Ais\MatakuliahBundle\Controller\MatakuliahController.

3. Event Listeners:

   • Subscribe to Doctrine lifecycle events (e.g., prePersist) for business logic:

     // src/Acme/AppBundle/EventListener/MatakuliahListener.php
     use Doctrine\Common\EventSubscriber;
     use Doctrine\ORM\Event\LifecycleEventArgs;
     
     class MatakuliahListener implements EventSubscriber {
         public function prePersist(LifecycleEventArgs $args) { ... }
     }
     

4. API Documentation:

   • Extend NelmioApiDocBundle annotations for custom API docs:

     # app/config/config.yml
     nelmio_api_doc:
         areas: { path_patterns: ["^/api"] }
     

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch:

   • The bundle targets Symfony 2.7. Avoid mixing with newer versions (e.g., 3.x/4.x) without forks.
   • Fix: Use a compatible fork or create a wrapper bundle.

2. Missing Dependencies:

   • NelmioApiDocBundle, FOSRestBundle, and JMSSerializerBundle are required but not auto-installed.
   • Fix: Manually add them to composer.json and AppKernel.php.

3. Route Conflicts:

   • The /api/matakuliah prefix may clash with existing routes.
   • Fix: Customize routing.yml or use route namespaces.

4. Serialization Issues:

   • Custom Matakuliah fields may break JMS\Serializer if not annotated.
   • Fix: Add @Serializer\Type("string") or @Serializer\ExclusionPolicy.

Debugging Tips

1. Enable Profiler:

   # app/config/config_dev.yml
   framework:
       profiler: { only_exceptions: false }
   

   Access /_profiler to inspect requests/responses.

2. Doctrine Logging:

   // app/config/config_dev.yml
   doctrine:
       orm:
           logging: true
   

   Logs appear in var/log/doctrine.log.

3. API Response Validation:

   • Use bin/console debug:router to verify routes.
   • Test with curl -v for HTTP headers/body inspection.

Extension Points

1. Custom Fields:

   // src/Acme/AppBundle/Entity/ExtendedMatakuliah.php
   use Ais\MatakuliahBundle\Entity\Matakuliah;
   
   class ExtendedMatakuliah extends Matakuliah {
       /**
        * @ORM\Column(type="string")
        * @Serializer\Type("string")
        */
       private $customField;
   }
   

2. Business Logic:

   • Override MatakuliahController methods (e.g., postAction).
   • Use Doctrine listeners for pre/post operations.

3. API Extensions:

   • Add new endpoints by extending routes.yml:

     # src/Acme/AppBundle/Resources/config/routing.yml
     acme_matakuliah_extended:
         type: rest
         resource: "@AcmeAppBundle/Resources/config/routing.yml"
     

4. Testing:

   • Mock MatakuliahRepository in unit tests:

     $repository = $this->getMockBuilder('Ais\MatakuliahBundle\Entity\MatakuliahRepository')
         ->disableOriginalConstructor()
         ->getMock();