Todomvc Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (if not archived, use composer require dunglas/todomvc-bundle).

   composer require dunglas/todomvc-bundle
   

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       Dunglas\TodoMVCBundle\DunglasTodoMVCBundle::class => ['all' => true],
   ];
   

3. Configure Dependencies (if not auto-loaded): Ensure FOSRestBundle, JMSSerializerBundle, and DunglasAngularCsrfBundle are installed and enabled.

   composer require friendsofsymfony/rest-bundle jms/serializer-bundle dunglas/angular-csrf
   

4. Run Migrations (if using Doctrine):

   php bin/console doctrine:migrations:migrate
   

5. First Use Case:
   • Access / to see the TodoMVC frontend (Backbone.js/Chaplin.js).
   • Test the REST API at /api/todos (returns JSON via FOSRestBundle).

Where to Look First

• Backend: src/Dunglas/TodoMVCBundle/Resources/config/routing.yml (API routes).
• Frontend: Resources/public/js/ (CoffeeScript/Backbone/Chaplin source).
• Entities: src/Dunglas/TodoMVCBundle/Entity/Todo.php (Doctrine model).
• Serialization: Resources/config/serializer/Todo.yml (JMS Serializer config).

Implementation Patterns

Core Workflows

1. CRUD Operations:

   • Create: POST /api/todos with JSON body { "title": "Task" }.
   • Read: GET /api/todos (filters: ?filter=active|completed|all).
   • Update: PUT/PATCH /api/todos/{id} with { "completed": true }.
   • Delete: DELETE /api/todos/{id}.

2. Frontend Integration:

   • Chaplin Router: Extend TodoMVCBundle:Default:index for custom routes.

     # Resources/public/js/app.coffee
     class TodoMVC.App extends Chaplin.Controller
       initialize: ->
         @listenTo @, "route:todos", ->
           @fetchTodos()
     

   • Backbone Models/Views: Override TodoMVC.Model.Todo or TodoMVC.View.TodoItem.

3. API Customization:

   • Extend Entities: Create a custom Todo entity extending Dunglas\TodoMVCBundle\Entity\Todo.
   • Add Fields: Update Todo.yml in Resources/config/serializer/:

     Dunglas\TodoMVCBundle\Entity\Todo:
       exclusion_policy: ALL
       properties:
         id:
           expose: true
         title:
           expose: true
         priority:  # Custom field
           expose: true
     

4. CSRF Protection:

   • Include the token in Angular/Backbone requests:

     headers: {
       'X-CSRF-Token': angular.element('meta[name="csrf-token"]').attr('content')
     }
     

Integration Tips

• Symfony Forms: Use FOSRestBundle's form handlers for hybrid API/form apps.
• Event Listeners: Hook into todo.pre_persist/todo.post_remove via Symfony events.

  // src/EventListener/TodoListener.php
  public function onTodoPrePersist(TodoEvent $event) {
      $todo = $event->getTodo();
      $todo->setCreatedAt(new \DateTime());
  }
  

• Testing:
  • Backend: Use Symfony\Bundle\FrameworkBundle\Test\WebTestCase.
  • Frontend: PhantomJS + Jasmine (pre-configured in Resources/tests/).

Gotchas and Tips

Pitfalls

1. CSRF Mismatches:

   • Issue: Backbone/Angular requests fail with 403 Forbidden.
   • Fix: Ensure DunglasAngularCsrfBundle is configured and tokens are included in headers.
   • Debug: Check meta[name="csrf-token"] exists in the HTML response.

2. Serialization Conflicts:

   • Issue: Custom fields don’t appear in API responses.
   • Fix: Verify serializer/Todo.yml includes the field and exclusion_policy is ALL or the field is explicitly exposed.
   • Debug: Run php bin/console debug:serializer Dunglas\TodoMVCBundle\Entity\Todo.

3. Chaplin Router Conflicts:

   • Issue: Frontend routes break after extending the bundle.
   • Fix: Override the Chaplin app in Resources/public/js/app.coffee and ensure TodoMVC.App is initialized last.

4. Doctrine Migrations:

   • Issue: Schema updates fail due to missing migrations.
   • Fix: Run php bin/console doctrine:migrations:diff and migrate after adding custom fields.

Debugging Tips

• API Debugging:
  • Use bin/console debug:router to list routes.
  • Check bin/console debug:serializer for serialization issues.
• Frontend Debugging:
  • Enable Chaplin debug mode in app.coffee:

    Chaplin.debug = true
    

  • Inspect network requests in Chrome DevTools (filter by XHR).

Extension Points

1. Custom Fields:

   • Add fields to Todo entity and update Todo.yml:

     properties:
       dueDate:
         type: DateTime
         exposed: true
     

   • Update the Backbone model in Resources/public/js/models/todo.coffee.

2. Authentication:

   • Integrate with LexikJWTAuthenticationBundle or FOSUserBundle:

     # config/packages/security.yaml
     firewalls:
         api:
             pattern: ^/api
             stateless: true
             jwt: ~
     

3. Alternative Frontend:

   • Replace Backbone/Chaplin with React/Vue by:
     • Extending the API endpoints.
     • Mounting a custom frontend at / (ensure it doesn’t conflict with index.html).

4. Testing:

   • Mock the API in frontend tests:

     // Jasmine test
     beforeEach(inject(function($httpBackend) {
       $httpBackend.whenGET('/api/todos').respond([{ id: 1, title: 'Test' }]);
     }));