Mozaic Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer config extra.symfony.allow-contrib true
   composer require disjfa/mozaic-bundle
   

   Ensure your composer.json includes the bundle in the extra.bundles section.

2. Environment Setup: Add Unsplash API credentials to .env:

   UNSPLASH_APPLICATION_ID=your_id
   UNSPLASH_APPLICATION_SECRET=your_secret
   

3. Basic Usage:

   • The bundle integrates with Webpack Encore for Vue.js components.
   • Load a Vue component in your JavaScript:

     import { MozaicComponent } from 'mozaic-bundle';
     new Vue({
         el: '#app',
         components: { MozaicComponent }
     });
     

   • Ensure your webpack.config.js is configured to handle Encore and Vue.

4. First Use Case: Use the bundle to fetch and display Unsplash images dynamically in a Vue component. Example:

   <mozaic-component :query="'nature'" :count="10"></mozaic-component>
   

Implementation Patterns

Workflows

1. Vue Component Integration:

   • Extend the MozaicComponent to customize behavior (e.g., filtering, pagination).
   • Example:

     // CustomComponent.vue
     export default {
         extends: MozaicComponent,
         props: ['customFilter'],
         methods: {
             fetchImages() {
                 this.$parent.fetchImages(this.customFilter);
             }
         }
     };
     

2. API Interaction:

   • The bundle abstracts Unsplash API calls. Override methods like fetchImages() to inject custom logic:

     methods: {
         async fetchImages(query) {
             const response = await this.$http.get(`/api/images?query=${query}`);
             this.images = response.data;
         }
     }
     

3. Symfony Integration:

   • Use Symfony’s Twig to pass dynamic data to Vue:

     <div id="app" data-images="{{ images|json_encode }}"></div>
     

   • Fetch data in Vue’s mounted() lifecycle hook:

     mounted() {
         this.images = JSON.parse(this.$el.dataset.images);
     }
     

4. Webpack Encore:

   • Ensure your webpack.config.js includes:

     Encore
         .enableVueLoader(() => {}, { version: 3 })
         .addEntry('app', './assets/js/app.js')
         .splitEntry('./assets/js/mozaic.js')
         .enableSingleRuntimeChunk();
     

Tips for Daily Use

• Lazy Loading: Dynamically load the MozaicComponent only when needed:

  if (document.getElementById('mozaic-container')) {
      import('./mozaic-component').then(component => {
          new Vue({ components: { MozaicComponent: component.MozaicComponent } }).$mount('#mozaic-container');
      });
  }
  

• State Management: Use Vuex for complex state (e.g., caching fetched images):

  // store.js
  export default new Vuex.Store({
      state: { images: [] },
      mutations: { SET_IMAGES(state, images) { state.images = images; } }
  });
  

• Testing: Mock Unsplash API responses in unit tests:

  // test.js
  const mockImages = [{ id: 1, urls: { raw: 'mock-url' } }];
  global.$http = { get: jest.fn().mockResolvedValue({ data: mockImages }) };
  

Gotchas and Tips

Pitfalls

1. Recipe Dependency:

   • The bundle relies on symfony/recipes-contrib. If recipes fail, manually configure:

     # config/packages/mozaic.yaml
     mozaic:
         unsplash:
             enabled: true
     

   • Ensure your composer.json has:

     "extra": {
         "symfony": {
             "allow-contrib": true
         }
     }
     

2. Webpack Encore Compatibility:

   • If Vue components fail to load, verify:
     • node_modules are installed (npm install).
     • Encore is properly configured (check public/build/ for compiled assets).
   • Clear cache after changes:

     yarn build --watch
     

3. API Rate Limits:

   • Unsplash API has rate limits. Cache responses in Symfony:

     # config/packages/cache.yaml
     framework:
         cache:
             app: cache.adapter.redis
     

4. Vue 2 vs. Vue 3:

   • The bundle assumes Vue 2. For Vue 3, alias imports in webpack.config.js:

     resolve: {
         alias: {
             vue$: 'vue/dist/vue.esm-bundler.js'
         }
     }
     

Debugging

• Console Errors:

  • Check browser console for 403 (API errors) or 404 (missing assets). Validate .env and Unsplash credentials.
  • Use console.log(this.$options) in components to inspect props/methods.

• Symfony Logs:

  • Enable debug mode (APP_DEBUG=1) and check var/log/dev.log for API request failures.

Extension Points

1. Custom API Endpoint: Override the Unsplash service in Symfony:

   # config/services.yaml
   services:
       App\Service\CustomUnsplashService:
           arguments:
               $clientId: '%env(UNSPLASH_APPLICATION_ID)%'
               $clientSecret: '%env(UNSPLASH_APPLICATION_SECRET)%'
   

   Bind it in the bundle’s configuration.

2. Component Slots: Extend the Vue component to support slots:

   // MozaicComponent.vue
   template: `
       <div>
           <slot name="header"></slot>
           <div v-for="image in images" :key="image.id">
               <img :src="image.urls.raw" />
               <slot name="footer" :image="image"></slot>
           </div>
       </div>
   `;
   

3. Server-Side Rendering (SSR): Use Symfony’s Twig to pre-render components:

   <div id="app" data-images="{{ images|json_encode }}">
       {% include 'mozaic/_component.html.twig' %}
   </div>
   

   Hydrate with Vue in JavaScript:

   new Vue({
       el: '#app',
       data() { return { images: JSON.parse(this.$el.dataset.images) } }
   });
   

4. Legacy Support: For Symfony 3.4, pin dependencies in composer.json:

   "require": {
       "php": "~5.5.9|~7.0",
       "symfony/symfony": "3.4.*"
   }