Extjs Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require asiragusa/extjs-bundle
   

   Ensure JMS\SerializerBundle and Tpg\ExtjsBundle are registered in AppKernel.php.

2. Basic Configuration (config.yml):

   tpg_extjs:
       entities:
           - "@YourBundle/Entity/"
       remoting:
           bundles:
               - YourBundle
   

3. Routing (routing.yml):

   tpg_extjs:
       resource: "@TpgExtjsBundle/Resources/config/routing.yml"
       prefix: /extjs
   

4. First Use Case:

   • Annotate an entity with @Tpg\ExtjsBundle\Annotation\Model (e.g., Acme\DemoBundle\Entity\Person).
   • Include the model generator in a Twig template:

     {{ extjs_model(true, 'Acme.DemoBundle.Entity.Person') }}
     

   • Verify the generated ExtJS model appears in the browser console.

Implementation Patterns

Dynamic Model Generation

• Workflow:

  1. Annotate entities with @Model and optionally @ModelProxy (e.g., @ModelProxy("/api/persons")).
  2. Include generateModel.js in your layout or template:

     <script src="{{ asset('/extjs/generateModel.js') }}"></script>
     

  3. ExtJS models are auto-generated at runtime based on Doctrine entities.

• Integration Tips:

  • Use the Twig extension extjs_model() to dynamically inject models:

    {{ extjs_model(false, 'Acme.DemoBundle.Entity.Person') }}  {# Script tag #}
    

  • For bulk generation, pass an array of namespaced entities:

    {{ extjs_model(true, ['Acme.DemoBundle.Entity.Person', 'Acme.DemoBundle.Entity.Book']) }}
    

Remoting Integration

• Workflow:

  1. Annotate controller actions with @Direct:

     use Tpg\ExtjsBundle\Annotation\Direct;
     
     class PersonController extends Controller {
         /**
          * @Direct
          */
         public function getPersonAction($id) { ... }
     }
     

  2. Include remoteapi.js in your template:

     <script src="{{ asset('/extjs/remoteapi.js') }}"></script>
     

  3. Call the remote action from ExtJS:

     App.PersonController.getPerson({ id: 123 });
     

• Handling Request Objects:

  • If an action expects Request $request, wrap parameters in an array:

    App.TestController.testRequestParam({ id: 12, name: "EFG" });
    

REST Controller Generation

• Workflow:

  1. Generate a REST controller for an entity:

     php app/console generate:rest:controller --controller YourBundle:Person --entity YourBundle:Person
     

  2. Configure fos_rest in config.yml:

     fos_rest:
         service:
             serializer: tpg_extjs.serializer
         routing_loader:
             default_format: json
     

  3. Include the generated routing in routing.yml:

     your_api:
         resource: "@YourBundle/Resources/config/routing.rest.yml"
         prefix: /api
         type: rest
     

• Trait Support (PHP 5.4+):

  • Use --trait flag to separate generated code from custom logic:

    php app/console generate:rest:controller --controller YourBundle:Person --entity YourBundle:Person --trait
    

  • This creates:
    • PersonControllerTrait (generated code).
    • PersonController (your custom implementation extending the trait).

Gotchas and Tips

Pitfalls

1. Serializer Configuration:

   • Ensure all entity properties have JMS Type annotations for deserialization to work (e.g., @Type("string")).
   • Example:

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

2. Routing Conflicts:

   • Prefix all ExtJS routes with /extjs to avoid conflicts with other bundles.
   • Example: /extjs/generateModel.js instead of /generateModel.js.

3. FOSRestBundle Dependency:

   • REST controller generation requires FOSRestBundle (≥0.12). If missing, use the --no-rest flag or install it first:

     composer require friendsofsymfony/rest-bundle
     

4. Model Proxy Paths:

   • Ensure @ModelProxy paths match your API routes (e.g., @ModelProxy("/api/persons") must align with routing.rest.yml).

Debugging

• Generated Model Issues:

  • Check the browser console for errors in generateModel.js. Common causes:
    • Missing @Model annotation on entities.
    • Incorrect namespace formatting (use dots . instead of slashes / in Twig calls).
  • Verify the entity is listed in tpg_extjs.entities config.

• Remoting Failures:

  • If @Direct actions fail, ensure:
    • The controller action is public.
    • Parameters are correctly wrapped in an array for Request objects.
    • The remoteapi.js script is loaded before ExtJS calls.

• REST Controller Debugging:

  • Test API endpoints manually (e.g., /api/persons) to isolate issues.
  • Check fos_rest logs for serialization/deserialization errors.

Tips

1. Partial Model Generation:

   • Generate models for specific entities dynamically:

     {{ extjs_model(true, 'Acme.DemoBundle.Entity.Person') }}
     

   • Avoid regenerating all models on every page load.

2. Caching Models:

   • ExtJS models are generated client-side. For large apps, consider:
     • Pre-generating models during build (e.g., with Gulp/Webpack).
     • Using Ext.define with static configurations for critical models.

3. Extending Remoting:

   • Customize remoteapi.js to add global remoting logic (e.g., auth headers):

     Ext.Ajax.defaultHeaders = {
         'X-Auth-Token': 'your_token'
     };
     

4. PHP 5.4 Traits:

   • Use traits to regenerate REST controllers without losing custom logic:

     php app/console generate:rest:controller --controller YourBundle:Person --trait
     

   • Extend the trait in your controller:

     class PersonController extends FOSRestController {
         use PersonControllerTrait;
     
         public function customAction() { ... }
     }
     

5. Testing:

   • Use the included PHPUnit/Jasmine tests to verify bundle functionality.
   • Mock generateModel.js responses in tests to avoid server dependencies.