Extjs Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require amstaffix/extjs-bundle
   

   Enable the bundle in AppKernel.php:

   new Tpg\ExtjsBundle\TpgExtjsBundle(),
   

2. Basic Configuration Add to config.yml:

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

3. Routing Include in routing.yml:

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

4. First Use Case

   • Annotate an entity with @Extjs\Model (e.g., Acme\DemoBundle\Entity\Person).
   • Include the model generator script in your template:

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

   • Call the generated model in JavaScript:

     Ext.define('Acme.DemoBundle.Entity.Person', { ... });
     

Implementation Patterns

Dynamic Model Generation

• Workflow:

  1. Annotate entities with @Extjs\Model (e.g., @Extjs\Model @ORM\Entity).
  2. Include generateModel.js in your template to auto-generate ExtJS models from Doctrine entities.
  3. Use the extjs_model Twig extension to inject models:

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

• Integration Tips:

  • Partial Generation: Specify models via query string:

    <script src="/extjs/generateModel.js?model[]=Acme.DemoBundle.Entity.Person"></script>
    

  • Proxy Configuration: Define REST proxy paths in annotations:

    @Extjs\ModelProxy("/api/people")
    

Remoting Integration

• Workflow:

  1. Annotate controller actions with @Extjs\Annotation\Direct.
  2. Include remoteapi.js to enable ExtJS remoting:

  <script src="/extjs/remoteapi.js"></script>
  

  3. Call remote actions from ExtJS:

  Test.testAction({ id: 123, name: "John" });
  

  • Request Handling: Wrap parameters in an array if the action expects a Request object:

    public function testAction(Request $request) {
        $id = $request->query->get('id');
    }
    

• Integration Tips:

  • Use Symfony\Component\HttpFoundation\Request for complex queries.
  • Leverage JMS\Serializer for automatic data transformation.

REST Controller Generation

• Workflow:

  1. Generate a REST controller for an entity:

     php app/console generate:rest:controller --controller AcmeDemoBundle:People --entity AcmeDemoBundle:Person
     

  2. Configure fos_rest in config.yml:

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

  3. Include the generated routes in routing.yml:

     acmedemo_api_rest:
         resource: "@AcmeDemoBundle/Resources/config/routing.rest.yml"
         prefix: /api
         type: rest
     

• Integration Tips:

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

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

  • Serialization Groups: Define groups in entities for granular control:

    use JMS\Serializer\Annotation as Serializer;
    /**
     * @Serializer\Groups({"get", "list"})
     */
    private $name;
    

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2.3:

   • The bundle is designed for Symfony 2.3. Upgrading to newer Symfony versions may require patches or forks.
   • Workaround: Use a compatibility layer or consider modern alternatives like API Platform.

2. FOSRestBundle Dependency:

   • REST controller generation requires FOSRestBundle. Ensure it’s installed and configured:

     composer require friendsofsymfony/rest-bundle
     

   • Error: Missing tpg_extjs.serializer service if FOSRestBundle isn’t properly configured.

3. Annotation Conflicts:

   • @Extjs\Model and @Extjs\ModelProxy must be placed on the entity class. Conflicts may arise with other annotations (e.g., @ORM\Table).
   • Fix: Ensure annotations are in the correct order or use YAML/XML configurations.

4. Model Generation Caching:

   • Generated models aren’t cached by default. Repeated requests to generateModel.js may cause performance issues.
   • Tip: Cache the generated JavaScript output in your web server (e.g., Nginx proxy_cache).

5. Request Parameter Handling:

   • Actions expecting Request objects must wrap parameters in an array when calling from ExtJS:

     // Correct:
     Test.action({ param: "value" }); // Maps to $request->query->get('param')
     // Incorrect (if action expects Request):
     Test.action(param: "value"); // Fails silently or throws errors.
     

Debugging

1. 404 on /extjs/generateModel.js:

   • Verify the tpg_extjs route is included in routing.yml and the bundle is enabled.
   • Check: Run php app/console debug:router | grep extjs to confirm the route exists.

2. Serializer Errors:

   • Ensure all entity properties have JMS\Serializer annotations (e.g., @Type("string")).
   • Debug: Enable serializer debug mode in config.yml:

     jms_serializer:
         debug: true
     

3. ExtJS Console Errors:

   • Open browser dev tools (F12) to check for JavaScript errors in the generated models.
   • Common Issue: Missing Ext namespace or incorrect model paths (e.g., Acme.DemoBundle.Entity.Person vs. Acme/DemoBundle/Entity/Person).

Extension Points

1. Custom Model Transformers:

   • Extend the bundle’s Tpg\ExtjsBundle\Generator\ModelGenerator to modify generated models (e.g., add custom fields or methods).
   • Example:

     // src/Acme/ExtjsBundle/DependencyInjection/Compiler/ModelGeneratorPass.php
     public function process(ContainerBuilder $container) {
         $definition = $container->findDefinition('tpg_extjs.model_generator');
         $definition->addMethodCall('setCustomTransformer', [new Callback('acme_extjs.custom_model_transformer')]);
     }
     

2. Override Remote API Behavior:

   • Subclass Tpg\ExtjsBundle\Generator\RemoteApiGenerator to customize how remote actions are wired to Symfony controllers.

3. Add Custom Serialization Groups:

   • Extend the tpg_extjs.serializer service to include additional groups or metadata:

     services:
         tpg_extjs.serializer:
             class: Tpg\ExtjsBundle\Serializer\ExtjsSerializer
             arguments:
                 - ['@serializer', '@tpg_extjs.metadata_factory']
             calls:
                 - [addGroup, ['custom_group']]
     

4. Dynamic Proxy Paths:

   • Use a custom route generator to dynamically set proxy paths based on runtime logic:

     // src/Acme/ExtjsBundle/Routing/ProxyPathGenerator.php
     public function generateProxyPath(EntityManager $em, string $entityClass): string {
         return '/dynamic/api/' . strtolower(class_basename($entityClass));
     }
     

   • Register the service in services.yml and override the default proxy path logic.

Tips for Daily Use

1. Rapid Prototyping:

   • Use the generate:rest:controller command to scaffold CRUD operations quickly. Customize the generated controller later.

2. Twig Extensions:

   • Leverage {{ extjs_model() }} to dynamically load models in templates, reducing manual JavaScript includes.

3. Version Control:

   • Exclude generated files (e.g., web/extjs/generateModel.js) from version control. Use a build step to regenerate them.

4. Testing:

   • Test remoting endpoints with tools like Postman or ExtJS’s built-in proxy testing.
   • Example Test Case:

     public function testRemoteAction() {
         $client = static::createClient();
         $client->request('GET', '/