Coffee Php Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to composer.json:

   composer require dlancea/coffee-php-bundle:dev-master
   

   Register in AppKernel.php:

   new DLancea\CoffeePhpBundle\DLanceaCoffeePhpBundle(),
   

2. First Use Case Create a .coffee file (e.g., app.coffee) in your Resources/assets/coffee/ directory. Reference it in Twig with the coffeephp filter:

   {% javascripts filter='coffeephp' '@AcmeBundle/Resources/assets/coffee/app.coffee' %}
       <script src="{{ asset_url }}"></script>
   {% endjavascripts %}
   

   Clear cache:

   php bin/console cache:clear --env=prod
   

Implementation Patterns

Workflow Integration

1. Asset Organization

   • Store .coffee files in a dedicated directory (e.g., Resources/assets/coffee/).
   • Use Assetic’s javascripts tag with the coffeephp filter to compile and bundle them.

2. Twig Integration

   • Single File Compilation:

     {% javascripts filter='coffeephp' '@AcmeBundle/Resources/assets/coffee/module.coffee' %}
         <script src="{{ asset_url }}"></script>
     {% endjavascripts %}
     

   • Multiple Files with Dependencies:

     {% javascripts
         filter='coffeephp'
         '@AcmeBundle/Resources/assets/coffee/base.coffee'
         '@AcmeBundle/Resources/assets/coffee/extension.coffee'
     %}
         <script src="{{ asset_url }}"></script>
     {% endjavascripts %}
     

3. Debugging Mode

   • In dev environment, Assetic generates separate files for each .coffee input (useful for debugging).
   • Use {% javascripts ... %} without filter in dev to verify raw .coffee loading.

4. Custom Compilation Logic

   • Override the filter in a custom Assetic extension if needed (see Assetic documentation).

Gotchas and Tips

Pitfalls

1. Cache Dependencies

   • Forgetting to clear the cache (php bin/console cache:clear) after adding/updating .coffee files will result in stale JavaScript output.
   • Fix: Use --env=prod explicitly for production cache clearing.

2. Assetic Configuration Conflicts

   • If Assetic is misconfigured (e.g., incorrect debug or use_controller settings), the coffeephp filter may fail silently.
   • Fix: Verify config.yml:

     assetic:
         debug:          "%kernel.debug%"
         use_controller: false
     

3. File Permissions

   • The compiled JavaScript files are written to app/cache/{env}/assetic/. Ensure the web server user has write permissions.
   • Fix: Run chmod -R 775 app/cache.

4. CoffeeScript Syntax Errors

   • Unlike Node.js, this bundle does not provide real-time error feedback for invalid CoffeeScript.
   • Fix: Validate .coffee files using an online compiler (e.g., CoffeeScript REPL) before integrating.

Debugging Tips

1. Inspect Compiled Output

   • Check the generated JavaScript in app/cache/{env}/assetic/ to verify compilation.
   • Use browser dev tools to confirm the script loads and executes.

2. Log Filter Output

   • Enable Assetic debug mode (debug: true in config.yml) to log filter execution:

     assetic:
         debug: true
     

3. Fallback for Complex Projects

   • For large projects, consider using a hybrid approach:
     • Compile .coffee files to .js in a build step (e.g., GitHub Actions).
     • Serve the pre-compiled .js files in production.

Extension Points

1. Custom Compiler Options

   • The underlying coffeescript-php library supports options like bare: true (remove wrapper function).
   • How to Use: Extend the filter by subclassing DLancea\CoffeePhpBundle\Assetic\Filter\CoffeePhpFilter and override compile():

     class CustomCoffeePhpFilter extends CoffeePhpFilter {
         protected function compile($code) {
             return parent::compile($code, ['bare' => true]);
         }
     }
     

   • Register the custom filter in services.yml:

     services:
         custom.coffeephp.filter:
             class: AppBundle\Assetic\Filter\CustomCoffeePhpFilter
             tags:
                 - { name: assetic.filter, alias: coffeephp }
     

2. Pre/Post-Processing

   • Chain the coffeephp filter with others (e.g., uglifyjs) for minification:

     {% javascripts filter='coffeephp,uglifyjs' '@AcmeBundle/Resources/assets/coffee/app.coffee' %}
         <script src="{{ asset_url }}"></script>
     {% endjavascripts %}