Backend Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require companyos/backend
   php bin/console backend:install
   

   • Runs migrations (if any) and sets up default assets.

2. First Use Case: Dashboard

   • Access /admin to see the pre-built dashboard.
   • No backend logic needed—just a frontend template ready for API integration.

3. Where to Look First

   • config/packages/companyos_backend.yaml: Core configuration (e.g., API endpoints, theme defaults).
   • assets/: VueJS + CoreUI source files (modify here for customization).
   • templates/: Twig templates for server-side rendering (e.g., login page).

Implementation Patterns

1. API Integration

• Pattern: Consume a Symfony API (e.g., companyos/core-bundle) via Axios.

  // Example: assets/js/api.js
  import axios from 'axios';
  const api = axios.create({
    baseURL: '/api', // Configured in backend.yaml
  });
  export default api;
  

• Workflow:
  1. Define API routes in your backend bundle (e.g., src/Controller/AdminController).
  2. Call them from Vue components using the api.js instance above.
  3. Use Vue’s ref or reactive to manage state.

2. Modular Admin Pages

• Pattern: Extend the sidebar and routes dynamically.

  # config/packages/companyos_backend.yaml
  companyos_backend:
      admin:
          routes:
              - { path: '/users', component: 'Users', icon: 'cil-user' }
  

• Integration Tips:
  • Place Vue components in assets/js/pages/ (e.g., Users.vue).
  • Use webpack.config.js to ensure assets are bundled correctly.

3. Theme Customization

• Pattern: Override CoreUI themes via SASS variables.

  // assets/scss/coreui/_variables.scss
  $theme-colors: (
    'primary': #4e73df,
    'danger': #fd7e14
  );
  

• Workflow:
  1. Extend the default _variables.scss in your project.
  2. Rebuild assets:

     npm run dev
     

4. Authentication Flow

• Pattern: Use Symfony’s security component + Vuex for state.

  // assets/js/store/auth.js
  import { createStore } from 'vuex';
  export default createStore({
    state: { user: null },
    mutations: {
      SET_USER(state, user) { state.user = user; },
    },
  });
  

• Integration:
  • Hook into Symfony’s login/logout events via EventDispatcher.
  • Redirect to /admin after login (configure in security.yaml).

Gotchas and Tips

Pitfalls

1. Asset Pipeline Issues

   • Gotcha: Forgetting to run npm install or npm run dev after modifying assets/.
   • Fix: Ensure webpack.config.js is configured to watch your project’s assets/ directory.

2. API Endpoint Mismatches

   • Gotcha: Hardcoding API URLs in Vue components instead of using the config.
   • Fix: Always use the baseURL from backend.yaml (injected via Twig or Webpack).

3. Vue 3 + Symfony Twig Conflicts

   • Gotcha: Mixing Twig syntax with Vue’s v-bind or v-on without proper escaping.
   • Fix: Use Twig’s {{ app.importmap }} to avoid conflicts:

     {# templates/base.html.twig #}
     <script src="{{ asset('js/app.js') }}" type="module"></script>
     

4. Plugin System (Alpha Limitation)

   • Gotcha: The plugin system is incomplete; manual integration required.
   • Tip: Use Symfony’s EventDispatcher to trigger custom events for extensibility.

Debugging

• Vue DevTools: Install the Vue DevTools browser extension to inspect the Vue app state.
• Symfony Profiler: Enable WebProfilerBundle to debug API calls and Twig rendering.

Extension Points

1. Custom Components

   • Override CoreUI components by extending the assets/js/coreui/ directory.
   • Example: Replace the default Card.vue with your version.

2. Webpack Overrides

   • Extend webpack.config.js to add custom loaders or plugins:

     module.exports = {
       // ...
       plugins: [
         new VueLoaderPlugin(),
         new MiniCssExtractPlugin(),
       ],
     };
     

3. API Response Handling

   • Centralize API error handling in a Vue plugin:

     // assets/js/plugins/api-error-handler.js
     export default {
       install(app) {
         app.config.globalProperties.$handleApiError = (error) => {
           // Custom logic (e.g., show toast)
         };
       },
     };