Cursor rules file - Comprehensive development guidelines and best practices for building Bagisto 2.2 packages, covering modular architecture, view hooks, asset management, database patterns, and Vue.js integration.

laravel-bagisto-2.2.mdc

---
description: Bagisto 2.2
globs: *.php, *.js, *.html
alwaysApply: false
---

## General Guideline

- Use conventions and guidelines described in Bagisto 2.2 Documentation
- Use Bagisto and Laravel provided artisan commands for generating files as much as possible.
- Maintain Bagisto module structure (https://devdocs.bagisto.com/2.2/architecture/modular-design.html).

## Package Structure & Organization

### 1. **Standard Directory Structure**
- Follow Bagisto's modular structure with clear separation:
  ```
  packages/Vendor/Package/
  ├── src/
  │   ├── Config/           # Configuration files
  │   ├── Console/          # Artisan commands
  │   ├── Contracts/        # Interfaces
  │   ├── Database/         # Migrations and seeders
  │   ├── DataGrids/        # DataGrid definitions
  │   ├── Http/             # Controllers and middleware
  │   ├── Models/           # Eloquent models
  │   ├── Providers/        # Service providers
  │   ├── Repositories/     # Data access layer
  │   ├── Resources/        # Views, assets, and translations
  │   ├── Routes/           # Route definitions
  │   └── Services/         # Business logic
  ```

### 2. **Service Provider Registration**
- Use a main ServiceProvider and a separate ModuleServiceProvider for model registration
- Register configuration files using `mergeConfigFrom()` for admin-menu, acl, and system configs
- Load resources in the boot method (migrations, routes, translations, views)

## Asset Management

### 3. **Vite Configuration**
- Use Vite for building frontend assets with proper hot file configuration
- Configure build output to `themes/{package-name}/default/build`
- Reference parent directories correctly in `envDir` for shared environment variables

### 4. **Tailwind CSS Integration**
- Use minimal Tailwind configuration targeting only package-specific blade files
- Prefer built-in Tailwind classes over custom CSS

## Database & Models

### 5. **Extending Existing Models**
- When extending core models (like Order), use the same table and add specific fields via migrations
- Create scopes for package-specific queries (e.g., `scopeMyPackageOrders()`)
- Use boolean flags to identify package-specific records (e.g., `is_my_package_order`)

### 6. **Migration Strategy**
- Add package-specific fields to existing tables rather than creating new tables when appropriate
- Include proper indexes for performance (e.g., composite indexes on flag + frequently queried fields)
- Use nullable fields for optional package-specific data

## View Integration

### 7. **View Hooks Pattern**
- Use Bagisto's view hooks to integrate with existing pages without modifying core files
- Register view hooks conditionally based on context. For example:
  ```php
  Event::listen($hook, function ($viewRenderEventManager) {
      $order = $viewRenderEventManager->getParam('order');
      if ($order && $order->is_my_package_order) {
          $viewRenderEventManager->addTemplate('path/to/my_pkg_feature.blade.php');
      }
  });
  ```
- When attaching templates with view hooks, `$viewRenderEventManager` will automatically inject arguments provided in `view_render_event('template_name.blade', $argumentsArray)`.

### 8. **Blade Component Structure**
- Use `<x-admin::layouts>` and `<x-shop::layouts>` for consistent layouts
- Utilize built in blade components @https://devdocs.bagisto.com/2.2/packages/blade-components.html for designing interface where appropriate
- Create modular blade views for different events/features
- Separate JavaScript components using Vue.js templates

## API & AJAX

### 9. **RESTful API Design**
- Group API routes under `/api` prefix within the package routes
- Return consistent JSON responses with proper status codes
- Use Laravel's validation for request handling

### 10. **Session-based State Management**
- Use session storage for temporary state during multi-step processes
- Clear session data after successful operations

## Configuration

### 11. **System Configuration**
- Add package settings to Bagisto's system configuration
- Use channel-based and locale-based settings where appropriate
- Provide sensible defaults in configuration files

### 12. **ACL Integration**
- Define proper ACL permissions for package features
- Group permissions hierarchically (e.g., `mypkg`, `mypkg.new-order`, `mypkg.orders.spetial`)

## Vue.js Integration

### 13. **Component Registration**
- Register Vue components within blade templates using `@pushOnce('scripts')`
- Use template IDs for component templates (e.g., `id="v-pkg-app-template"`)
- Leverage Bagisto's existing Vue instance and utilities

### 14. **AJAX with Axios**
- Use `this.$axios` for API calls in Vue components
- Handle CSRF tokens automatically through Bagisto's setup
- Implement proper error handling and loading states

## Console Commands

### 15. **Custom Artisan Commands**
- Create package-specific commands for setup tasks (e.g., `mypkg:seed-channel`)
- Register commands conditionally when running in console
- Provide clear command descriptions and feedback

## Repository Pattern

### 16. **Service Layer Architecture**
- Separate business logic into service classes
- Use repository pattern for data access
- Inject dependencies through constructor for testability

## Error Handling

### 17. **Transaction Management**
- Wrap complex operations in database transactions
- Provide meaningful error messages
- Roll back transactions on failure

## Channels & Multi-tenancy

### 18. **Channel Support**
- Create package-specific channels when needed
- Link channels with appropriate locales and currencies
- Use channel configuration for package-specific settings

## Development Workflow

### 19. **Incremental Testing**
- Test each feature thoroughly before moving to the next (as per user preference)
- Use proper debugging tools and console logging during development
- Clear all caches after configuration changes

### 20. **Clean Code Practices**
- Use type declarations and strict types where possible
- Follow PSR standards for code formatting
- Document complex business logic with clear comments